This section defines some terminologies and explain their meaning and the context you might find them in.
League
The word league historically is only applicable for Soccer. However in our platform, its meaning is extended to represents a collection of sport competitions. Some example of leagues are:
- Soccer:
English Premier League
,Laliga
,World Cup
, orClub Friendly
(a collection of international friendly soccer match), etc… - Tennis: Grandslams such as
Wimbledon
,Roland Garros
,Australia Open
or ATP leagues such asMiami Open
, etc… - Basketball:
NBA
,FIBA Africa Clubs Champions Cup
,Morroco Nationale 1
, etc…
Match
A match is a sport competition between two or more sides and occurs at a specific time. Normally, a match is organized within a particular league, but when there are several matches is organized without an official league, sportbooks might group them say under a made up league such as Club Friendly
or International Friendly
. It is notable that in multi-sided sports such as horse racing or car racing, there might be more than two parties taking part in the competition.
Some good examples of a match are:
- Soccer: A soccer match between
United State Women Soccer Team
vsAustralia Women Soccer Team
inWomen World Cup League
orManchester United
vsManchester City
underEnglish Premier League
. - Tennis: A tennis match between
Roger Federer
vsNovak Djokovic
- Basketball: A basketball match between
Utah Jazz
vsPortland Trail Blazers
underNBA
Event
When betting during a single match, sportbooks often allow betting on different kinds of scores. For each kind of score, we define an Event for it specified by the Event Type. To give you more concrete example, take a SOCCER match between Manchester United
vs Manchester City
, we can have following event types:
- Main - where the number of goals is used to determine the bet outcome.
- Corner - where the number of corners of each team is used as score to determine the bet outcome.
- Home Team Corner - where the number of corner of the HOME team, in this case,
Manchester United
, is used as score to determine the bet outcome. - Away Team Total - where the number of goals for the AWAY team only, in this case,
Manchester City
, is used to determine the bet outcome. - etc…
Or for a TENNIS match,
- Set Number of set won for each side
- Game Number of game won for each side
- etc…
Live State
Live state conveys the current situation of the event. For each kind of sports, the live state is different. For example,
- In soccer: a live state of an event contains the current score of the event, the number of red card for each team or the duration of the match…
- In tennis: a live state of an event contains the score for each set, the current set, or number of foul each player has, etc…
For different kind of event in the same sport, the live state score might have different meaning. For example, given a soccer match Manchester United
vs Manchester City
, the Total Corner
event’s Live State Scores are the number of corners each team has been awarded, whereas the Main
event’s Live State Scores are the number of goals each team has made.
Users should also note the inconsistency of live state among different sportbooks. First, our data feed provides live states for all sportbooks. Across different sportbooks the types of live state data available are not the same. For example, IBC provides the most comprehensive live state data for a Tennis
which includes scores for all sets, tiebreaks, and even game score or advantage statuses, but other sportbooks, might only provide the current set scores.
Second, the same kind of data existing in multiple sportbook might not change consistently with each other. For example, for the same soccer match, the duration (current time of the match) in IBC and SBO might be different due to update delays of individual sportbooks.
With those note in mind, choosing which sportbook’s live state to use is a matter of users’ choices.
Record
A record is equivalent to a particular selection on a sportbook. It contains the information to help you identify whether it is the kind of bet you want to bet on.
Field | Description | Types | Values |
---|---|---|---|
oddType |
Odd types define whether this odd is offerred as an in running odd (i.e. when match is running), or within one day of match running or very early before the match running | Enumeration | LIVE TODAY EARLY |
oddFormat |
How the odd is displayed | Enumeration | HK, MALAY, INDO, EU, AMERICAN |
timeType |
Time types define the period of time within which players’ scores / points / goals etc… will be used to determine the bet outcomes. The time types are different in different sports. | Enumeration | Soccer: FT, HT , Tennis: FT, S1, S2, S3 ... , Basketball: FT, HT, Q1, Q2, Q3, Q4 |
rates |
Rates are the actual odd values provided by the sport book | Float | Examples: 0.95 , 0.8 , -1.2 , etc… |
id |
ID of the odd | Long | |
matchId |
ID of the match that offers this odd | String | |
eventId |
ID of the event that offers this odd | Integer | |
source |
ID of the sportbook that offers this odd | String | SBO , IBC , etc… |
Fields for sports with two sides
While our system will support multi-sides sports in the future, such as horse racing, formula 1, etc… we currently focus more on 2 sides sports, such as Soccer, Tennis, Basketball, etc… As such, we list here also some record fields that are only specific to 2 sides sports.
Field | Description | Types | Values |
---|---|---|---|
pivotType |
Pivot types define how score will be used in calculation of bet result. For example, TOTAL defines that the score of the event will be summed together and compared to the pivot value to determine the out come of the bet. |
Enumeration | HDP , TOTAL , ONE_TWO |
pivotValue |
Pivot values are the values at which the outcome of a bet is determined. For records of ONE_TWO pivot type, no pivot value is defined |
Number | 0, 0.25, 0.5, 0.75, 1, 1.25, etc... |
pivotBias |
Pivot bias specifies which team is is the favorite team (this is specific to 2 side sport only) | Enumeration | HOST , GUEST , NEUTRAL |
Target type when betting with two sides sports
When placing a bet on a particular record, you will want to specify which side of the match or of the pivot you want to bet on. For example, in a Handicap Bet, you might want to specify the team you want to bet on. In a Total bet, you might want to specify if you are betting on the OVER side of the Pivot or the UNDER side of the pivot, etc… The values of Target Type
are used for this purpose. We have following target types:
Target Type | Use for Pivot Type | Description |
---|---|---|
OVER |
TOTAL |
You want to bet that the total score of an event is greater than a specific pivot value |
UNDER |
TOTAL |
You want to bet that the total score of an event is smaller than a specific pivot value |
GIVE |
HDP |
You want to bet that the favorite team will win with difference in score (not counting the current score at betting moment) more than a specific pivot value |
TAKE |
HDP |
You want to bet that the underdog team will not lose with difference in score (not counting the current score at betting moment) more than a specific pivot value |
HOME |
HDP |
Depending on the pivot bias value, the home team is giving or taking handicap. If pivot bias is HOST , the home (host) team is the favorite team and HOME target means the same as GIVE target type. Conversely, if pivot bias is GUEST , HOME target means the same as TAKE target type |
AWAY |
HDP |
Depending on the pivot bias value, the away team is taking or giving handicap. If pivot bias is HOST , the home (host) team is the favorite team and AWAY target means the same as TAKE target type. Conversely, if pivot bias is GUEST , AWAY target means the same as GIVE target type |
ONE |
ONE_TWO |
You want to bet that the home team will win the event |
TWO |
ONE_TWO |
You want to bet that the away team will win the event |
DRAW |
ONE_TWO |
You want to bet that the home and away team will have equal score for the event |
Snapshots and deltas
A snapshot is a collection of matches each will contains multiple events which in turn, each contain multiple records. The following diagram shows how this is organized.
We have two types of snapshots, full snapshot and delta commands (which contains partial data).
Full snapshot is the snapshot that contains all data that you can consume. The fullsnapshot is often sent to you when you first connect to our feed or when you retrieve data from our JAVA subscriber using the view’s snapshot method. The full snapshot contains all available matches, events, records and their relevant properties. To construct a full snapshot at a time T
you take a previous full snapshot and plus it with all the subsequent deltas until T
.
We use delta commands to help reduce the amount of bandwidth usage. A delta only contains the changes occur at a certain point in time. A change can add or remove or update certain piece of data. You can think of a delta command as an instruction on modifying the fullsnapshot. Hence we have following type of commands for data manipulation:
Command Type | Expected behavior |
---|---|
Insert Match |
New matches are added into the full snapshot |
Delete Match |
Matches are deleted from the full snapshot |
Update Match |
The matches contained in the command are updated with new information. In general, matches are not updated so you shouldn’t see or have to handle this command. |
Insert Event |
New events are added into corresponding matches. One match might have multiple events added in one command. |
Delete Event |
Events are deleted from the corresponding matches. |
Update Event |
The events contained in the command are updated with new information. In our current implementation, update event is mostly used to set new live states for the events. This often occurs when for example, the duration changed in a soccer match, or when scores of the players, teams, etc.. changed in soccer, tennis, basketball or other sports. |
Insert Record |
New records are added into containing events. One event might have multiple records added in one command. |
Delete Record |
Records are removed from containing events. This often happens when sportbook no longer offers a bet market and the record is deleted permanently. It can also occur when for example, goal scored or red cards awarded, then the record is deleted temporarily |
Update Record |
This command is used to update the rates, i.e. the price of the record. Multiple records can be updated using one command. |
Getting data
We support two ways of getting data, the first one is a Java native library for Java applications. Our Java library gives you an API to poll the full snapshot at regular interval or to receive notification a changes in the data stream. Each poll will give you a full snapshot, where as the notifications are the delta commands which let you know how to transform the current snapshot. The following diagram sum up the common Java use case:
If you are not working with Java, you can run our wrapping server (a Java program) which will consume the feed for you and push the data to subscribers through JSON-formatted streams.
For Java developer, please refer to Java getting started
For Non-Java developer, please refer to Non-Java getting started