top of page

Scores, Odds, & Promos API

Introduction

Welcome to the Scores, Odds, & Promos API docs!  The easiest way to access aggregated data from all sportsbooks including scores, odds, historical odds, promotions, odds boosts, Same Game Parlays (SGP), and more.

See the current lists of all bookmakers, markets, sports, and bookmaker promos available.

Get Started

Get Started

Step 1

Select your plan to get an API key.

Step 2

Get the list of in-season sports

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

Host

Base URL

All requests use the following format, where "Suffix" will be filled in based on the request: https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix={Suffix}

GET sports

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.

Suffix

GET sports/?apiKey={apiKey}

Parameters

  • apiKey  An API key is emailed when you sign up for a plan. See here for 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

Example Request

GET https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix=sports/?apiKey={apiKey}

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

  }

]

Response Headers

Calls to the /sports endpoint will not affect the quota usage.

GET odds

GET odds

Returns a list of upcoming and live games with recent odds for a given sport, region and market.

See the current lists of all bookmakers, markets, and sports covered.

​Suffix

GET sports/{sport}/odds/?apiKey={apiKey}&regions={regions}&markets={markets}

Parameters

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

  • sport   The sport key is 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, us2 (United States), uk (United Kingdom), au (Australia) and eu (Europe). Multiple regions can be specified if comma delimited. See the 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.

  • eventIds   Optional - Comma-separated game ids. Filters the response to only return games for the specified game ids.

  • bookmakers   Optional - Comma-separated list of bookmakers to be returned. If both bookmakers and regions are both specified, bookmakers takes priority. Bookmakers can be from any region. Every group of 10 bookmakers is the equivalent of 1 region. For example, specifying up to 10 bookmakers counts as 1 region. Specifying between 11 and 20 bookmakers counts as 2 regions.

  • commenceTimeFrom   Optional - filter the response to show games that commence on and after this parameter. Values are in ISO 8601 format, for example 2023-09-09T00:00:00Z

  • commenceTimeTo   Optional - filter the response to show games that commence on and before this parameter. Values are in ISO 8601 format, for example 2023-09-10T23:59:59Z

Example Request

GET https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix=sports/americanfootball_nfl/odds/?apiKey=YOUR_API_KEY&regions=us&markets=h2h,spreads&oddsFormat=american

Example Response

[

  {

    "id": "7c8e887a27e43988654b137a001f6d3b",

    "sport_key": "americanfootball_nfl",

    "sport_title": "NFL",

    "commence_time": "2023-10-15T17:03:00Z",

    "home_team": "Atlanta Falcons",

    "away_team": "Washington Commanders",

    "bookmakers": [

      {

        "key": "fanduel",

        "title": "FanDuel",

        "last_update": "2023-10-14T16:15:08Z",

        "markets": [

          {

            "key": "h2h",

            "last_update": "2023-10-14T16:15:08Z",

            "outcomes": [

              {

                "name": "Atlanta Falcons",

                "price": -130

              },

              {

                "name": "Washington Commanders",

                "price": 108

              }

            ]

          },

          {

            "key": "spreads",

            "last_update": "2023-10-14T16:15:08Z",

            "outcomes": [

              {

                "name": "Atlanta Falcons",

                "price": -110,

                "point": -2.5

              },

              {

                "name": "Washington Commanders",

                "price": -110,

                "point": 2.5

              }

            ]

          }

        ]

      }

    ]

  }

]

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

Usage Quota Cost

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

More info

  • The list of games returned in the /odds endpoint mirrors games that are listed by major bookmakers. This usually includes games for the current round

  • Games may temporarily become unavailable after a round, before bookmakers begin listing the next round of games

  • Games may be unavailable if the sport is not in season. For popular sports, bookmakers may begin listing new season games a few months in advance

  • If no games are returned, the request will not count against the usage quota

  • How to check if a game is live: The /odds endpoint response contains the commence_time of each game. This can be used to determine if a game is live or pre-match. If commence_time is greater than the current time, the game is pre-match. Otherwise the game is live. The /odds endpoint does not return completed games

 

GET scores

GET scores

Returns a list of upcoming, live and recently completed games for a given sport. Live and recently completed games contain scores. Games from up to 3 days ago can be returned using the daysFrom parameter. Live scores update approximately every 30 seconds.

See the current list of covered sports and leagues.

Suffix

GET sports/{sport}/scores/?apiKey={apiKey}&daysFrom={daysFrom}&dateFormat={dateFormat}

Parameters

  • sport   The sport key obtained from calling the /sports endpoint.

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

  • daysFrom   Optional - The number of days in the past from which to return completed games. Valid values are integers from 1 to 3. If this parameter is missing, only live and upcoming games are returned.

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

  • eventIds   Optional - Comma-separated game ids. Filters the response to only return games for the specified game ids.

Example Request

GET https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix=sports/basketball_nba/scores/?daysFrom=1&apiKey=YOUR_API_KEY

Example Response

[

  {

    "id": "fd55db2fa9ee5be1f108be5151e2ecb0",

    "sport_key": "basketball_nba",

    "sport_title": "NBA",

    "commence_time": "2023-10-24T23:30:00Z",

    "completed": false,

    "home_team": "Denver Nuggets",

    "away_team": "Los Angeles Lakers",

    "scores": null,

    "last_update": null

  }

]

Tip: The game id field in the scores response matches the game id field in the odds response

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 Cost

The usage quota cost is 2 if the daysFrom parameter is specified (returning completed events), otherwise the usage quota cost is 1.

Examples

  • Return live and upcoming games, and games completed within the last 3 days

    • Only live and completed games will have scores

    • Cost: 2

    • Example /v4/sports/americanfootball_nfl/scores?daysFrom=3&apiKey=...

  • Return live and upcoming games

    • Only live games will have scores

    • Cost: 1

    • Example /v4/sports/americanfootball_nfl/scores?apiKey=...

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

 

 

GET historical odds   BETA

GET historical odds

Returns a snapshot of games with bookmaker odds for a given sport, region, and market, at a given historical date. Historical odds data 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.

Suffix

GET sports/{sport}/odds-history/?apiKey={apiKey}&regions={regions}&markets={markets}&date={date}

Parameters

​Parameters are the same as for the /odds endpoint, with the addition of the date parameter.

  • date   The timestamp of the data snapshot to be returned, specified in ISO8601 format, for example, 2021-10-18T12:00:00Z The historical odds API will return the closest snapshot equal to or earlier than the provided date parameter.

Example Request

GET https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix=sports/{sport}/odds-history/?apiKey={apiKey}&regions={regions}&markets={markets}&date={date}

Example Response

The response schema is the same as that of the /odds 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 date parameter.

  • previous_timestamp   The preceding available timestamp. This can be used as the date parameter in a new request to move back in time.

  • next_timestamp   The next available timestamp. This can be used as the date parameter in a new request to move forward in time.

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 Cost

The usage quota cost for historical odds is 10 per region per market.

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

Examples

  • 1 market, 1 region

    • Cost: 10

    • Example /v4/sports/americanfootball_nfl/odds-history?markets=h2h&regions=us&...

  • 3 markets, 1 region

    • Cost: 30

    • Example /v4/sports/americanfootball_nfl/odds-history?markets=h2h,spreads,totals&regions=us&...

  • 1 market, 3 regions

    • Cost: 30

    • Example /v4/sports/soccer_epl/odds-history?markets=h2h&regions=us,uk,eu&...

  • 3 markets, 3 regions

    • Cost: 90

    • Example: /v4/sports/basketball_nba/odds-history?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

More Info

  • Responses with empty data do not count towards the usage quota.

  • Prior to September 18th, 2022, only decimal odds were captured in historical snapshots. American odds before this time are calculated from decimal odds and may include small rounding errors.

  • Data errors aren't common but they can occur from time to time. We are usually quick to correct errors in the regular API, however, they can still be captured in historical odds snapshots. In the future we plan to remove known errors from historical snapshots.

  • Bookmakers and sports will only be available in the historical odds API after the time that they were added to the regular odds API.

  • Requests may be slower for data further back in time. This is by design, as we have optimized for more recent data, which we anticipate is likely to be requested more often.

GET event odds   BETA

GET event odds

Returns odds for a single game. Accepts any available betting markets using the markets parameter. Coverage of non-featured markets is currently limited to selected bookmakers and sports, and expanding over time.

When to use this endpoint

We're gradually adding odds for additional betting markets. Use this endpoint to access odds for any supported market. Since the volume of data returned for these new markets can be large, we have decided to restrict requests to one event at a time. If you are only interested in the most popular betting markets, including head-to-head (moneyline), point spreads (handicap), over/under (totals), the main /odds endpoint is simpler to integrate and more cost-effective.

Suffix

GET sports/{sport}/events/{eventId}/odds?apiKey={apiKey}&regions={regions}&markets={markets}&dateFormat={dateFormat}&oddsFormat={oddsFormat}

Parameters

Parameters are the same as for the /odds endpoint with the addition of the eventId in the path. All available market keys are accepted in the markets parameter.

  • eventId   The id of an upcoming or live game. Event ids can be found in the "id" field in response of main /odds endpoint.

Example Request

GET https://oddsboostapi.azurewebsites.net/OddsAndScores/Get?suffix=sports/{sport}/events/{eventId}/odds?apiKey={apiKey}&regions={regions}&markets={markets}&dateFormat={dateFormat}&oddsFormat={oddsFormat}

Example Response

The response schema is almost the same as that of the /odds endpoint with a few differences:

  • A single game is returned, determined by the eventId parameter.

  • The last_update field is only available on the market level in the response and not on the bookmaker level. This reflects the fact that markets can update on their own schedule.

  • Relevant markets will have a description field in their outcomes.

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 Cost

The usage quota cost depends on the number of markets and regions used in the request.

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

Examples

  • 1 market, 1 region

    • Cost: 1

    • Example /v4/sports/americanfootball_nfl/events/a512a48a58c4329048174217b2cc7ce0/odds?markets=h2h&regions=us&...

  • 3 markets, 1 region

    • Cost: 3

    • Example /v4/sports/americanfootball_nfl/events/a512a48a58c4329048174217b2cc7ce0/odds?markets=h2h,spreads,totals&regions=us&...

  • 1 market, 3 regions

    • Cost: 3

    • Example /v4/sports/soccer_epl/events/037d7b6bb128546961e2a06680f63944/odds?markets=h2h&regions=us,uk,eu&...

  • 3 markets, 3 regions

    • Cost: 9

    • Example: /v4/sports/basketball_nba/events/0b83beff5f82f8623eea93dbc1d7cd4e/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

More Info

  • Responses with empty data do not count towards the usage quota.

  • When calculating the market component of usage quota costs, a count of unique markets in the API response is used. For example, if you specify 5 different markets and 1 region in the API call, and data is only available for 2 markets, the cost will be [2 markets] x [1 region] = 2

  • We don't standardize the description field for applicable markets at this time. For example for player prop markets, player names might occasionally differ across bookmakers.

GET promos/odd boosts

GET promos/odds boosts

Returns sportsbook banner promotions (the horizontally scrollable banners a the top of the sportsbook app) based on user location.

Screenshot 2023-09-21 at 7.40_edited.jpg

All "Intake" endpoints will return the same class, see the structure below:

Parameters

 

  • promoCode (nullable string)   This field will show the promo code of the boost/promotion if there is one provided

    • example: "5XWPQ"

 

  • name (nullable string)   This field is a high-level description of the boost/promotion. In some cases, this also comes through with HTML.

    • Example: "<p> All customers get TWO 50% PBTs to use on a College Football Parlay for games on 9/7-9/9! </p>"

  • parsedName (nullable string)   This field is a high-level description of the boost/promotion. This field won't contain HTML.

    • Example: "All customers get TWO 50% PBTs to use on a College Football Parlay for games on 9/7-9/9!"

  • title (nullable string)   This field is usually a more high-level, readable version of the name. In some cases, this also comes through with HTML.

    • Example: "<p> College Football Parlay Profit Boost </p>"

  • parsedTitle (nullable string)   This field is usually a more high-level, readable version of the name. This field won't contain HTML.

    • Example: "College Football Parlay Profit Boost"

  • description (nullable string)   This field is going to contain the most detail about the boost/promotion. In some cases, this also comes through with HTML. 

    • Example: "<p><b>How it Works:</b></p><ol><li>Click \"Claim Now\" on the home page to claim your Profit Boost Token</li><li>After clicking “Claim Now” on the Promotion, you will be awarded a 25% Profit Boost Token</li><li>..."

  • parsedDescription (nullable string)   This field is going to contain the most detail about the boost/promotion. This field won't contain HTML.

    • Example: "How it Works: Click \"Claim Now\" on the home page to claim your Profit Boost Token After clicking “Claim Now” on the Promotion, you will be awarded a 25% Profit Boost Token..."

  • termsAndConditions (nullable string)   This field contains the TOS of the boost/promotion. In some cases, this also comes through with HTML.

    • Example: "...style=\"font-size: 10pt; line-height: 15.3333px;\">The Promotion is only open to individuals who are at least 21 years of age and are physically present in Arizona,..."

  • parsedTermsAndConditions (nullable string)   ​This field contains the TOS of the boost/promotion. This field won't contain HTML.

    • Example: "...The Promotion is only open to individuals who are at least 21 years of age and are physically present in Arizona,..."

  • images (array Image)   This field will contain an array of images used for the boost/promotion. (See Image class below for more information)

  • product (nullable string)   This field will show what product the boost/promotion pertains to.

    • Example: "SPORTSBOOK"

  • endDate (nullable string)   This field will show when the boost/promotion expires.

    • Example: "09/17/2023 06:00:00"

  • location (nullable string)   This field will show what state this boost/promotion is in (should be the same as the parameter).

    • Example: "NJ"

  • site (nullable string)   This field will show what site is used to get the boosts (should be the same as the endpoint).

    • Example: "FanDuel"

Image class​ parameters

Rate Limiting (status code 429)

Rate Limiting (status code 429)

Requests are rate limited in order to protect our systems from sudden bursts in traffic. This means there's a cap on the number of requests can that be sent each second. The rate limit can change depending on the system load. In most cases this shouldn't be an issue, however it can occur if too many requests are sent concurrently. If you enounter the rate limit, the API will respond with a status code of 429, in which case we recommend spacing out requests over several seconds.
 

bottom of page