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:

Line Moment

Odds update regularly due to changes in player availability, market liquidity etc. We track each change as it occurs with a timestamp, which can be viewed in the relevant Line Changes endpoint.

Both Pre Match and In Play odds line movement is accessible via dedicated line movement endpoints. To track line movement for Prop markets please use the Betting Market endpoints as outlined below.

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

Edge Cases and Unusual Events

In some cases odds will not behave in an expected way. While these are highly unusual, they are common enough that we document them here, along with our process for handling these occasional hiccups.

Odds Removed By Sportsbook Operator

There is a field called UnlistedTime on the BettingOutcome table. This denotes the time at which we stop seeing that outcome in the sportsbook feeds, meaning when it is no longer available to bet on.

If an odd was published by a sportsbook then very quickly removed, we still ingest and publish it. This means that in the rare cases of an inaccurate or inappropriate odd being available for a few seconds, we will retain it but Unlist it as soon as the sportsbook does.

Odds Removed By Sportsbook Operator Then Put Back Online

A specific price for a market may be Unlisted, but then re-listed by a sportsbook. In this case, we do not restore the old odds record, but rather create a new one entirely. For example, if a market for a spread changes from -1.5 and a -2.5 and then back to -1.5, the following occurs: the -1.5 is created, then Unlisted. The -2.5 is created, then Unlisted. And then a new -1.5 is created.

This is so we can track the times of when the odds were changed.

You can deduce if a line is suspended if there is a gap in time between “Unlisted” and “Created”. That would indicate a suspension as we saw one set of odds disappear without a new set replacing it.

Created - Indicated the first timestamp of when we saw this particular line combination

Updated - Indicates the last timestamp of when we saw this line combination

Unlisted - Indicated the first refresh we no longer saw this line combination

Here is an example:

Let’s assume that for one specific Betting Line combination Item A is the first pull, Item B comes after A, and Item C comes after B

Created Updated Unlisted

A: 8:55:26 8:58:21 8:58:31

B: 8:58:31 8:59:17 8:59:27

C: 9:02:41 9:02:51 null

For this example let’s say we pull on a 10 second interval.

Created shows the first pull we had for each example of this Line Combination
Updated shows the last time a pull had these lines
Unlisted shows the first pull those lines were gone

C is the latest and STILL ACTIVE item for this line combination (unlisted is null) and was last pulled at 9:02:51

A Unlisted -> B Created had no gap and was the exact same time stamp

B was created when A stopped showing (unlisted)

B Updated -> C Created has a gap from 8:59:17 to 9:02:41 (A 3 second gap to indicate the line was suspended in that gap).

If a line combination goes Unlisted but then never comes back, there will be no suspension and the unlisting would be permanent.

Invalid Or Otherwise Unusable Odds

The Aggregated Odds service involves a complex matching operation to ensure that markets are correctly grouped and categorized. On rare occasions a market may be mismatched, creating an invalid result. WHen these markets are created in error, as soon as we detect them, they are removed from the feed entirely. This is the only scenario in which odds are hard-deleted from the output.

Odds Resulting

When working with our Aggregated Odds Resulting feeds clients should consider waiting about 15 - 20 minutes following the end of a game to allow for our closing procedures to conclude. Resulting endpoints do not continually run and are considered complete when all outcomes of the game are initially delivered. Stat corrections will not be processed via our resulting feeds and should be tracked via the Team and Player Statistics feeds.

It is important to note that not all betting markets are available via the Resulting endpoints at SportsDataIO. To better understand which betting markets are available in that feed, please contact Support@sportsdata.io.

Sports Betting Jurisdictions

New Jersey

New Jersey state law prohibits in-state gambling on college sports when a New Jersey school is involved, or the game takes place in New Jersey, even if it is between two out-of-state colleges.

Example: A bettor in New Jersey wants to gamble on the Rutgers (based in NJ) basketball game at Duke (based in NC.) He is not allowed to do so in New Jersey because Rutgers are an NJ-based school. This prohibition remains in place even though the game is in North Carolina. The bettor would have to travel out of state to place his wager.

Example: A bettor in New Jersey wants to gamble on the Army-Navy football game, which is being played at Meadowlands in New Jersey. The Navy school is from Virginia and the Army school is from New York. The bettor is not allowed to place the wager in New Jersey because the game takes place there, even though the schools are out-of-state. She must travel out of state to place her wager.

Odds Availability

For our purposes, this means our college football and college basketball odds may be unavailable because of the way the sportsbooks package their odds. Some sportsbooks aggregate their odds nationwide, meaning access to those NJ-restricted markets is unavailable across the board. Others allow state-by-state access, meaning that those outside NJ will still be able to see the odds.

Sportsbooks Not Available

For games ineligible for New Jersey wagering, expect the following sportsbooks not to appear in our SportsDataIO aggregated odds feeds:

PointsBet
DraftKings
Caesars
BetMGM

Sportsbooks Available

For games ineligible for New Jersey wagering, expect the following sportsbooks to appear in our SportsDataIO aggregated odds feeds:

FanDuel
Parx*
Rivers (Pennsylvania)*
Sports Illustrated*
SugarHouse (Pennsylvania)*
Tipico*

*Pre-game lines and in-game lines only, excluding props, futures etc.

Betting Data Integration Guide