Aggregated Odds Integration Guide

This article is also available at sportsdata.io.

Description

Explanation about Betting Event architecture and the various data objects related such as Betting Markets, Types, Period and Outcomes.

Subject

HIGH LEVEL OVERVIEW

The Aggregated Odds Feed is designed to aggregate and link up the odds from various sportsbooks from Money Lines and Point Spreads to Player Props and Futures. It is a comprehensive system meant to give you a complete view of a particular game or future and its set of odds.

The following diagram presents a high-level overview of the architecture and how the various data objects are related. Below are sections detailing each object in finer detail.

The diagram uses the NBA as an example but the data architecture is the same across all sports. For details on the data types of the fields on these objects, please see the data dictionaries under the "Aggregated Odds" heading:

Golf

Please see these notes, which detail the differences that exist in the Golf aggregated odds APIs.

The *Types

Throughout this guide and while using the aggregated odds feed, you'll come across the *Types fields (e.g. Betting Market Type, Betting Event Type, Betting Period Type). These are enumerations which are used to group and categorize the data objects which make up the aggregated odds feed. The guide below details these *Types. For a complete list of these *Types, please see the following endpoints, which return lists of all of values you will encounter:

Timeline For Player Props

Sportsbooks release player props at different times for each sport. For example, NFL player props are released early in the week while for other sports like MLB, player props are released much closer to the time of the game. Please see the table below for approximately when sportsbooks begin to list the first few player props for a game. They'll then continue to release player props up until the game starts.

BETTING EVENTS, BETTING MARKETS AND BETTING OUTCOMES

Betting Event

The Betting Event is the root level object: all other data objects are children of this object
At current, it will be one of two Betting Event Types:
- Game - Betting Events which point to a game record and will contain child items related to that game
- Future - Betting Events which span an entire season or tournament

Betting Market

The data object which holds information on the specific bets (and their selections) for the parent Betting Event
Five core fields which identify the characteristics of the betting market:
- Betting Market Type - Describes the market grouping e.g. Game Line, Player Prop, Team Prop, etc
- Betting Bet Type - Describes the type of bet e.g. Moneyline, Point Spread, Total Points, Total Assists, etc
- Betting Period Type - Specifies the time dimension of the market e.g Full Game, 1st Half, 3rd Quarter, Regulation Time (Excluding Overtime), etc
- Player Id - If the Betting Market applies to a single player, this field will contain the Player Id e.g. "Lebron James Total Points 1st Half"
- Team Id - If the Betting Market applies to a single team, this field will contain the Team Id e.g. "LA Lakers Total Points 3rd Quarter"
Player Id and Team Id Considerations
- If the Player Id or Team Id have a value, all child Betting Outcomes will point to the respective Player Id or Team Id
Game Prop Considerations
- For Betting Markets which have a Betting Market Type of Game Prop, the child Betting Outcomes may contain different Player Ids and Team Ids
- Example of this would be bets like "First Player to Score a 3-pointer" or "Last Team to Score"

Betting Outcome

Per sportsbook, the object which contains information on the odds and values for the selections available on a Betting Market
A number of core fields:
- Betting Outcome Type
  - Used to determine which side a Betting Outcome represents e.g. Over, Under, Home, Away, Yes, No
  - For example on a Betting Bet Type of Total Points, you will see options for “Over” and “Under” which correspond to the over and under outcomes
- Value - Contains the value needed for the bet (if applicable)
  - For example, “Philadelphia Eagles Total Points” might contain outcomes where the value is 24. The “Over” means the bet would win if the Eagles score more than 24 points and the “Under” means the best would win if the Eagles score less than 23 points.
  - Typical bets which will have non-null Value include Point Spread and Totals
  - Betting Outcomes for something like a Betting Bet Type of Moneyline will have a null Value, as the bet isn’t based on any particular value (in the case of a Moneyline, it’s which team will win)
- PayoutAmerican/PayoutDecimal - The odds on this particular outcome
- Is Available - Indicates whether the outcome is currently open for wagering on the related sportsbook
- Sportsbook - Indicates which sportsbook is associated with this outcome
- Player Id - Points to the Player record for which this outcome corresponds
- Team Id - Points to the Team record for which this outcome corresponds

You will need to add a query string parameter to your API call if you wish to receive the unavailable BettingOutcomes.

The two options for the include query string parameter are as follows:

available: This will return only available BettingOutcome records. If you do not include a query string parameter this is what will occur.
unlisted: This will return all BettingOutcome records, even those removed by the sportsbooks. This will be delayed by 10-15 minutes to allow for caching, but provides a full record of all odds, even outdated or unlisted ones.

Sample API Call:

https://api.sportsdata.io/v3/nfl/odds/json/BettingMarketsByScoreID/18343?include=available

The following endpoints require the parameters:

Betting Market by Event
Betting Markets by Market Type
Betting Markets by GameID
Betting Player Props by GameID

The following sports require the parameters:

NFL
MLB
NBA
NHL
NCAA Football
NCAA Men's Basketball
Soccer (all leagues)
PGA
NASCAR
MMA

To take advantage of the increased performance and speed, you do not need to make any changes, as the include=available parameter will apply to any calls made without specifying a call type.

Should you wish to use the slower, less performant, but more detailed calls that exist today, you must change your queries to incorporate include=unlisted.

GOLF

There are a few differences in the Golf aggregated odds API which need to be taken into consideration. The differences originate from the fact that golf betting has its own nuances compared with, say, betting on the NBA or the NFL. The player pool per betting event is much larger and many bets offered by the sportsbooks involve a field of multiple golfers competing among themselves (i.e. SixShooter offerings).

Tournaments and Futures

At the moment, there is no concept of a Future type Betting Event in the Golf aggregated odds feed
A Betting Event points to a Tournament. If the Tournament Id is not set on a Betting Event, it is because the Tournmament is far in the future (i.e. next year's Masters), and once we have the Tournament record, they will be linked

Golfer Identification and Golfer Props

Unlike in the other sports, golfers are not currently defined at the Betting Market level. They are defined strictly at the Betting Outcome level
An example: in a market like "To Make/Miss The Cut", all outcomes related to this bet would go under one market. This is in contrast to the other sports where each player gets their own market for each prop i.e. "Bryce Harper Total RBIs"
If an outcome involves a particular golfer, the PlayerId on the Betting Outcome will point to the golfer. Otherwise it will be null, and you should look to the Betting Outcome Type field to determine the specifics of the Betting Outcome (i.e. it might be the "Tie" option in a head-to-head Matchup)
To replicate a structure like the single player Betting Market Player Props (as is done in the other sports), in your code you could group-by the PlayerId on the Betting Outcomes for a Betting Event. You'd then need to traverse the grouping and collect the betting market Ids, and relate them to each player, perhaps through a dictionary

Matchups, Groups and SixShooters

Many of the sportsbooks offer bets on groups of 2 or more golfers, where a bettor picks one of the golfers to have the best score in the particular group
There is often no overlap between these groups across sportsbooks, so we place them in a single betting market per kind of grouping (Head-to-Head/Matchup, SixShooter, etc)
You might see a market for the "Round 1 SixShooter". This Betting Market will contain all of the SixShooter offerings for the Tournament that we have synced from the sportsbooks
To identify which Betting Outcomes belong to the same original group , we expose a field on Betting Outcome called GroupKey, which links the Betting Outcomes together based on their original grouping at the Sportsbooks
An example: a sportsbook might offer 3 SixShooters, each with 6 golfers, for a total of 18 Betting Outcomes. All 18 of these outcomes would be found under one market and the GroupKey can be used to separate the 18 outcomes back into the original 3 groups
Currently, Betting Market Types Matchup Prop (2 Golfers), SixShooter Prop (6 Golfers) and Group Prop (3-5 Golfers) will have this field set

SOCCER

Like Golf, there are a few differences in the Soccer aggregated odds API which need to be taken into consideration when you are integrating with the various endpoints. The differences mainly have to do with the spread and totals markets, owing to Soccer's low scoring nature and affinity for games which end in a tie/draw.

Totals and Spread Markets

You will find multiple totals or spreads (e.g. 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, etc.,) for a given sportsbook in a Betting Market's set of Betting Outcomes. The payouts on these records will be accordingly high or low depending on the target value.
This multiple values condition is in contrast to how the totals markets work in the others sports, where a sportsbook would only have 1 value at any given time (unless a market is specifically indicated to contain alts).
There are no consensus outcomes formed for these markets.

Common Questions

How do I see all bet types: Betting MetaData Endpoint
What bets are resulted and where do I find those: Betting MetaData Endpoint