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.
...
- Weather condition
- Pitch condition
- Period length
- Numer Number of periods
The complete list of event details for each sport are is listed in sports.show method fmethods 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
...
The complete list of results for each sport are is listed in sports.show method fshow 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 are is listed in sports.show method fshow 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:
...
The complete list of incidents for each sport are is listed in sports.show method fshow methods i.e. https://api.statscore.com/v2/sports/5
...
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
...
The complete list of standing types for each sport are is listed in sports.show method fshow methods i.e. https://api.statscore.com/v2/sports/5
...