Live Odds API - Quickstart v3

Get Started

Get started with the odds api in 3 steps

Step 1 Get an API key

Get an API key via email

See plans

Step 2 Get sports

Get a list of in-season sports

Request api.the-odds-api.com/v3/sports/?apiKey=YOUR_API_KEY Response
{
    "key": "soccer_epl",
    "active": true,
    "group": "Soccer - UK",
    "details": "English Premier League 🇬🇧",
    "title": "EPL"
},
  ...
                
More details

Step 3 Get odds

Get odds using the sport key from step 2.

The region parameter controls the returned bookmakers. Valid regions are us (United States), uk (United Kingdom) and au (Australia).

The mkt parameter is optional and defaults to head to head (moneyline). Valid markets are h2h (moneyline), spreads (point spreads), and totals (over/under).

Request api.the-odds-api.com/v3/odds?sport=soccer_epl&region=uk&mkt=h2h&apiKey=YOUR_API_KEY Response
{
    "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
                ]
            }
        },
  ...
            
More details

Details

All requests use the host
https://api.the-odds-api.com

GET sports

GET   /v3/sports/?apiKey={apiKey}
Request Headers  Accept: application/json
Returns a list of in-season sport objects. The sport key can be used as the {sport} parameter in the /odds requests. This request does not contribute to usage quotas.

Parameters

  • apiKey   The API key is emailed when you sign up to a plan. See usage plans at https://the-odds-api.com
  • all   Optional - if this parameter is present (for example, all=1), a list of all sports (in and out of season) will be returned

Testing

API requests work in the browser, making testing easy:
https://api.the-odds-api.com/v3/sports/?apiKey=YOUR_API_KEY

Example Request

curl -H "Accept: application/json" -X GET "https://api.the-odds-api.com/v3/sports/?apiKey=YOUR_API_KEY"

Example Response

                                
Loading...

Response Headers

Calls to the /sports method will not affect the quota usage. For plans with quotas, 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

GET   /v3/odds/?apiKey={apiKey}&sport={sport}&region={region}&mkt={mkt}
Request Headers  Accept: application/json
Returns the most recent odds for a given sport, region and market

Parameters

  • sport   Sport keys change as sports go in and out of season. For a list of sport keys, call the /sports method below and use the key field. Note upcoming is always valid, and will return any live games as well as the next 8 upcoming games across all sports.
  • region   Determines which bookmakers are returned. Valid regions are au (Australia), uk (United Kingdom) and us (United States)
  • mkt   Optional - defaults to h2h (head to head or moneyline). Valid markets are h2h, spreads (handicaps) and totals (over/under).
    Non-h2h markets are only available for paid plans. These markets are not always as comprehensive as h2h, so they do not count against the quota.
  • apiKey   The API key is emailed when you sign up to a plan. See usage plans at https://the-odds-api.com

Testing

API requests work in the browser, making testing easy:
https://api.the-odds-api.com/v3/odds/?sport=upcoming&region=uk&mkt=h2h&apiKey=YOUR_API_KEY

Example Request

curl -H "Accept: application/json" -X GET "https://api.the-odds-api.com/v3/odds/?apiKey=YOUR_API_KEY&sport=soccer_epl&region=uk&mkt=h2h"

Example Response

                                
Loading...
Note 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.

For example, for the first event in the above response, the odds for Unibet are Wolverhampton Wanderers: 11.75, Manchester City: 1.27, Draw: 6.6

Response Headers

For plans with quotas, 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