# Historical Odds Data
Historical odds data is available for all sports and bookmakers covered by The Odds API. Historical data is available as snapshots, which include events and bookmaker odds as they were at a point in time.
Historical odds data for featured markets is available from June 6th 2020, with snapshots taken at 10 minute intervals. From September 2022, historical odds snapshots are available at 5 minute intervals.
Historical odds data for additional markets, including player props, period markets and more, is available from May 3rd, 2023. Snapshots are available at 5 minute intervals.
Historical data is only available on paid usage plans.
# How to access historical odds data
# Historical odds data for featured markets
Featured markets include the most popular betting markets and are prominently displayed by bookmakers. Historical odds data for featured markets is available in JSON format using the API's historical odds endpoint.
# Example API Request
The input parameters are the same as those of the v4 odds API endpoint, with the addition of a date parameter which represents the timestamp of the snapshot to be queried. The historical odds API will return the closest snapshot equal to or earlier than the provided date parameter. The usage quota cost for the historical odds endpoint is 10 per region per market (more info).
GET https://api.the-odds-api.com/v4/historical/sports/americanfootball_nfl/odds?regions=us&oddsFormat=american&apiKey=YOUR_API_KEY&date=2021-10-18T12:00:00Z
# Example API Response
The response schema is the same as that of the v4 odds API endpoint, but wrapped in a structure that contains information about the snapshot, including:
- timestamp: The timestamp of the snapshot. This will be the closest available timestamp equal to or earlier than the provided
dateparameter. - previous_timestamp: the preceding available timestamp. This can be used as the
dateparameter in a new request to move back in time. - next_timestamp: The next available timestamp. This can be used as the
dateparameter in a new request to move forward in time.
{
"timestamp": "2021-10-18T11:55:00Z",
"previous_timestamp": "2021-10-18T11:45:00Z",
"next_timestamp": "2021-10-18T12:05:00Z",
"data": [
{
"id": "4edd5ce090a3ec6192053b10d27b87b0",
"sport_key": "americanfootball_nfl",
"sport_title": "NFL",
"commence_time": "2021-10-19T00:15:00Z",
"home_team": "Tennessee Titans",
"away_team": "Buffalo Bills",
"bookmakers": [
{
"key": "draftkings",
"title": "DraftKings",
"last_update": "2021-10-18T11:48:09Z",
"markets": [
{
"key": "h2h",
"outcomes": [
{
"name": "Buffalo Bills",
"price": -294
},
{
"name": "Tennessee Titans",
"price": 230
}
]
}
]
},
...# Historical odds data for additional markets
Historical odds data for additional markets, including player props, half/quarter time markets and more, can be queried one game at a time using the historical event odds endpoint.
# Example API Request
The input parameters are the same as those of the v4 event-odds API endpoint, with the addition of a date parameter which represents the timestamp of the snapshot to be queried. The historical odds API will return the closest snapshot equal to or earlier than the provided date parameter. The usage quota cost for the historical event-odds endpoint is 10 per region per market per event (more info).
In this example, da359da99aa27e97d38f2df709343998 is the id of the Lakers @ Pistons game on 2023-11-30. The historical events endpoint can be used to find event ids.
GET https://api.the-odds-api.com/v4/historical/sports/basketball_nba/events/da359da99aa27e97d38f2df709343998/odds?apiKey=YOUR_API_KEY&date=2023-11-29T22:45:00Z®ions=us&markets=player_points,h2h_q1
# Example API Response
The response schema is the same as that of the v4 event-odds API endpoint, but wrapped in a structure that contains information about the snapshot, including:
- timestamp: The timestamp of the snapshot. This will be the closest available timestamp equal to or earlier than the provided
dateparameter. - previous_timestamp: the preceding available timestamp. This can be used as the
dateparameter in a new request to move back in time. - next_timestamp: The next available timestamp. This can be used as the
dateparameter in a new request to move forward in time.
{
"timestamp": "2023-11-29T22:40:39Z",
"previous_timestamp": "2023-11-29T22:35:39Z",
"next_timestamp": "2023-11-29T22:45:40Z",
"data": {
"id": "da359da99aa27e97d38f2df709343998",
"sport_key": "basketball_nba",
"sport_title": "NBA",
"commence_time": "2023-11-30T00:10:00Z",
"home_team": "Detroit Pistons",
"away_team": "Los Angeles Lakers",
"bookmakers": [
{
"key": "draftkings",
"title": "DraftKings",
"last_update": "2023-11-29T22:40:09Z",
"markets": [
{
"key": "h2h_q1",
"last_update": "2023-11-29T22:40:55Z",
"outcomes": [
{
"name": "Detroit Pistons",
"price": 2.5
},
{
"name": "Los Angeles Lakers",
"price": 1.56
}
]
},
{
"key": "player_points",
"last_update": "2023-11-29T22:40:55Z",
"outcomes": [
{
"name": "Over",
"description": "Anthony Davis",
"price": 1.83,
"point": 23.5
},
{
"name": "Under",
"description": "Anthony Davis",
"price": 1.91,
"point": 23.5
},
{
"name": "Over",
"description": "Ausar Thompson",
"price": 1.87,
"point": 11.5
},
{
"name": "Under",
"description": "Ausar Thompson",
"price": 1.87,
"point": 11.5
},
{
"name": "Over",
"description": "Cade Cunningham",
"price": 1.91,
"point": 23.5
},
{
"name": "Under",
"description": "Cade Cunningham",
"price": 1.83,
"point": 23.5
},
{
"name": "Over",
"description": "D'Angelo Russell",
"price": 1.87,
"point": 14.5
},
...# Sample Historical Odds Data
The historical odds API is only available on paid subscriptions at this time. This section provides examples of API requests and responses to demonstrate usage of the historical odds API.
This section only covers a small selection of sports. Historical odds data is available for all sports covered in the API from the time the sport was added to the API. See the full list of sports. (opens new window).
# Historical NFL odds data
- Moneyline (h2h), point spreads (spreads) and over/under (totals)
- US bookmakers
- Snapshot date 2021-11-25T12:00:00Z
- American odds format
Request:
https://api.the-odds-api.com/v4/historical/sports/americanfootball_nfl/odds?apiKey=YOUR_API_KEY®ions=us&markets=h2h,spreads,totals&oddsFormat=american&date=2021-11-25T12:00:00Z
Response: Download historical odds API response for NFL
# Historical EPL odds data
- 1x2 (h2h)
- UK bookmakers
- Date 2021-10-30T00:00:00Z
- Decimal odds format
Request:
https://api.the-odds-api.com/v4/historical/sports/soccer_epl/odds?apiKey=YOUR_API_KEY®ions=uk&markets=h2h&date=2021-10-30T00:00:00Z
Response: Download historical odds API response for EPL
# Historical German Bundesliga odds data
- 1x2 (h2h)
- EU bookmakers
- Date 2022-10-18T02:00:00Z
- Decimal odds format
Request:
https://api.the-odds-api.com/v4/historical/sports/soccer_germany_bundesliga/odds?apiKey=YOUR_API_KEY®ions=eu&markets=h2h&date=2022-10-18T02:00:00Z
Response: Download historical odds API response for Bundesliga
# Historical AFL odds data
- Head to head (h2h)
- AU bookmakers
- Date 2022-04-25T00:00:00Z
- Decimal odds format
Request:
https://api.the-odds-api.com/v4/historical/sports/aussierules_afl/odds?apiKey=YOUR_API_KEY®ions=au&markets=h2h&date=2022-04-25T00:00:00Z
Response: Download historical odds API response for AFL
# Historical US presidential elections winner odds data
- Futures (outrights)
- US bookmakers
- Date 2020-10-31T00:00:00Z (note coverage of US bookmakers was limited in 2020)
- American odds format
Request:
https://api.the-odds-api.com/v4/historical/sports/politics_us_presidential_election_winner/odds?apiKey=YOUR_API_KEY®ions=us&oddsFormat=american&date=2020-10-31T00:00:00Z
Response: Download historical odds API response for US Presidential Election Winner
# Get Access
Historical odds data is only available for paid subscriptions at this time. Get an API key by subscribing to a usage plan.
Subscriptions can also be managed in the accounts portal.