# Odds API Docs V4

These docs are for version 4, the latest version of the API. Docs for version 3 can be found here.

# Overview

Get started with the odds API in 3 steps

Step 1
Get an API key via email
See plans


Step 2

Get a list of in-season sports

Details

{
  "key": "americanfootball_nfl",
  "group": "American Football",
  "title": "NFL",
  "description": "US Football",
  "active": true,
  "has_outrights": false
},
...


Step 3

Use the sport key from step 2 to get a list of upcoming events and odds from different bookmakers


Use the oddsFormat parameter to show odds in either decimal or American format

Details

{
  "id": "bda33adca828c09dc3cac3a856aef176",
  "sport_key": "americanfootball_nfl",
  "commence_time": "2021-09-10T00:20:00Z",
  "home_team": "Tampa Bay Buccaneers",
  "away_team": "Dallas Cowboys",
  "bookmakers": [
  {
    "key": "fanduel",
    "title": "FanDuel",
    "last_update": "2021-06-10T10:46:09Z",
    "markets": [
    {
      "key": "h2h",
      "outcomes": [
        {
          "name": "Dallas Cowboys", 
          "price": 240 
        },
        {
          "name": "Tampa Bay Buccaneers", 
          "price": -303
        }
      ]
  ...


# 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 cost the usage quota.

# Endpoint


GET /v4/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 set to true (all=true), a list of both in and out of season sports will be returned


Try it out in the browser

# Schema

For a detailed API spec, checkout the Swagger API docs (opens new window)

# Example Request


# Example Response


[
    {
        "key": "americanfootball_ncaaf",
        "group": "American Football",
        "title": "NCAAF",
        "description": "US College Football",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "americanfootball_nfl",
        "group": "American Football",
        "title": "NFL",
        "description": "US Football",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "americanfootball_nfl_super_bowl_winner",
        "group": "American Football",
        "title": "NFL Super Bowl Winner",
        "description": "Super Bowl Winner 2021/2022",
        "active": true,
        "has_outrights": true
    },
    {
        "key": "aussierules_afl",
        "group": "Aussie Rules",
        "title": "AFL",
        "description": "Aussie Football",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "baseball_mlb",
        "group": "Baseball",
        "title": "MLB",
        "description": "Major League Baseball",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "basketball_nba",
        "group": "Basketball",
        "title": "NBA",
        "description": "US Basketball",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "cricket_test_match",
        "group": "Cricket",
        "title": "Test Matches",
        "description": "International Test Matches",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "golf_masters_tournament_winner",
        "group": "Golf",
        "title": "Masters Tournament Winner",
        "description": "2022 WInner",
        "active": true,
        "has_outrights": true
    },
    {
        "key": "golf_the_open_championship_winner",
        "group": "Golf",
        "title": "The Open Winner",
        "description": "2021 WInner",
        "active": true,
        "has_outrights": true
    },
    {
        "key": "golf_us_open_winner",
        "group": "Golf",
        "title": "US Open Winner",
        "description": "2021 WInner",
        "active": true,
        "has_outrights": true
    },
    {
        "key": "icehockey_nhl",
        "group": "Ice Hockey",
        "title": "NHL",
        "description": "US Ice Hockey",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "mma_mixed_martial_arts",
        "group": "Mixed Martial Arts",
        "title": "MMA",
        "description": "Mixed Martial Arts",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "rugbyleague_nrl",
        "group": "Rugby League",
        "title": "NRL",
        "description": "Aussie Rugby League",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_australia_aleague",
        "group": "Soccer",
        "title": "A-League",
        "description": "Aussie Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_brazil_campeonato",
        "group": "Soccer",
        "title": "Brazil Série A",
        "description": "Brasileirão Série A",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_denmark_superliga",
        "group": "Soccer",
        "title": "Denmark Superliga",
        "description": "",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_finland_veikkausliiga",
        "group": "Soccer",
        "title": "Veikkausliiga - Finland",
        "description": "",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_japan_j_league",
        "group": "Soccer",
        "title": "J League",
        "description": "Japan Soccer League",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_league_of_ireland",
        "group": "Soccer",
        "title": "League of Ireland",
        "description": "Airtricity League Premier Division",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_norway_eliteserien",
        "group": "Soccer",
        "title": "Eliteserien - Norway",
        "description": "Norwegian Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_spain_segunda_division",
        "group": "Soccer",
        "title": "La Liga 2 - Spain",
        "description": "Spanish Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_sweden_allsvenskan",
        "group": "Soccer",
        "title": "Allsvenskan - Sweden",
        "description": "Swedish Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_sweden_superettan",
        "group": "Soccer",
        "title": "Superettan - Sweden",
        "description": "Swedish Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_uefa_european_championship",
        "group": "Soccer",
        "title": "UEFA Euro 2020",
        "description": "UEFA European Championship",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "soccer_usa_mls",
        "group": "Soccer",
        "title": "MLS",
        "description": "Major League Soccer",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "tennis_atp_french_open",
        "group": "Tennis",
        "title": "ATP French Open",
        "description": "Men's Singles",
        "active": true,
        "has_outrights": false
    },
    {
        "key": "tennis_wta_french_open",
        "group": "Tennis",
        "title": "WTA French Open",
        "description": "Women's Singles",
        "active": true,
        "has_outrights": false
    }
]

# Response Headers

Calls to the /sports endpoint 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 /v4/sports/{sport}/odds/?apiKey={apiKey}&regions={regions}&markets={markets}

# Parameters

  • sport   The sport key obtained from calling the /sports endpoint. upcoming is always valid, returning any live games as well as the next 8 upcoming games across all sports

  • apiKey   An API key is emailed when you sign up to a plan. See here for usage plans

  • regions   Determines the bookmakers to be returned. Valid regions are us (United States), uk (United Kingdom), au (Australia) and eu (Europe). Multiple regions can be specified if comma delimited. See here for a list of bookmakers by region.

  • markets   Optional - Determines which odds market is returned. Defaults to h2h (head to head / moneyline). Valid markets are h2h (moneyline), spreads (points handicaps), totals (over/under) and outrights (futures). Multiple markets can be specified if comma delimited. spreads and totals markets are mainly available for US sports and bookmakers at this time. Each specified market costs 1 against the usage quota, for each region.

    Lay odds are automatically included with h2h results for relevant betting exchanges (Betfair, Matchbook etc). These have a h2h_lay market key.

    For sports with outright markets (such as Golf), the market will default to outrights if not specified. Lay odds for outrights (outrights_lay) will automatically be available for relevant exchanges.

    For more info, see descriptions of betting markets.

  • dateFormat   Optional - Determines the format of timestamps in the response. Valid values are unix and iso (ISO 8601). Defaults to iso.

  • oddsFormat   Optional - Determines the format of odds in the response. Valid values are decimal and american. Defaults to decimal. When set to american, small discrepancies might exist for some bookmakers due to rounding errors.


Try it out in the browser

# Schema

For a detailed API spec, checkout the Swagger API docs (opens new window)

# Example Request


# Example Response


[
    {
        "id": "bda33adca828c09dc3cac3a856aef176",
        "sport_key": "americanfootball_nfl",
        "commence_time": "2021-09-10T00:20:00Z",
        "home_team": "Tampa Bay Buccaneers",
        "away_team": "Dallas Cowboys",
        "bookmakers": [
            {
                "key": "unibet",
                "title": "Unibet",
                "last_update": "2021-06-10T13:33:18Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -303
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -109,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -111,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "caesars",
                "title": "Caesars",
                "last_update": "2021-06-10T13:33:48Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -278
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "sugarhouse",
                "title": "SugarHouse",
                "last_update": "2021-06-10T13:34:07Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -305
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -109,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -112,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "draftkings",
                "title": "DraftKings",
                "last_update": "2021-06-10T13:33:26Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -305
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -109,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -112,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "pointsbetus",
                "title": "PointsBet (US)",
                "last_update": "2021-06-10T13:36:20Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 230
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -291
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "betonlineag",
                "title": "BetOnline.ag",
                "last_update": "2021-06-10T13:37:29Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -286
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -105,
                                "point": 6
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -115,
                                "point": -6
                            }
                        ]
                    }
                ]
            },
            {
                "key": "betmgm",
                "title": "BetMGM",
                "last_update": "2021-06-10T13:32:45Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 225
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -275
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "betrivers",
                "title": "BetRivers",
                "last_update": "2021-06-10T13:35:33Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -305
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -109,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -112,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "fanduel",
                "title": "FanDuel",
                "last_update": "2021-06-10T13:33:23Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 225
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -275
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "barstool",
                "title": "Barstool Sportsbook",
                "last_update": "2021-06-10T13:34:48Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -305
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -109,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -112,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "bovada",
                "title": "Bovada",
                "last_update": "2021-06-10T13:35:51Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -290
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            },
            {
                "key": "williamhill_us",
                "title": "William Hill (US)",
                "last_update": "2021-06-10T13:34:10Z",
                "markets": [
                    {
                        "key": "h2h",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": 240
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -280
                            }
                        ]
                    },
                    {
                        "key": "spreads",
                        "outcomes": [
                            {
                                "name": "Dallas Cowboys",
                                "price": -110,
                                "point": 6.5
                            },
                            {
                                "name": "Tampa Bay Buccaneers",
                                "price": -110,
                                "point": -6.5
                            }
                        ]
                    }
                ]
            }
        ]
    },
...

# 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

# Usage Quota Costs

The usage quota cost is 1 per region per market.

cost = [number of markets specified] x [number of regions specified]

Examples

  • 1 market, 1 region
    Cost: 1
    Example /v4/sports/americanfootball_nfl/odds?markets=h2h&regions=us&...

  • 3 markets, 1 region
    Cost: 3
    Example /v4/sports/americanfootball_nfl/odds?markets=h2h,spreads,totals&regions=us&...

  • 1 market, 3 regions
    Cost: 3
    Example /v4/sports/soccer_epl/odds?markets=h2h&regions=us,uk,eu&...

  • 3 markets, 3 regions
    Cost: 9
    Example: /v4/sports/basketball_nba/odds?markets=h2h,spreads,totals&regions=us,uk,au&...


Keeping track of quota usage

To keep track of requests used and remaining on an API key, every API response includes the following response headers:

  • x-requests-used
  • x-requests-remaining


# 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

  • Games will be unavailable if the sport is not in season
  • Games may temporarily become unavailable after a round, before bookmakers begin listing the next round
  • If no games are returned, the request will not count against the usage quota

Stay up to date on new sports, bookmakers and features by following us on Twitter (opens new window)