API access to sports data with the SDQL


NBA, WNBA, NCAABB, NFL, NCAAFB, CFL, NHL, MLB, ATP, Premier League, Danish Superliga, Scottish Premiership, FIFA, WFIFA, UEFA, UFC, UFCW

Open Source Tools

Ubuntu is the operating system and philosophy. NginX is the http server. Facebook's Tornado serves as the web framework and holds the PyQL databases in RAM. The Python Programming Language is happily used throughout.

Data API

The SDQL3 Data API has two parts: POST requests are used to update a sports database and GET requests are used for SDQL queries into a sports database.

Post requests are made to and require headers of: user, token, league, action . Allowed values for action are: update, replace, and remove. The POST payload is a specialized JSON dictionary describing a sports game. The main specialization consists of using the parameter prefx 't:' for team stats and 'o:' for opponent stats. Stats that are not team specific, like `date`, do not need a parameter prefix. Another specialization is that a list of dictionaries is used to specify player-level data.

To post a JSON dictionary for the game on March 10, 2020 when the Bulls hosted the Cavaliers and won 108 to 103, use the JSON request:

header: { "token": "YOUR_TOKEN",
          "user": "YOUR_USERNAME",
          "league": "NBA",
          "action": "replace" }

data: { "date": 20200310,
        "t:team": "Bulls",
        "o:team": "Cavaliers",
        "t:site": "home",
        "o:site": "away",
        "t:points": 108,
        "o:points": 103,
        "t:Players": [{"name":"Coby White","points":20,"minutes":38.0},
                      {"name":"Denzel Valentine","points":15,"minutes":22.7},
        "o:Players": [{"name":"Collin Sexton","points":26,"minutes":36.5},
                      {"name":"Andre Drummond","points":21,"minutes":34.5},

Where the ... means to make a dictionary for every player.

In order to locate the game in the database, all sports have required data keys of: date, t:team, o:team. For baseball the key double header is also required.

Databases are updated with any freshly uploaded files every hour on the hour.

GET requests are made to When making a GET request the following headers are required: user, token. The GET request is made with a JSON dictionary describing a query. The only required dictionary key is: sdql. To get the win-loss record of the Chicago Blackhawks in 2019, use the JSON request:

header: { "token": "YOUR_TOKEN",
          "user": "YOUR_USERNAME"}
data: {"sdql": "S(W),S(L)@team='Chicago Blackhawks' and season=2019"}

Settings API

The settings API has two parts: POST requests are used to manage your data sharing and GET requests are used simply to check your settings.

Post requests are made to https://YOUR_SITE/sapi and require headers of: user and token.

The data dictionary can have any fields and more controls are coming. Two important fields for data sharing are 'follow' and 'invite'. These both take a list of user names as arguments. The default value for both is ["*"], and this means invite everyone and follow everyone. For Beta testing the 'invite' setting will be stuck on ["*"].

For `Joe` to invite `Bob` and `Alice`, they would make the API call:

header: { "token": "Joe_Token",
          "user": "Joe"}
data: {"invite": ["Bob","Alice"]}

For `Joe` to only see their own data, they would make the API call:

header: { "token": "Joe_Token",
          "user": "Joe"}
data: {"follow": ["Joe"]}

Data fields are seached hierarchically based on 'follow' settings. For `Joe` to first check their own data and to use `Alice` for any missing games or fields, they would make the API call:

header: { "token": "Joe_Token",
          "user": "Joe"}
data: {"follow": ["Joe","Alice"]}
and make sure `Alice` is inviting.

You can call the SDQL API from a browser by setting your CORS domain. For 'Joe' to set their CORS domain to '', they would make the API call:

header: { "token": "Joe_Token",
          "user": "Joe"}
data: {"CORS domain": ""}


The Sports Data Query Language Manual 3.0

Share and grow your knowledge of the SDQL at the discussion group.

Learn about the SDQL API at the API discussion group.

e-mail links:   
Content for this site is generated using the Sports Data Query Language (SDQL).