This article is also available at sportsdata.io.
Explanation about Betting Event architecture and the various data objects related such as Betting Markets, Types, Period and Outcomes.
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:
- NFL Data Dictionary
- NBA Data Dictionary
- MLB Data Dictionary
- NHL Data Dictionary
- College Basketball Data Dictionary
- College Football Data Dictionary
Please see these notes, which detail the differences that exist in the Golf aggregated odds APIs.
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:
- NFL Aggregated Odds Types
- NBA Aggregated Odds Types
- MLB Aggregated Odds Types
- NHL Aggregated Odds Types
- CBB Aggregated Odds Types
- CFB Aggregated Odds Types
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.
- NFL - 96 to 72 hours
- NBA - 72 to 24 hours
- MLB - 48 to 24 hours
- NHL - 48 to 24 hours
- CBB - 24 hours or less
- CFB - 48 to 24 hours
BETTING EVENTS, BETTING MARKETS AND BETTING OUTCOMES
- 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
- 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"
- 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
- Betting Outcome Type
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:
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:
- NCAA Football
- NCAA Men's Basketball
- Soccer (all leagues)
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.
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
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.
- How do I see all bet types: Betting MetaData Endpoint
- What bets are resulted and where do I find those: Betting MetaData Endpoint
Related Help Articles
integration, odds, props, guide