# Odds API Docs V3
Update
Version 4 of the API is now available. Docs for version 4 can be found here
Version 3 will continue to be maintained. Version 4 currently offers the same data, however in a format that's more convenient for new implementations.
# Overview
Get started with The Odds API in 3 steps
Get a list of in-season sports
{
"key": "soccer_epl",
"active": true,
"group": "Soccer - UK",
"details": "English Premier League 🇬🇧",
"title": "EPL"
},
...
Use the sport key from step 2 to get a list of upcoming events and odds from different bookmakers
{
"sport_key": "soccer_epl",
"sport_nice": "EPL",
"teams": ["Chelsea", "Manchester United"],
"commence_time": 1540035000,
"home_team": "Chelsea",
"sites": [
{
"site_key": "unibet",
"site_nice": "Unibet",
"last_update": 1540020857,
"odds": {
"h2h": [
1.68,
5.5,
4.05
]
}
},
...
# Host
All requests use the host https://api.the-odds-api.com
# GET sports
Returns a list of in-season sport objects.
The sport key can be used as the sport parameter in the /odds requests (below).
This request does not contribute to usage quotas.
# Endpoint
GET /v3/sports/?apiKey={apiKey}
# Parameters
apiKey  An API key is emailed when you sign up to a plan. See here for usage plans
all  Optional - if this parameter is present (for example,
all=true), a list of all sports (in and out of season) will be returnedoutrights  Optional - if this parameter is present (for example,
outrights=true), the response will include sports and events with outright markets (for example, Super Bowl Winner). See more info on outrights
Try it out in the browser
# Example Request
# Example Response
{
"success": true,
"data": [
{
"key": "americanfootball_ncaaf",
"active": true,
"group": "American Football",
"details": "US College Football",
"title": "NCAAF"
},
{
"key": "americanfootball_nfl",
"active": true,
"group": "American Football",
"details": "US Football",
"title": "NFL"
},
{
"key": "aussierules_afl",
"active": true,
"group": "Aussie Rules",
"details": "Aussie Football",
"title": "AFL"
},
{
"key": "baseball_mlb",
"active": true,
"details": "Major League Baseball 🇺🇸",
"group": "Baseball",
"title": "MLB"
},
{
"key": "cricket_test_match",
"active": true,
"details": "International Test Matches",
"group": "Cricket",
"title": "Test Matches"
},
{
"key": "mma_mixed_martial_arts",
"active": true,
"group": "Mixed Martial Arts",
"details": "Mixed Martial Arts",
"title": "MMA"
},
{
"key": "rugbyleague_nrl",
"active": true,
"group": "Rugby League",
"details": "Aussie Rugby League",
"title": "NRL"
},
{
"key": "soccer_belgium_first_div",
"active": true,
"group": "Soccer - Europe",
"details": "Belgium Soccer 🇧🇪",
"title": "Belgium First Div"
},
{
"key": "soccer_china_superleague",
"active": true,
"details": "Chinese Soccer 🇨🇳",
"group": "Soccer - Other",
"title": "Super League - China"
},
{
"key": "soccer_denmark_superliga",
"active": true,
"group": "Soccer - Europe",
"details": "Danish Soccer 🇩🇰",
"title": "Denmark Superliga"
},
{
"key": "soccer_efl_champ",
"active": true,
"group": "Soccer - UK",
"details": "EFL Championship 🇬🇧",
"title": "Championship"
},
{
"key": "soccer_england_league1",
"active": true,
"group": "Soccer - UK",
"details": "EFL League 1 🇬🇧",
"title": "League 1"
},
{
"key": "soccer_england_league2",
"active": true,
"group": "Soccer - UK",
"details": "EFL League 2 🇬🇧",
"title": "League 2"
},
{
"key": "soccer_epl",
"active": true,
"group": "Soccer - UK",
"details": "English Premier League 🇬🇧",
"title": "EPL"
},
{
"key": "soccer_finland_veikkausliiga",
"active": true,
"group": "Soccer - Europe",
"details": "Finnish Soccer 🇫🇮",
"title": "Veikkausliiga - Finland"
},
{
"key": "soccer_france_ligue_one",
"active": true,
"group": "Soccer - Europe",
"details": "French Soccer 🇫🇷",
"title": "Ligue 1 - France"
},
{
"key": "soccer_france_ligue_two",
"active": true,
"details": "French Soccer 🇫🇷",
"group": "Soccer - Europe",
"title": "Ligue 2 - France"
},
{
"key": "soccer_germany_bundesliga",
"active": true,
"group": "Soccer - Europe",
"details": "German Soccer 🇩🇪",
"title": "Bundesliga - Germany"
},
{
"key": "soccer_germany_bundesliga2",
"active": true,
"details": "German Soccer 🇩🇪",
"group": "Soccer - Europe",
"title": "Bundesliga 2 - Germany"
},
{
"key": "soccer_mexico_ligamx",
"active": true,
"details": "Mexican Soccer 🇲🇽",
"group": "Soccer - Other",
"title": "Liga MX"
},
{
"key": "soccer_netherlands_eredivisie",
"active": true,
"group": "Soccer - Europe",
"details": "Dutch Soccer 🇳🇱",
"title": "Dutch Eredivisie"
},
{
"key": "soccer_norway_eliteserien",
"active": true,
"group": "Soccer - Europe",
"details": "Norwegian Soccer 🇳🇴",
"title": "Eliteserien - Norway"
},
{
"key": "soccer_portugal_primeira_liga",
"active": true,
"group": "Soccer - Europe",
"details": "Portugese Soccer 🇵🇹",
"title": "Primeira Liga - Portugal"
},
{
"key": "soccer_russia_premier_league",
"active": true,
"group": "Soccer - Europe",
"details": "Russian Soccer 🇷🇺",
"title": "Premier League - Russia"
},
{
"key": "soccer_spain_la_liga",
"active": true,
"group": "Soccer - Europe",
"details": "Spanish Soccer 🇪🇸",
"title": "La Liga - Spain"
},
{
"key": "soccer_spl",
"active": true,
"group": "Soccer - UK",
"details": "Scottish Premier League 🇬🇧",
"title": "SPL"
},
{
"key": "soccer_sweden_allsvenskan",
"active": true,
"group": "Soccer - Europe",
"details": "Swedish Soccer 🇸🇪",
"title": "Allsvenskan - Sweden"
},
{
"key": "soccer_sweden_superettan",
"active": true,
"details": "Swedish Soccer 🇸🇪",
"group": "Soccer - Europe",
"title": "Superettan - Sweden"
},
{
"key": "soccer_switzerland_superleague",
"active": true,
"group": "Soccer - Europe",
"details": "Swiss Soccer 🇨ðŸ‡",
"title": "Super League - Swiss"
},
{
"key": "soccer_usa_mls",
"active": true,
"group": "Soccer - Other",
"details": "Major League Soccer 🇺🇸",
"title": "MLS"
}
]
}
# Response Headers
Calls to the /sports method will not affect the quota usage. The following response headers are returned:
- x-requests-remaining  The number of requests remaining until the quota resets
- x-requests-used  The number of requests used since the last quota reset
# GET odds
Returns a list of upcoming and live games with recent odds for a given sport, region and market
# Endpoint
GET /v3/odds/?apiKey={apiKey}&sport={sport}®ion={region}&mkt={mkt}
# Parameters
apiKey  An API key is emailed when you sign up to a plan. See here for usage plans
sport  The sport key obtained from calling the /sports method.
upcomingis always valid, returning any live games as well as the next 8 upcoming games across all sportsregion  Determines which bookmakers are returned. Valid regions are
au(Australia),uk(United Kingdom),eu(Europe) andus(United States)mkt  Optional - Determines which odds market is returned. Defaults to
h2h(head to head / moneyline). Valid markets areh2h,spreads(handicaps) andtotals(over/under).spreadsandtotalsodds are not always as comprehensive as h2h, so they do not count against the usage quota on paid plans.Lay odds are automatically included with
h2hresults for relevant bookmakers (Betfair, Matchbook etc). These appear in the results under theh2h_laykey.From July 2020,
outrightsare a valid market for sports withhas_outrights: true. If the sport has outrights, setmkt=outrights. Lay odds for outrights (outrights_lay) will automatically be available for relevant exchanges. More info on outrightsdateFormat  Optional - Determines the format of timestamps in the response. Valid values are
unixandiso(ISO 8601). Defaults tounix.oddsFormat  Optional - Determines the format of odds in the response. Valid values are
decimalandamerican. Defaults todecimal. When set toamerican, small discrepancies might exist for some bookmakers due to rounding errors.
Try it out in the browser
# Example Request
# Example Response
{
"success": true,
"data": [
{
"id": "5cc7c4e08fb03088252f8e0b046bb761",
"sport_key": "soccer_epl",
"sport_nice": "EPL",
"teams": ["Bournemouth", "Everton"],
"commence_time": 1535205600,
"home_team": "Bournemouth",
"sites": [
{
"site_key": "unibet",
"site_nice": "Unibet",
"last_update": 1535157373,
"odds": { "h2h": [2.65, 2.7, 3.6] }
},
{
"site_key": "betvictor",
"site_nice": "Bet Victor",
"last_update": 1535157374,
"odds": { "h2h": [2.55, 2.8, 3.6] }
},
{
"site_key": "ladbrokes",
"site_nice": "Ladbrokes",
"last_update": 1535157143,
"odds": { "h2h": [2.5, 2.65, 3.5] }
},
{
"site_key": "betfair",
"site_nice": "Betfair",
"last_update": 1535157209,
"odds": { "h2h": [2.68, 2.8, 3.65] }
},
{
"site_key": "skybet",
"site_nice": "Sky Bet",
"last_update": 1535157054,
"odds": { "h2h": [2.4, 2.63, 3.6] }
},
{
"site_key": "paddypower",
"site_nice": "Paddy Power",
"last_update": 1535157357,
"odds": { "h2h": [2.6, 2.7, 3.5] }
}
],
"sites_count": 6
},
{
"id": "d689bc4a1d0fe53463e500059280057e",
"sport_key": "soccer_epl",
"sport_nice": "EPL",
"teams": ["Arsenal", "West Ham United"],
"commence_time": 1535205600,
"home_team": "Arsenal",
"sites": [
{
"site_key": "unibet",
"site_nice": "Unibet",
"last_update": 1535157373,
"odds": { "h2h": [1.38, 8.75, 5.5] }
},
{
"site_key": "betvictor",
"site_nice": "Bet Victor",
"last_update": 1535157374,
"odds": { "h2h": [1.36, 8.5, 5.5] }
},
{
"site_key": "ladbrokes",
"site_nice": "Ladbrokes",
"last_update": 1535157143,
"odds": { "h2h": [1.36, 8, 5] }
},
{
"site_key": "betfair",
"site_nice": "Betfair",
"last_update": 1535157209,
"odds": { "h2h": [1.39, 9.4, 5.6] }
},
{
"site_key": "skybet",
"site_nice": "Sky Bet",
"last_update": 1535157054,
"odds": { "h2h": [1.36, 7.5, 5] }
},
{
"site_key": "paddypower",
"site_nice": "Paddy Power",
"last_update": 1535157357,
"odds": { "h2h": [1.33, 8.5, 5.5] }
}
],
"sites_count": 6
},
{
"id": "c66e5a4cfe4e2571734021d8340a02c2",
"sport_key": "soccer_epl",
"sport_nice": "EPL",
"teams": ["Huddersfield Town", "Cardiff City"],
"commence_time": 1535205600,
"home_team": "Huddersfield Town",
"sites": [
{
"site_key": "unibet",
"site_nice": "Unibet",
"last_update": 1535157373,
"odds": { "h2h": [2.4, 3.65, 3] }
},
{
"site_key": "betvictor",
"site_nice": "Bet Victor",
"last_update": 1535157374,
"odds": { "h2h": [2.4, 3.6, 3] }
},
{
"site_key": "ladbrokes",
"site_nice": "Ladbrokes",
"last_update": 1535157143,
"odds": { "h2h": [2.3, 3.4, 2.9] }
},
{
"site_key": "betfair",
"site_nice": "Betfair",
"last_update": 1535157209,
"odds": { "h2h": [2.46, 3.7, 3.05] }
},
{
"site_key": "skybet",
"site_nice": "Sky Bet",
"last_update": 1535157054,
"odds": { "h2h": [2.38, 3.4, 2.9] }
},
{
"site_key": "paddypower",
"site_nice": "Paddy Power",
"last_update": 1535157357,
"odds": { "h2h": [2.3, 3.5, 2.88] }
}
],
"sites_count": 6
},
{
"id": "d676957e3a4a2d652c7c4237869f7c0b",
"sport_key": "soccer_epl",
"sport_nice": "EPL",
"teams": ["Southampton", "Leicester City"],
"commence_time": 1535205600,
"home_team": "Southampton",
"sites": [
{
"site_key": "unibet",
"site_nice": "Unibet",
"last_update": 1535157373,
"odds": { "h2h": [2.45, 3.2, 3.3] }
},
{
"site_key": "betvictor",
"site_nice": "Bet Victor",
"last_update": 1535157374,
"odds": { "h2h": [2.4, 3.3, 3.25] }
},
{
"site_key": "ladbrokes",
"site_nice": "Ladbrokes",
"last_update": 1535157143,
"odds": { "h2h": [2.35, 3.2, 3.1] }
},
{
"site_key": "skybet",
"site_nice": "Sky Bet",
"last_update": 1535157054,
"odds": { "h2h": [2.3, 3.2, 3.2] }
},
{
"site_key": "paddypower",
"site_nice": "Paddy Power",
"last_update": 1535157357,
"odds": { "h2h": [2.4, 3.1, 3.2] }
},
{
"site_key": "betfair",
"site_nice": "Betfair",
"last_update": 1535157209,
"odds": { "h2h": [2.44, 3.3, 3.4] }
}
],
"sites_count": 6
}
]
}
Head to head (moneyline) odds are in the same order as teams. For 3 outcome sports, the 3rd item in the h2h list is the draw odd.
Example For the first event in the above response, the odds for Unibet are Bournemouth: 2.65, Everton: 2.7, Draw: 3.6
idis a unique game id. For details on how this is constructed, see the release notes
# Response Headers
The following response headers are returned
- x-requests-remaining  The number of requests remaining until the quota resets
- x-requests-used  The number of requests used since the last quota reset
Occasionally a bookmaker might disappear from the API response. This can happen for a number of reasons, for example, their site might be down for maintenance or they may have changed their site. These situations are often short-lived.
# Code Samples
Get started right away with code samples for Python and NodeJs. Code samples are also available on Github (opens new window)
# More Info
Odds may be unavailable if the sport is not in season. Odds may temporarily become unavailable if bookmakers stop listing games in between rounds. If no odds are returned, the request will not count against the usage quota.
We continually add sports, bookmakers and features. Stay up to date by following us on Twitter (opens new window)