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. You can use our APIs to access sport statistics feeds, which contain all the data for leagues, conferences, teams, games, and players in our database. 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.

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.

Use the navigation to the left to select the documentation for your desired sport. Detailed documentation and code examples are included for each API endpoint. View code examples in the area to the right. You can switch the programming language of the examples with the tabs in the top right. ## 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 authentication keys 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. 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.
## 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: **Reference IDs & Entity IDs**: Normally accompanied by an origin attribute that describes where the ID is linked to. For instance, NFL GSIS data may have an ID for a given player, we include that ID as a reference ID. Entity IDs perform the same function, but only appear in our Images and Editorial Content APIs. Reference ID Example: 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 simulation system replays select completed games and allows you to view our API feeds as if they were happening live.

Live Data Simulations

The simulations for each sport replay full games in the order listed in the tables below. 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. If you need assistance in utilizing these simulations, please contact Sportradar Support.

NFL API Simulations

Below are the details regarding the simulations for our NFL Official API (v5) The live simulations give you the opportunity to test your code against a simulation of live data before the preseason starts or any time! Our simulation system replays select completed games allowing you to view our API feeds as if they were happening live. Below are the details regarding the simulations for our NFL API (v5) Simulations run twice a day at the following times (Eastern Time): 11:00 am/11:00 pm - Data is reset for the day’s simulations
1:00 pm/1:00 am - PST week 1 games will run – Minnesota at New Orleans, Seattle at Philadelphia, Buffalo at Houston, and Tennessee at New England
3:00 pm/3:00 am – PST week 2 games will run - Minnesota at San Francisco, Houston at Kansas City, Tennessee at Baltimore, and Seattle at Green Bay
5:00 pm/5:00 am – PST week 3 games will run – Tennessee at Kansas City and Green Bay at San Francisco
7:00 pm/7:00 am – PST week 4 games will run – San Francisco vs Kansas City
By retrieving the Season Schedule feed for the 2019 postseason, you can obtain the game ID for each game listed above. All pull-based feeds are available for simulation. Simulations of push delivery are available for the Push Statistics and Push Event feeds, but we are currently unable to provide the Push Clock as a simulation. If you have an existing API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.

NCAAFB API Simulations

Below are the details regarding the simulations for our NCAAFB API (v1)

Feeds Available: Weekly Schedule, Season Schedule, Game Statistics, Game Summary, Play-By-Play, Play Summary, Boxscore, Extended-Boxscore, Game Roster, Team Hierarchy, Team Roster, Standings, Seasonal Statistics

Event Description | Season | Week | Example Play-By-Play Feed Path ----------------- | ------ | ---- | ------------------------------ WKY@MSH | 2015/REG | 1 | http://api.sportradar.us/ncaafb-sim-t1/2015/REG/1/WKY/MSH/pbp.xml?api_key={your_api_key} KEN@FLA | 2015/REG | 1 | http://api.sportradar.us/ncaafb-sim-t1/2015/REG/1/KEN/FLA/pbp.xml?api_key={your_api_key} WOU@PRST | 2015/REG | 1 | http://api.sportradar.us/ncaafb-sim-t1/2015/REG/1/WOU/PRST/boxscore.xml?api_key={your_api_key}

NBA API Simulations

Below are the details regarding the simulations for our NBA API (v7)

Feeds Available: Schedule, Standings, League Hierarchy, Game Boxscore, Game Summary, Play-By-Play, Team Profile, Seasonal Statistics, Injuries, Push Events, and Push Statistics

Simulations run every day at the following times (UTC): 12:45 pm – Data is reset for day's simulations.
1:00 pm – Chicago Bulls at New York Knicks & Brooklyn Nets at Portland Trail Blazers.
5:00 pm – Utah Jazz at Los Angeles Clippers, Philadelphia 76ers at Detroit Pistons, and Washington Wizards at Golden State Warriors.
7:00 pm – San Antonio Spurs at Los Angeles Lakers.
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/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` | Optional 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. | Most relevant pull-based feeds are available for simulation. Simulations of push delivery are available for all feeds. If you have an existing API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.

NCAAMB API Simulations

Below are the details regarding the simulations for our NCAAMB API (v3)

Feeds Available: Schedule, Standings, League Hierarchy, Game Boxscore, Game Summary, Play-By-Play, Team Profile

Game Description | Season | Event / Game ID | Example Play-By-Play Feed Path ---------------- | ------ | --------------- | ------------------------------ AUB@CONN (Replay of 12/23/2016) | 2016/REG | 50251ac4-d083-4ada-a736-67db9e894196 | http://api.sportradar.us/ncaamb-sim3/games/50251ac4-d083-4ada-a736-67db9e894196/pbp.xml?api_key={your_api_key} PUC@PAC (Replay of 12/23/2016) | 2016/REG | db79b069-f4ff-4153-ab5a-86670df5d7ca | http://api.sportradar.us/ncaamb-sim3/games/db79b069-f4ff-4153-ab5a-86670df5d7ca/pbp.xml?api_key=={your_api_key}

NCAAWB API Simulations

Below are the details regarding the simulations for our NCAAWB API (v3)

Feeds Available: Schedule, League Hierarchy, Game Boxscore

Game Description | Season | Event / Game ID | Example Play-By-Play Feed Path ---------------- | ------ | --------------- | ------------------------------ ND@CONN | 2014/pst | bce4735f-2b3c-458d-bad5-0d3ff118738d | http://api.sportradar.us/ncaawb-sim3/games/bce4735f-2b3c-458d-bad5-0d3ff118738d/boxscore.xml?api_key={your_api_key}

NHL API Simulations

Below are the details regarding the simulations for our NHL API (v7) Simulations run every day at the following times (UTC): 11:00 am - Data is reset for the day’s simulations.
12:00 pm - Vancouver at Colorado, Chicago at Los Angeles, Minnesota at St. Louis
4:00 pm – Dallas at St. Louis, Calgary at New York
8:00 pm – Dallas at Detroit, Nashville at Colorado, Minnesota at Vancouver, Florida at Chicago
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/nhl/simulation/`{version}`/`{language_code}`/games/`{year}`/`{month}`/`{day}`/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), es (Spanish), fr (French), ru (Russian), and zh (simplified Chinese). | | `year` | Current year in 4 digit format (YYYY). | | `month` | Current month in 2 digit format (MM). | | `day` | Current day in 2 digit format (DD). | | `format` | xml or json. | | `your_api_key` | Your API key. |
Note: If the simulation URL requires a nhl_season, you must use the season type of SIM.
Most relevant pull-based feeds are available for simulation. Simulations of push delivery are available for Push Events and Push Statistics. If you have an existing API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.

Golf API Simulations

Below are the details regarding the simulations for our Golf API (v2)

Feeds Available: Tournament Schedule, Tournament Summary, Tournament Leaderboard, Tournament Hole Statistics, Tee Times Per Round, Scorecards Per Round, Player Statistics

Tournament Description | Season | Tournament ID | Round | Example Leaderboard Feed Path ---------------------- | ------ | ------------- | ----- | ----------------------------- Scottish Open Simulation | 2015 | 57bdb770-e0b5-4344-ac24-21e059e1219e | all | http://api.sportradar.us/golf-sim-pga2-t2/leaderboard/pga/2015/tournaments/57bdb770-e0b5-4344-ac24-21e059e1219e/leaderboard.xml?api_key={your_api_key} Masters Simulation | 2015 | a2576743-9b52-41b8-be69-b16e73d3b94e | all | http://api.sportradar.us/golf-sim-pga1-t2/leaderboard/pga/2015/tournaments/a2576743-9b52-41b8-be69-b16e73d3b94e/leaderboard.xml?api_key={your_api_key} ## 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., MLB v1 and MLB v2 require separate keys). If you currently have a key to an API that has a new version released, we will create a key for you as part of the new version release. 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 your 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 US 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

version 407 as of 5 months ago by m.wood

Docs Navigation