## Probabilities API Overview
The Probabilities API provides live and pre-match 3-way (win, lose, or draw) probabilities for sporting events. Top US bookmakers are featured, and return odds for NFL, NBA, MLB, NHL, top soccer leagues, and more.
The API is consistent in structure, format, and behavior with the other General Sport APIs. Primary feeds will return schedules for sports and leagues covered.
Additional feeds provide probability breakdowns for events, including a live timeline for supported games.
API
API Version
Probabilities
v1
Note: Authentication is required for all API calls.
## Probabilities API Map
To best utilize the Probabilities API, you will need several parameters to create your API calls. The map below illustrates how you can obtain the parameters you need.
>
Examples:
>To find the Sport Event Probabilities for a Cricket match on a given day:
>
Call the Sports endpoint and find Cricket.
Take note of the "sport - id" for Cricket (sr:sport:21).
Call the Sport Schedule endpoint using the sport id and the given day you are interested in.
Find the sport event you are interested in and call the Sport Event Probabilities feed with the "sport_event - id".
>The probabilities for the chosen match are displayed.
>
>To find the Probabilities for a season of Cricket and view a Sport Event Probabilities Timeline:
>
Call the Sports endpoint and find Cricket.
Take note of the "sport - id" for Cricket (sr:sport:21).
Call the Sport Competitions endpoint and take note of the "competition - id" for the competition you want.
Call the Competition Seasons endpoint using the "competition - id" and take note of the "season - id" for the season you want.
Call the Seasonal Probabilities endpoint using the "season - id" and take note of the "sport_event - id" for the match you want.
Call the Sport Event Probabilities Timeine endpoint using the "sport_event - id".
>The timeline of probabilities for the given match are displayed.
Primary feeds don't require any parameters, while other feeds may require dates, IDs or other human-readable parameters to identify the category, sport, sport event or tournament that the feed will describe. The primary feeds provide Sport IDs, sports feeds provide Sport Event and Competition IDs, the competition feed provide Season IDs, and the seasonal feed provides Sport Event IDs.
## Competition Seasons
Returns a list of seasons for a given competition ID.
TTL / Cache:
60 seconds
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/competitions/sr:competition:17/seasons.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", "/probabilities/trial/v1/en/competitions/sr:competition:17/seasons.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/probabilities/trial/v1/en/competitions/sr:competition:17/seasons.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Competition Seasons feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/competitions/`{competition_id}`/seasons.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `competition_id` | Id of a given competition. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Seasonal Outright Probabilities
Returns a list of probabilities for various seasonal outrights.
TTL / Cache:
60 seconds
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/seasons/sr:season:63057/outright_probabilities.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", "/probabilities/trial/v1/en/seasons/sr:season:63057/outright_probabilities.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/probabilities/trial/v1/en/seasons/sr:season:63057/outright_probabilities.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Seasonal Outright Probabilities feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/seasons/`{season_id}`/outright_probabilities.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `season_id` | Id of a given season. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Seasonal Probabilities
Returns a list of sport events with probabilities, for a given competition season ID.
TTL / Cache:
60 seconds
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/seasons/sr:season:63057/probabilities.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", "/probabilities/trial/v1/en/seasons/sr:season:63057/probabilities.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/probabilities/trial/v1/en/seasons/sr:season:63057/probabilities.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Seasonal Probabilities feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/seasons/`{season_id}`/probabilities.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `season_id` | Id of a given season. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
### Optional Query String Parameters
>Example including optional query string parameters:
import http.client
conn = http.client.HTTPSConnection("api.sportradar.com")
conn.request("GET", "/probabilities/trial/v1/en/seasons/sr:season:63057/probabilities.xml?api_key={your_api_key}&start=200")
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl -L GET 'api.sportradar.com/probabilities/trial/v1/en/seasons/sr:season:63057/probabilities.xml?api_key={your_api_key}&start=200'
In addition to the URL parameters listed above, you can paginate the response with one or more of the following optional query string parameters.
Note: Optional query string parameters must be added after your API key with an ampersand (&).
Replace placeholders with the following query parameters:
| Parameter | Description |
| --------- | ----------- |
| `start` | Number to start the list of results from. Example: start=0 |
| `limit` | Number to limit the number of results. Minimum value is 1, maximum value is 200. Example: limit=200 |
Return to top
## Sport Competitions
Returns a list of competitions IDs for a given sport ID.
TTL / Cache:
60 seconds
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/sports/sr:sport:1/competitions.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", "/probabilities/trial/v1/en/sports/sr:sport:1/competitions.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/probabilities/trial/v1/en/sports/sr:sport:1/competitions.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Sport Competitions feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/sports/`{sport_id}`/competitions.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `sport_id` | Id of a given sport. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Sport Event Probabilities
Returns probabilities for a given sport event ID.
TTL / Cache:
1 second
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/probabilities.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", "/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/probabilities.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/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/probabilities.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Sport Event Probabilities feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/sport_events/`{sport_event_id}`/probabilities.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `sport_event_id` | Id of a given sport event. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Sport Event Probabilities Timeline
Returns a list of probability changes during an event for a given sport event ID.
TTL / Cache:
1 second
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/timeline.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", "/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/timeline.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/probabilities/trial/v1/en/sport_events/sr:sport_event:17139773/timeline.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Sport Event Probabilities Timeline feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/sport_events/`{sport_event_id}`/timeline.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `sport_event_id` | Id of a given sport event. |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Sport Schedule
Returns a list of scheduled sport events by sport ID and date.
TTL / Cache:
1 second
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/sports/sr:sport:3/schedules/2021-10-09/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", "/probabilities/trial/v1/en/sports/sr:sport:3/schedules/2021-10-09/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/probabilities/trial/v1/en/sports/sr:sport:3/schedules/2021-10-09/schedule.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Sport Schedule feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/sports/`{sport_id}`/schedules/`{date}`/schedule.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `sport_id` | Id of a given sport. |
| `date` | Date in the following format: YYYY-MM-DD |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
Return to top
## Sports
Returns a list of sports and their IDs.
TTL / Cache:
60 seconds
```ruby
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://api.sportradar.us/probabilities/trial/v1/en/sports.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", "/probabilities/trial/v1/en/sports.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/probabilities/trial/v1/en/sports.xml?api_key={your_api_key}"
```
> The above command returns xml structured like this.
Access the Sports feed by replacing the parameters in the following URL:
https://api.sportradar.us/probabilities/`{access_level}`/`{version}`/`{language_code}`/sports.`{format}`?api_key=`{your_api_key}`
| Parameter | Description |
| --------- | ----------- |
| `access_level` | Defines the access level of your API key as Production (production) or Trial (trial). |
| `version` | Version number of the API you are accessing (Current Version: v1). |
| `language_code` | Supported Locales |
| `format` | xml or json. |
| `your_api_key` | Your API key. |
## Frequently Asked Questions
Q: What sports are available in the Probabilities API?
A: The below sports are available to be licensed. More can be made available by request.
American Football
Baseball
Basketball
Cricket
Handball
Ice Hockey
Soccer
Tennis
Q: What format are date fields presented in?
A: All of our Date/Time attributes are in either UTC (ISO-8601) or Unix Time (Epoch Time).
UTC Example: 2013-04-03T18:15:00+00:00
Unix Example: 1505844490
Q: What format are the date/time fields presented in?
A: All of our Date/Time attributes are in UTC, presented in the ISO 8601 standard format.
ex: 2013-04-03T18:15:00+00:00
For more information: https://en.wikipedia.org/wiki/ISO_8601
Q: What competitions are covered?
A: To get a list of all the competitions call the Sport Competitions endpoint for a given sport.
Q: What markets are currently available?
A: Only main markets (2way, 3way) odds are currently available for all sports. The Innings Runs market is also available for Cricket.
Q: What information does 'basic score' include?
A: Basic score information is included in the node and includes the following parameters:
status
match_status
home_score
away_score
innings
over
delivery
home_dismissals
away_dismissals
Q: What level of precision is applied to the probabilities?
A: The probabilities are presented to the nearest tenth of a percent. Changes to the probabilities are captured when the probabilities change by more than 0.1%.
Q: How do I distinguish between pre-match and live probabilities?
A: Live probabilities are denoted by the attribute live="true". See the code sample to the right.
Q: What happens to the Sport Event Probabilities Timeline before, during, and after the match?
A: Before the match, the feed will only include pre-match probabilities. Near to the start of the match the probabilities will switch to live. The pre-match probabilities will remain in the feeds throughout the match but be frozen in time with no further changes.
Live probabilities will continue to update throughout the match and will converge to 0 and 100 for the losing and winning outcomes.
Post-match the live probabilities will remain at 0 and 100 while the pre-match probabilities will persist as they were at the start of the match.
Q: What are the possible values for “sport_event - status”?
A: The possible values for “sport_event – status” are:
not_started – The match is scheduled to be played
started - The match has begun
live – The match is currently in progress
postponed – The match has been postponed to a future date
suspended - The match has been suspended
match_about_to_start - The match is about to begin
delayed – The match has been temporarily delayed and will be continued
interrupted - The match began, but coverage has stopped for a short time. Note that match scores may not be updated during this period, the last recorded match score will be displayed instead
cancelled – The match has been cancelled and will not be played
ended – The match is over
closed – The match results have been confirmed
Q: When does match_time, remaining_time and remaining_time_in_period show up in the data?
A: These attributes are included alongside predictions for sport events which are divided into time-based periods of play. The data is only recorded while a period of play is in-progress and does not appear during breaks such as half-time.
Q: Are historical probabilities available?
A: No. This is a forward-looking API only and probabilities will only be available for the current season of any competition. Additionally, there are no probabilities available prior to February 2019.
Q: How do I locate the TTL (Time to Live)/cache on an API endpoint?
A: The cache (in seconds) can be accessed in the returned header information on each RESTful API call, under cache-control.
ex. cache-control: max-age=1, public, s-maxage=1 or cache-control: public, must-revalidate, max-age=120
## Competition Seasons
Returns a list of seasons for a given competition ID.
