Sports data structure

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 describe all important concepts of our sports data structure. The hierarchy of the objects is presented below:

• Sport *  
  
  • Competition *
    
    • Season *
      
      • Stage
        
        • Group
        •  Round
          • Event *
            
            • Event details *
            • Participants *
              • Results *
              • Statistics *
              • Lineups
            • Incidents
              
              

* 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 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 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

Some examples of seasons:

• 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:

• Group stage

• Playoff

• Qualification

• Main tournament

Group

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 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 ID. Each event always belongs to a season. An event could be optionally related to a stage and/or group. Each event has its own unique 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 of an event is the status, which 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 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 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.

Some examples of events and their relation:

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

Some examples of results:

• 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

Some examples of statistics:

• 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 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 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

Some examples of standings:

• League standings

• Halftime standings

• World Cup 2015/16 standings

• FIFA club standings

• Heat standings (for speedway event)

The complete list of standing types for each sport is listed in sports.show methods i.e https://api.statscore.com/v2/sports/5