In this section, you will find the description of the sports data structure used in our API.
The main purpose of our sports data structure is to describe sports events such as fixtures, matches, races, and leagues standings in the same format across all sports. The data structure is designed to be easily integrated into the customer's system, it's very flexible and will easily support any future updates. The following documents describes describe all important concepts of our sports data structure. The hierarchy of the objects are is presented below:
- Sport Sport *
- Competition *
- Season *
- Stage
- Group
- Round
- Event *
- Round
- Event details *
- Participants *
- Results *
- Statistics *
- Lineups
- Incidents
- Event *
- Stage
- Season *
- Competition *
* For these objects betting offers including odds can be added to allow for bets to be made. In our structure this is know as the "Betting offer" and is described in more detail below These objects always exist in the data tree. Others are optional and depend on sport or competition.
Below you'll find a detailed explanation of some terms:
Competition (League)
A competition is a form of the tournament where teams or individual athletes compete against each other in a specific sport. It can be a national league for soccer or a basketball World Cup tournament. Each competition belongs to a sport. The list of available sports is presented in the Sports section. A competition could be part of a tour e.g. The men's Wimbledon competition is part of the ATP Tour, the Women's Wimbledon competition is part of the WTA Tour, the cycling race "Giro Italia" is related to the UCI Tour. The used tours' list can be found in the API resource: tours.index. Each competition has its own unique identificator ID and the structure of the competition object is the same across all sports. Detailed information about competitions can be found in the API resource: competitions.index
Some examples of competitions:
Premiership
Bundesliga
Wimbledon
World Cup
Season (League season)
A season is the period of time/year that a competition is played in, this means that one competition can be related to multiple seasons. Each season will have its own unique identificator ID and belong to a competition. The structure of the season object is the same across all sports. Detailed information about the season structure can be found in the API resource: seasons.index
...
Premiership 2015/16
Premiership 2014/15
Wimbledon 2014
World Cup 2010
World Cup 2014
Stage (Season stage)
An event could optionally belong to a stage. A stage is a part of a season e.g. for the Euro Championship in 2008 there were 2 stages: the Group stage and the Playoff stage. For NBA 2014/15 we also have 2 stages: Regular season and Playoffs. Stages belong to seasons. The used stages list can be found in the API resource: stages.index
Some examples of stages:
...
An event could optionally belong to a group. For example, during the soccer World Cup, events can be played in Group A, Group B, Group C, etc. The used groups list can be found in the API resource: groups.index
Event (Game or Match)
An event is a the main object in our sports data structure. It describes a soccer match, a volleyball match, a formula 1 race or a cycling event as well. All events have a unique identificatorID. Each event always belongs to a season. An event could be optionally related with to a stage and/or group. Each event has its own unique identificator ID and the structure of the event object is the same across all sports. An event could optionally belong to a Round e.g: Round 1, Quarterfinal, etc. The rounds list can be found in the API resource: rounds.index
One of the most important attributes for of an event is the status, which inform informs about the progress of an event e.g: 1st half, 2nd half, Not started, Finished, etc. Please note that not all match statuses are used by all sports. For each sport, the list of event statuses can be different. The used statuses are available in the Statuses section. Detailed information about event attributes can be found in the resource: events.index
Every event object contains some additional information called event details. For each sport, the list of event details can be different.
The complete list of possible event details are is available in the Event details section.
Some examples of events details:
First half start date
Second half start date
Number of possible sets
Period length
For each event, we add Participants. For team sports like football, volleyball, and ice hockey we add 2 participants to an event e.g. Real Madrid and Barcelona. The number of participants related to an event could be higher for some sports e.g: formula 1, cycling, ski jumping. A Ski Jumping event contains 50 participants (each jumper is a participant for the event). We differentiate between the three types of participants (teams, individuals and doubles (used for tennis)).The participants participant's list can be found in the API resource: participants.index. For each participant related to the event we will deliver Results and Statistics updated in real-time and explained further below.
...
| Tour | Competition | Season | Stage | Group | Round | Event | Event details | Participants |
|---|---|---|---|---|---|---|---|---|
| ATP Tour | Wimbledon | Wimbledon 2015 | Main tournament | Quarterfinal | Federer - Nadal | Surface: grass Number of sets: 5 |
| |
| ATP Tour | Wimbledon | Wimbledon 2015 | Qualification | 1st round | Coria - Delbonis | Surface: grass Number of sets: 5 |
| |
| World Cup | World Cup 2010 | Group Stage | Group A | Italy - Germany | Weather condition: sunny Pitch condition: good |
| ||
| World Cup | World Cup 2010 | Playoff | Brazil - France | Weather condition: sunny Pitch condition: good |
| |||
| UCI Tour | Giro d'Italia | Giro d'Italia 2015 | Lens - Paris (stage 1) | Length: 250 km |
| |||
| Premiership | Premiership 2015/16 | 25 round | Manchester United - Chelsea | Weather condition: sunny Pitch condition: good |
|
Event details
Every sports event object contains some additional information called event details. For each sport the list of event details is different.
Some examples of events details:
- Weather condition
- Pitch condition
- Period length
- Number of periods
The complete list of event details for each sport is listed in sports.show methods i.e. https://api.statscore.com/v2/sports/5
Results
For each event, we deliver the results, which are updated in real-time. For each sport, the list of results can be different. The complete list of possible results for each sport are available in the Results section
...
Result
Regular time
First half
Second quarter
Third period
The complete list of results for each sport is listed in sports.show methods i.e https://api.statscore.com/v2/sports/5
Statistics
For each event, we deliver statistics updated in real-time. For each sport, the list of statistics can be different. The complete list of possible statistics for each sport are available in the Statistics section
...
Result
First period
Corners
Throw-ins
Dangerous attacks
The complete list of statistics for each sport is listed in sports.show methods i.e https://api.statscore.com/v2/sports/5
Lineups
For some events, we deliver the lineup for each participant. This object includes the players starting and the names of all substitute players available for the event.
Incidents (Event/Game actions)
Everything that happens in an event is an incident. Incidents are sent out when the events are running. For each sport, the list of incidents can be different. The complete list of possible incidents are is available in the Incidents section.
Some examples of incidents:
Goal scored
Throw in
2pt shot scored
3pt shot missed
First half started
The complete list of incidents for each sport is listed in sports.show methods i.e https://api.statscore.com/v2/sports/5
Standings types
For each sport we provide standings. Standings can be related with to a sport, a season, a competition, a stage, or the event. The complete list of possible standings for each sport are available in the Standings types section
...
League standings
Halftime standings
World Cup 2015/16 standings
FIFA club standings
Heat standings (for speedway event)
Betting offer
...
We differentiate between two types of betting offers: live and prematch. It's described by the attribute is_live_offer. For prematch odds the is_live_offer attribute has a "no" value, for live odds the value of this attribute is "yes". We start to offer live odds a few minutes before events start. The data structure of the betting object is the same for live and prematch odds.
The hierarchy of the betting offer objects are presented below:
...
Some examples of betting offers:
...
- Under 212.5
- Over 212.5
...
- Real Madrid
- X
- Barcelona
...
- Wayne Rooney
- Diego Costa
- Daniel Sturridge
- Oliver Giroud
- Sergio Aguero
More information concerning betting offers and their structure is available at: betting-offers.index
Markets and default outcomes
Markets are related with betting offer. Each market has it's own unique identificator, name, static name and market type. Additionally for each market we defined default outcomes. Default outcomes are always assigned to a market and used when the same outcomes appears for that market every time e.g. "Odd/even" market is always decided between default "Odd" and "Even" and a "1x2" market always has three possible outcomes: "Home", "Draw", "Away". The Subtype of the market defines number of possible outcomes for a particular market (2-way, 3-way-, n-way). Some markets are offered in a prematch odds feed, some could be offered in a live odds feed, some markets are offered in both types of odds. For some markets the scope is assigned to help you find markets related to a requested scope.
Some markets and their default outcomes name includes replacers. Replacers are a pattern to generate final market or outcomes name for specific betting offer, e.g. for market name "Who will win #nextPoint# point" we use replacer #nextPoint# and that generates final market name: "Who will win 3. point". The similar situation occurs when default outcomes name for a market include replacer e.g. "Under #totalPoints#" -> "Under 195.5", etc.
Some examples of markets:
...
- Home
- Draw
- Away
...
- Under #totalPoints#
- Over #totalPoints#
...
- #participant1# #pointsHandicap#
- #participant2# #pointsHandicapRev#
...
Detailed information about markets and their defualt outcomes can be found in the API resource: markets.index.
Replacers
Replacers are used to generate the dynamic information like event parts, number of points, participant names etc. During the process of creation betting offers replacers are used in the markets name and outcomes name to generate final name. If market or outcome uses a replacer, it's final name is generated for a specific betting offer, e.g. for market name "Who will win #nextPoint#. point" we use replacer instead of #nextPoint# and that's what generates market "Who will win 3. point").
Some examples of replacers:
...
- 194.5
- 44.5
...
- 2.5
- 3.5
- 1
...
- 1
- 2
- 5
...
- 4.5
- -2.5
- 3.5
...
- -4.5
- 2.5
- -3.5
...
- Roger Federer, Novak Djokovic
- Manchester United, Liverpool FC
- Poland, Germany, Norway, Russia....
...
The list of all replacers can be found in the API resource: replacers.index
Scopes and market types
Scopes and markets types could be used to filter our betting offer lists e.g. you can retrieve all betting offers related with Full time scope or all betting offers having Asian handicap market type. Market type is a category of a market e.g. "Both teams to score" market belongs to "Goals" market type category and "1x2" market belongs to "Main" category. Scope represents a name of event's part. Every scope can be used in many sports.
Some examples of markets types:
...
Some examples of scopes:
...
You can retrieve list of all possible market types list using API resource: markets-types.index
You can retrieve list of all possible scopes list using API resource: scopes.indexThe complete list of standing types for each sport is listed in sports.show methods i.e https://api.statscore.com/v2/sports/5