Documentation

## 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:

  1. Select the API you want to view from the dropdown.
  2. Enter your API key in the field.
  3. Select your desired feed and adjust the parameters to your needs.
  4. 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. 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:
  1. Interrogate the Tournaments Seasons endpoint to ascertain the required Season ID.
  2. 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:
  1. Interrogate the Competitions List endpoint to ascertain the required Competition ID.
  2. Use that Competition ID to call the Competition Seasons endpoint and locate your desired Season ID.
  3. 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, NHL, and NCAA Football.** If you need assistance in utilizing these simulations, please contact Sportradar Support.

MLB API Simulations

Below are the details regarding the simulations for our MLB API v7 Simulations run every day according to the below schedule. Data is reset for each day's simulations at 10:00am UTC.
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 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. http://api.sportradar.us/mlb/simulation/`{version}`/en/games/`{year}`/`{month}`/`{day}`.`{format}`?api_key=`{your_api_key}`
Note: The current date must be used when calling the simulation schedule.
| 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*| | `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

Below are the details regarding the simulations for our NBA API (v7) Simulations run every day according to the below schedule. Data is reset for each day's simulations at 12:45pm UTC.
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. http://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

Below are the details regarding the simulations for our NHL API (v7) Simulations run every day according to the below schedule. Data is reset for each day's simulations at 12:00pm UTC.
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. http://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).

NCAAFB API Simulations

Simulations will be available starting July 19th and will continue through August 27th​. During this time we will provide six replayed games from the 2020 NCAA Football Season per week​. Monday-Friday there will be a game replayed at 2:00 pm ET and on Thursdays an additional game at 6:00 pm ET. Details of these games are listed below.
Note: The simulated games will be listed as part of the 2021 Regular season.
Day Time (EDT) Game (Original game date)
Monday 2:00pm BYU at Houston (10/16/20)
Tuesday 2:00pm Florida State at Miami (Fla.) (9/26/20)​
Wednesday 2:00pm Auburn at Georgia (10/3/20)​
Thursday (Early Game) 2:00pm Louisiana-Lafayette at Iowa State (9/12/20)​
Thursday (Late Game) 6:00pm Texas at Oklahoma (10/10/20)​
Friday 2:00pm Michigan State at Iowa (11/7/20)​
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: http://api.sportradar.us/ncaafb/simulation/`{version}`/`{language_code}`/games/2021/REG/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). | | `format` | xml or json. | | `your_api_key` | Your API key. |

Feeds Available: Weekly Schedule, Season Schedule, Game Statistics, Game Play-By-Play, Game Boxscore, Game Roster, and League Hierarchy​.

For syntax structure on each feed, please visit our NCAA Football API documentation [here](https://developer.sportradar.com/docs/read/american_football/NCAA_Mens_Football_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:
  1. Register for a user account
  2. Register your application
  3. Navigate to My Account
  4. Select Get API Keys
### 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. ### 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

Docs Navigation