## Getting Started
Sportradar brings together a whole conference of application programming interfaces (APIs) to give you access to all the sports data you need for your website applications and mobile apps.
There are two steps to getting started with Sportradar APIs. The first is to get your API Key. This key identifies your account and application to the API and is needed for any API calls.
Second, once you have your keys, you need to understand how to call the Sportradar APIs. You don't need to write any code to get started. Instead, you can use our API Sandbox to test those calls against our live sports data.
To use the API Sandbox:
Select the API you want to view from the dropdown.
Enter your API key in the field.
Select your desired feed and adjust the parameters to your needs.
Click Try It.
Our APIs are separated by sport to account for differing structures and statistics tracked. We also provide League Specific and General Sport APIs for some sports played globally. Click on a sport on the left side of the screen to view documentation for our available APIs and versions.
Sportradar APIs are organized around RESTful structure. APIs are accessible through HTTP GET requests, using intuitive URLs and responses are available in both JSON and XML formats.
Note: Sportradar's APIs are a B2B (Business-to-Business) service and are not intended to be called directly from a client application.
The documentation for every API includes the following:
Statistics Summary: A high-level overview of all the data points provided within the whole API.
Documentation (Statistics Feeds): Provides a list of endpoints for the API with basic descriptions of what each endpoint does. This document also includes descriptions of each data point and its location. Finally, general FAQ questions are answered at the end of the document.
API Maps: Structural maps to aid you in navigating the APIs endpoints.
Syntax Info: Instructions on how to access each endpoint within an API.
Schema Info: Schema definitions are provided for each endpoint. OpenAPI specs are included when applicable.
Code Examples: View code examples for each endpoint in the right column. You can switch the programming language of the examples with the tabs in the top right.
Frequently Asked Questions: A concise list of FAQs specific to this sports data.
## League Specific APIs and General Sport APIs
To further support major US sports and sports played globally, we have created League Specific and General Sport APIs formats.
League Specific API format (NFL, NBA, MLB, NHL, and more) provides the greatest depth of coverage available for the given league with the broadest set of statistics that we offer. For all League Specific APIs, we provide most (if not all) events with full play-by-play coverage, as well as scores and statistics in near real time. Further information about coverage for these leagues can be found in the Coverage Levels documentation. We’ve structured these APIs to be tailored to the sport, providing you with the best experience when integrating our data.
General Sport API format (Global American Football, Global Baseball, Global Basketball, Global Ice Hockey, and more) provides a breadth of coverage across numerous leagues worldwide. All General Sport APIs follow a consistent structure and format between sports, making it easy to consume the data across different leagues or competitions. Coverage for a given league, competition, or sport event within these General Sport APIs can vary. Coverage information for a league or sport event can be found by calling the Schedule or Summaries feeds.
## Authentication
> Below is an example call to the NFL API v5 using API key authentication:
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/nfl/official/trial/v5/en/games/2019/reg/schedule.xml?api_key={your_api_key}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body
```
```python
import http.client
conn = http.client.HTTPSConnection("api.sportradar.us")
conn.request("GET", "/nfl/official/trial/v5/en/games/2019/reg/schedule.xml?api_key={your_api_key}")
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```
```shell
curl -X GET "https://api.sportradar.us/nfl/official/trial/v5/en/games/2019/reg/schedule.xml?api_key={your_api_key}"
```
> You must replace {your_api_key} with your API key. If you have upgraded from a trial key, be sure to change the access_level in the URL to reflect your production key. See the required parameters for the API for details.
Sportradar APIs use api_key authentication within the query to allow access to the API. Each API requires its own separate key, and the key must be included in each request. To authenticate with the server, replace {your_api_key} with your API key for the requested API.
You can register for free API trial keys at our [developer portal](https://developer.sportradar.com/member/register).
You must replace {your_api_key} with your API key. If you have upgraded from a trial key, be sure to change the access_level in the URL to reflect your production key. See the required parameters for the API for details.
## Versioning
We regularly enhance our APIs to provide the most comprehensive sports data. We have adopted the following versioning strategy to provide flexibility in your development.
#### Versioning Strategy:
Sportradar provides support for one current and two previous versions of an API. These versions are considered stable as it relates to the schema, data elements, behaviors, and formats as they will not change. Defects in calculations or logic will be addressed at the discretion of Sportradar. Previous versions will continue to be available but are not supported, and will no longer be available to new customers. It is your responsibility to migrate to one of the current, stable versions. To find the currently supported versions, see the Sportradar Versioning Strategy for details.
## HTTP Response Codes
Our APIs support the following HTTP response codes to indicate the success or failure of an API request. This list is not exhaustive, but provides the most common responses our APIs deliver.
| Numeric Code | Message | Description |
| ------------ | --------------------- | ------------------------------------------------------------ |
| 200 | OK | The request was successful |
| 400 | Bad Request | A variable in the request is incorrect, check the reply message for details |
| 403 | Forbidden | The request is legitimate but proper authorization was not provided |
| 403 | Developer Over Limit | The provided key has exceeded the rate limit |
| 403 | Developer Over QPS | The provided key has exceeded the queries per second limit |
| 403 | Developer Over Rate | The provided key has exceeded the rate limit |
| 404 | Not Found | The request resource was not found |
| 404 | Not Found | Invalid route |
| 404 | Not Found | Wrong identifier |
| 404 | Not Found | No outrights for this category |
| 404 | Not Found | Timestamp is too old |
| 404 | Not Found | No schedule for this tournament |
| 404 | Not Found | No tournaments for this sport |
| 429 | Too Many Requests | The number of sent requests to the endpoint has exceeded the rate limit |
| 500 | Internal Server Error | The server encountered an unexpected condition, which prevented it from fulfilling the request or serving the response |
| 503 | Database Error | The server was unable to retrieve the request |
| 503 | Service Unavailable | The server is undergoing scheduled maintenance |
| 503 | Backend Fetch Failed | The server could not reach the requested resource |
| 504 | Gateway Timeout | The server did not receive a timely response from another server upstream |
| 596 | Service Not Found | The called upon service does not exist on this server |
## ID Types in Sportradar APIs
Within Sportradar APIs you will encounter many different ID values. IDs can be attributed to leagues, conferences, divisions, franchises, teams, venues, drafts, weeks, periods, quarters, coaches, managers, prospects, draft picks, trades, transactions, drives, possessions, plays, in-game events, and many other variables.
### Primary IDs
There are two primary types of ID that can be attributed to a variety of variables: GUIDs (Global Unique Identifiers) and SR IDs (Sportradar Identifiers). They are used as a way to directly identify the given variable within the API, across multiple Sportradar APIs, or within data outside of Sportradar. The forms of IDs that you will encounter within Sportradar products, are detailed below:
**GUID IDs**: GUID IDs follow a specific structure: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
Example:
These GUIDs may appear as an “id” or a “us_id” in various APIs, or both values may be present.
Example:
**SR IDs**: These IDs can have a varying structure but always begin with "sr:" and end with a number.
Example:
These IDs may appear as an “id” or a “sr_id” in various APIs.
Example:
Note: The sr_id is an optional value in the US APIs and it’s strongly encouraged to utilize the GUIDs as your primary key.
### Other IDs
**Source IDs**: ID from another Sportradar API, such as a player from NCAA being drafted to the NFL. We include the source_id from the NCAA API so player information can be linked.
Example:
**Entity IDs**: Entity IDs are normally accompanied by an origin attribute that describes where the ID is linked to. For instance, image data may have an ID for a given player, we include that ID as a reference to our other APIs. Entity IDs only appear in our Images and Editorial Content APIs.
Entity ID Example:
### Notes Regarding IDs
Some IDs are displayed in different ways in different places along logical lines. For instance, some endpoints display a “team – id” to reference the teams that are competing in a specific sport event, but the team id may also be used to reflect a home team “home – id”, away team “away – id”, or an event winner “sport_event_status - winner_id”.
Another instance of this occurs frequently with “player – id” referencing the player, but the ID may also appear in event information to reflect player as a goal scorer “scorer – id”, or as providing an assist “assist – id”.
With various forms of IDs in the Sportradar APIs, some duplication can occur. For instance, a venue that is used by both the NBA and NBA G League may have multiple venue GUID IDs and/or SR IDs.
Similarly, a college player may have a GUID ID and/or SR ID that is different if they have joined a professional league.
Tournament IDs and Season IDs are interchangeable when calling Tournament endpoints. This is done so you are able to access a previous seasons data. To do this:
Interrogate the Tournaments Seasons endpoint to ascertain the required Season ID.
Use that Season ID to call any of the Tournament endpoints.
To access a previous seasons data in an API where Competition IDs are used:
Interrogate the Competitions List endpoint to ascertain the required Competition ID.
Use that Competition ID to call the Competition Seasons endpoint and locate your desired Season ID.
Use that Season ID to call any of the Season endpoints.
## Simulations
At Sportradar, we strive to make sure you are ready for live games. The live simulations below give you the opportunity to test your code against a simulation of live data being entered **before** the preseason starts!
Our simulations replay full completed games and allow you to view our API feeds as if they were happening live. Feeds update with game data as it plays. For instance, when a play completes in the play-by-play feed, the game statistics feed updates as well. This allows you to see how each API feed changes over the course of the game.
**Simulations are currently available for MLB, NBA, and NHL.**
If you need assistance in utilizing these simulations, please contact Sportradar Support.
MLB API Simulations
Sportradar's MLB simulations run every day according to the below schedule. Data is reset for each day's simulations at 10:00am UTC.
Quick Access
Start Time (UTC)
Game (Original game date)
Game ID
1:00pm
MIN at CLE (9/14/19, Game 1 Doubleheader)
6fc55b0d-29a8-43bf-bc08-932366c1dda3
1:00pm
CWS at SEA (9/14/19)
b946e7e5-3d02-45ad-a4bc-b0a75832a25e
1:00pm
HOU at KC (9/14/19)
fb2559d7-12d6-45a3-b991-829283f1a532
5:00pm
MIN at CLE (9/14/19, Game 2 Doubleheader)
02aef4b5-9025-43b9-bbf6-f29061c025ae
5:00pm
CWS at SEA (9/15/19)
d5b72bd7-7902-4de2-820d-57d11d7eaffb
5:00pm
HOU at KC (9/15/19)
eaa42c5a-0f07-45e8-8838-b29f6c0300c9
7:00pm
KC at OAK (9/17/19)
dff5b8c4-a972-4a44-9b9e-642b1e3fd5a4
7:00pm
CWS at MIN (9/16/19)
1785193a-599c-45bd-b13b-a3d5e68b4afe
To retrieve the game IDs, team IDs, and other associated information for each game listed above, you can use the following Daily Schedule URL with the syntax noted below. If you have an existing MLB API key, simply replace the access_level (trial or production) in the URL of a feed with *simulation*.
Note: The current date must be used when calling the simulation daily schedule.
Daily Schedule: https://api.sportradar.us/mlb/simulation/`{version}`/en/games/`{year}`/`{month}`/`{day}`/schedule.`{format}`?api_key=`{your_api_key}`
Play-by-Play sample: https://api.sportradar.us/mlb/simulation/`{version}`/en/games/1785193a-599c-45bd-b13b-a3d5e68b4afe/pbp.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `version` | Version number of the API you are accessing (Current Version: v7). |
| `year` | The current year in 4 digit format (YYYY). *Use 2019 for Seasonal simulation feeds and the current date for Daily feeds*|
| `month` | The current month in 2 digit format (MM). |
| `day` | The current day of the month in 2 digit format (DD). |
| `mlb_season` | Regular Season (REG). |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Feeds Available: Daily Boxscore, Daily Change Log, Daily Schedule, Daily Summary, Game Boxscore, Game Extended Summary, Game Pitch Metrics, Game Summary, Injuries, League Depth Chart, League Hierarchy, League Schedule, Play By Play, Player Profile, Rankings, Seasonal Pitch Metrics, Seasonal Splits, Seasonal Statistics, Seasonal Transactions, Seasons, Standings, Team Depth Chart, Team Profile, Venues, Push Events, Push Linescores, and Push Statistics.
For syntax structure on each feed, please visit our MLB API documentation [here](https://developer.sportradar.com/docs/read/baseball/MLB_v7).
NBA API Simulations
Sportradar's NBA simulations run every day according to the below schedule. Data is reset for each day's simulations at 12:45pm UTC.
Quick Access
Start Time (UTC)
Game
Game ID
1:00pm
Chicago Bulls at New York Knicks
26e0906a-a222-4013-a9c8-dea6a8fe1f4f
1:00pm
Brooklyn Nets at Portland Trailblazers
0d996d35-85e5-4913-bd45-ac9cfedbf272
5:00pm
Utah Jazz at Los Angeles Clippers
a2a43125-5538-43f7-84a9-e8e02a8a772f
5:00pm
Philadelphia 76ers at Detroit Pistons
9c322810-33cc-4aa8-b1c7-43bc6ed9af73
5:00pm
Washington Wizards at Golden State Warriors
f8367461-6e6f-4cbb-b758-4b866f554f80
7:00pm
San Antonio Spurs at Los Angeles Lakers
12b2e554-c80f-404f-b140-c25400996ac7
To retrieve the game IDs, team IDs, and other associated information for each game listed above, you can use the following URL with the syntax noted below. If you have an existing NBA API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.
https://api.sportradar.us/nba/simulation/`{version}`/`{language_code}`/games/2017/SIM/schedule.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `version` | Version number of the API you are accessing (Current Version: v7). |
| `language_code` | 2 letter code for supported languages: en (English), ru (Russian), zh (simplified Chinese), and ja (Japanese). |
| `nba_season` | Regular Season (REG). |
| `season_year`| Year in 4 digit format (YYYY). *Use 2017 for simulations* |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Feeds Available: Schedule, Standings, League Hierarchy, Game Boxscore, Game Summary, Play-By-Play, Team Profile, Seasonal Statistics, Injuries, Rankings, Push Events, and Push Statistics
For syntax structure on each feed, please visit our NBA API documentation [here](https://developer.sportradar.com/docs/read/basketball/NBA_v7).
NHL API Simulations
Sportradar's NHL simulations run every day according to the below schedule. Data is reset for each day's simulations at 12:00pm UTC.
Quick Access
Start Time (UTC)
Game
Game ID
1:00pm
Edmonton at Vancouver
66a5f479-0011-4ead-a51d-33a93e0062f7
1:00pm
Montreal at Winnipeg
8d591315-f3c8-4925-a3f1-d5a23ac8ba55
5:00pm
Dallas at Tampa Bay
90008b6a-3600-45e6-a3c3-21cca49e5d9d
5:00pm
Pittsburgh at New York
e4ba2be3-6cdc-4434-9194-5694e82c7ef9
9:00pm
St. Louis at San Jose
86bf6496-4a5d-456d-8e63-2cd41bd0373b
9:00pm
Minnesota at Vegas
c7e64152-06e2-44cc-872f-678fb64714ca
9:00pm
Colorado at Arizona
d364d4ec-892d-48d0-b44d-40a2e711b174
9:00pm
Vegas at Anaheim
dd1f6ad9-733a-4a28-b4a8-955f1fc04cc2
To retrieve the game IDs, team IDs, and other associated information for each game listed above, you can use the following URL with the syntax noted below. If you have an existing NHL API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.
https://api.sportradar.us/nhl/simulation/`{version}`/`{language_code}`/games/2020/SIM/schedule.`{format}`?api_key=`{your_api_key}`
Note: Use SIM as the nhl_season and 2020 as the season_year for each applicable NHL simulation request.
| Parameter | Description |
| --------- | ----------- |
| `version` | Version number of the API you are accessing (Current Version: v7). |
| `language_code` | 2 letter code for supported languages: en (English), es (Spanish), fr (French), ru (Russian), and zh (simplified Chinese). |
| `nhl_season` | SIM |
| `season_year` | 2020 |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Feeds Available: Game Analytics, Game Boxscore, Game Faceoffs, Game Play-By-Play, Game Shot Zones, Game Summary, Game Time on Ice, League Leaders (Goaltending), League Leaders (Skaters), Schedule, Seasonal Analytics, Seasonal Faceoffs, Seasonal Shot Zones, Seasonal Statistics, Standings, Team Profile, Push Events, and Push Statistics.
For syntax structure on each feed, please visit our NHL API documentation [here](https://developer.sportradar.com/docs/read/hockey/NHL_v7).
## FAQs
### What is an API request?
API stands for "Application Programming Interface." Basically, an API is how computers talk to each other to share data. Web applications will request data through an API, with the path and parameters provided defining what data is returned.
### How do I get started sampling feeds?
You can get access to our complete set of data feeds by following these steps:
### When does my trial API key run out?
Trial API keys will last for 90 days. However, we are willing to work with our prospective customers to allow ample time to sample all of our data feeds.
### How many requests can I make with my trial API keys?
Each trial key is specific to a single sport, and is limited to 1,000 total calls over a rolling 30 day period.
### How do I get access to a higher number of API requests?
Contact our sales group and they will work with you to provide the access level you need to evaluate our products.
### Will I be able to see all the data with my trial API key?
A trial key allows you access to the same data as is made available with a production key. A trial key allows you less calls per month as well as less calls per second rate or throttle limit compared to the other tiers. The data itself is not throttled or updated at a lesser frequency between trial and production access levels.
### Do your APIs support CORS (Cross-Origin Resource Sharing) requests?
No. Sportradar’s APIs are B2B (Business-to-Business) and are not intended to be called directly from a client application. The expectation is that you pull from our APIs, store the data, and then serve it directly to your customers.
### Where do I find feed documentation?
We have two types of feed documentation. For product managers evaluating our coverage, our documentation page has detailed documents outlining every data point included in each feed. For developers parsing our feeds, we provide XSD files in our API gallery.
### Why do you base your pricing tiers on the number of API requests I make?
The sports media and fantasy sports industries place a premium on update speed, so we have made substantial investments to generate real-time data feeds. We price our product tiers based on the frequency a customer pulls from these real-time feeds.
### How many API requests do I need?
On our pricing page there is a table that provides the number of monthly requests needed to update a single feed at various frequencies. We will work with you to determine the appropriate number of API requests you need to meet your product requirements.
### What happens when I exceed my allocated number of requests?
We use two forms of rate limiting for each API we provide. First, depending on your contract level, we limit how many calls per second we accept from a particular account key to prevent overloading the API from a burst of activity. If you exceed this limit, you will receive an HTTP/1.1 403 error ("Forbidden - Account Over Queries Per Second Limit") until the next second begins. Second, we specify how many calls each account key can make over a month. If you exceed this limit, we return a 403 error ("Forbidden - Account Over Rate Limit"). It is up to customers to monitor their contracted API usage.
### Why is one sport more expensive than another?
There are two main factors which dictate sport pricing. The first factor is our costs. For example, NFL data collection requires more live data analysts than do other sports to capture all the relevant game action. Another example of a more costly sport is MLB, which has a significant number of games to collect data from each month. The second factor is the value of the data in the marketplace. Media and fantasy companies typically generate more revenue on NFL and MLB data, than on NBA and NHL.
### Will I be charged a fee during the off-season months?
No, you will only be charged a licensing fee during the months in which teams play games for a given sport.
### Are the monthly fees the same during the preseason, postseason or any months with fewer games?
Yes, the monthly costs are generally lower during months in which there are fewer games. We do not have standard rates for those months, however, as many customers require data during months where there are a mix of pre-season/regular or regular/postseason, while others may only want postseason data. We work with each customer to determine a fair price for these months.
### Do I need separate keys for different versions of your APIs?
Yes, each version of our APIs require a key (e.g., NFL v6 and NFL v7 require separate keys). If you currently have a key to an API that has a new version released, either we will create a key for you as part of the new version release, or you're current key will be forward-compatible to the new version. If a new key is issued, this new key can be viewed on the My Account page when you login to the Sportradar API Portal and will have the same request limits as you're key to the previous version. When a new version is created, Sportradar support will send a notification to the email address used to register with our Portal.
### Does Sportradar have a data quality team to ensure accurate data?
We do have a quality team - it is modeled much like a "pit boss" structure you would see in a casino. There are multiple layers of validation (checked against multiple public sources) to make sure that each stat is spot-on with the official league statistic. The data entry analyst has a "pit-boss" that typically has about 6 events he or she monitors. The "pit-boss" validates that the data is matching public sources in a timely manner and addresses issues immediately. There is then a supervisor who is checking on all the pit-bosses to make sure their games are tight as well (and then is available to address any scoring issues or concerns). We automate as much of this process as possible so that the validation (and alerts) highlight inconsistencies quickly and aggressively. The validation process is both automated and checked with human fail-safes to make sure we provide the highest quality possible.
Return to top
