1 of 73

Table Tennis

Getting Started

Get started with building your application using our Table Tennis API, that provides fast and reliable static and live data for tournaments, matches and competitions.

Getting Started with IMG Arena's Developer Platform for Table Tennis

IMG Arena's FastPath data feeds enable you to harness the power of our historical data and live events within your own applications. The provision of low latency, official data has been a key driver behind the growth of online sports betting. The platform provides tools, resources, data and API products for you to integrate.

How the platform is organized

The IMG Arena's developer platform is organized into four different products, based on use case, versioning, and access model.

We have put together a different page for each product to help you get started, which you can access below:

Product

Details

Table Tennis Schedule API

The Table Tennis Schedule API is a set of programmatic endpoints that can be used to learn about upcoming or historical events, competitions or tournaments.

This API allows you to find and retrieve a variety of different resources including the following:

Live Events
Tournaments
Competitions
Draws
Results

Table Tennis Stream API

The Table Tennis Streaming API allows you to programmatically integrate with the FastPath live data platform which provides low latency match status updates during live events including the following:

Players Confirmation
Match Start
Points Started
Points Scored
Undos
Score Corrections
Sanctions
Penalty Points
Swap Servings
Swap Sides
Timeouts
Injuries
Walkovers
Disqualifications
Retiring
Match Finish

Troubleshooting and support

Debugging an error? Have a question? Head over to our support section to find troubleshooting tips, contact details, live API status monitor, and other helpful information.

Fundamentals

Getting Access

How to get access to the IMG Arena Table Tennis API

To make any request to the IMG Arena API, you must first apply for an account and our Support and Integrations team will send you an OAuth Bearer 2.0 token. This token represents your application and enables you to authenticate requests.

Since these tokens do not expire unless regenerated, we suggest creating environment variables or using a secure password manager once you've received your credentials.

Please note: If you misplace or forget the tokens, you will need to regenerate them, which creates new credentials and invalidates the old ones. This means that you will have to update any integrations that you may have set up with your prior credentials.

Once you have access, you’re ready to get started using the IMG Arena Table Tennis API! We have quick start guides for many of our endpoints, useful tools and libraries and sample code that describe how to build solutions around different use cases.

Polling limits

IMG Arena monitor the incoming traffic from our customers and strive to ensure that traffic is controlled, in-keeping with our guidelines and not unnecessarily excessive. We would suggest a polling rate of 5 requests per second, whilst we strive towards implementing rate limiting.

Websockets

A single websocket endpoint exists for each match. It is a match details feed and contains an action based play by play representation of a volleyball match.

Endpoint URL

wss://dde-streams.imgarena.com/tabletennis/{id}/matchdetails

Process for connecting to the web socket endpoints

Connect to SSL websocket address
Send JSON packet containing API token
Receive response indicating that connection is authorised (or a response indicating why the connection cannot be made)
Receive data packets

Once you have the API token, any further data that you send over the connection will be ignored.

Security protocol for WebSockets: Please note that we currently we do not support SSL. We only support the use of TLS Version 1.2+.

Testing

Learn about the different methods to test your integration before going live.

This page includes test event IDs and other information to make sure your integration works as planned. Use it to trigger different flows in your integration and ensure they are handled accordingly.

Table Tennis API

When using the Table Tennis API in your application, ensure that:

All required header paramters are set correctly
You have a valid OAuth Bearer 2.0 token for authentication
Use the correct URL to get connected to the API

Basic Match IDs

Genuine match ID information cannot be used in test mode. Instead, use any of the following test match ID numbers to make a successful request.

Match ID

Details

999991

Test Match ID

Example of how to connect to a Websocket

Use the following command to get more details about a match associated with the id of 999991.

WebSocket: wss://dde-streams.imgarena.com/tabletennis/999991/matchdetails

Then right after getting connected, a valid authentication token should be sent immediately.

{
  "authToken": "<token>"
}

Example of how to connect to the REST API

Method: GET

URL: https://dde-test-api.imgarena.com/tabletennis/tournaments/

Headers: [Accept] application/vnd.imgarena.dde.api+json;version=1

World Table Tennis (WTT)

Technical Documentation provided by WTT

Title

Date

Link

WTT Series Handbook 2021 Final (Updated 17 May)

May 17, 2021

ITTF Table Tennis World Ranking FAQ

Mar 30, 2021

Major Events

Tournament

Event

World Table Tennis Championships

Men's Singles
Women's Singles
Men's Doubles
Mixed Doubles

World Team Table Tennis Championships

Men's Team
Women's Team

Schedule API

You can use the Table Tennis REST API to create calls to get the data you need to integrate with IMG Arena.

This describes the resources that make up the Table Tennis REST API. If you have any problems or requests, please contact our Support and Integrations team.

Static Endpoints

Live Events

This endpoint lists the currently live booked events for which you are licenced. This allows you to determine which events have live streams available.

Live Events

GET https://dde-api.imggaming.com/tabletennis/tournaments/liveevents

We recommend that you request this REST endpoint every 10 seconds so that you have the most up-to-date information on the events that are currently live on the DDE. This endpoint currently takes no request parameters.

Headers

Name

Type

Description

[
    {
        "eventId": 85413,
        "eventState": "InProgress",
        "startTime": {
            "status": "StartsAt",
            "time": "18:40"
        },
        "teamA": {
            "status": "KnownTableTennisTeam",
            "team": {
                "entryType": "Standard",
                "player1": {
                    "externalId": "104257",
                    "firstName": "Youngsik",
                    "id": 115,
                    "lastName": "JEOUNG"
                },
                "seed": 12
            }
        },
        "teamB": {
            "status": "KnownTableTennisTeam",
            "team": {
                "entryType": "Standard",
                "player1": {
                    "externalId": "112409",
                    "firstName": "Jonathan",
                    "id": 116,
                    "lastName": "GROTH"
                },
                "seed": 29
            }
        },
        "tournamentExternalId": "5365",
        "tournamentId": 33,
        "tournamentName": "WTT China Champions 2021 - IMGSIM 2"
    },
    {
        "eventId": 4648,
        "eventState": "InProgress",
        "startTime": {
            "status": "StartsAt",
            "time": "19:05"
        },
        "teamA": {
            "status": "KnownTableTennisTeam",
            "team": {
                "entryType": "Qualifier",
                "player1": {
                    "externalId": "120284",
                    "firstName": "Tibor",
                    "id": 6357,
                    "lastName": "SPANIK"
                },
                "seed": 34
            }
        },
        "teamB": {
            "status": "KnownTableTennisTeam",
            "team": {
                "entryType": "Qualifier",
                "player1": {
                    "externalId": "120765",
                    "firstName": "Eric",
                    "id": 6360,
                    "lastName": "THILLEN"
                },
                "seed": 70
            }
        },
        "tournamentExternalId": "2480",
        "tournamentId": 18,
        "tournamentName": "2021 ITTF Czech International Open"
    }
]

The value of HTTP header 'Accept' was malformed:
Accept must match .*application/vnd.imggaming.dde.api\+json;\s?version=(\d).*, image/* or text/csv

The supplied authentication is invalid

Response Model

An array of live-event matches

Live Event Object

Field Name

Type

Description

liveEvents

object

LiveEvents object

Field Name

Type

Description

tournamentName

string

Name of the tournament

tournamentId

int

Tournament Identifier

externalTournamentId

string

External Tournament Identifier

eventId

string

Unique identifier for this event

startTime

object

StartTime object indicating when the match was scheduled to start

teamA

object

A team status object describing the first team taking part

teamB

object

A team status object describing the second team taking part

eventState

string

NotStarted, InProgress, Finished, Suspended

StartTime object

Field Name

Type

Description

time

Timestamp relating to the status

Team Status object

Both of these objects contain the same information, but about the opposing team.

Field Name

Type

Description

status

string

UnknownTableTennisTeam, KnownTableTennisTeam, Bye

team

object

Team object containing the player information. Object will be empty if the status is Unknown or Bye

Team object

In singles, there is a team of 1 player1, in doubles we have 2 players, player1 and player2

Field

Type

Description

player1

object

Contains player information (mandatory for doubles and singles)

player2

object

Only exists for doubles

entryType

string

Standard, Qualifier

seed

integer

The seed that teams are in a tournament

Player object

These objects contain the same information, per player

Fields

Type

Description

string

Players individual identifier

firstName

string

First name

lastName

string

Last name

birthDate

string

The ISO 8601 representation of the player's date of birth (i.e. YYYY-MM-DD)

country

string

Player's country code

Tournaments

List of Tournaments

GET https://dde-api.imggaming.com/tabletennis/tournaments/

This endpoint returns an object containing tournaments.

Path Parameters

Name

Type

Description

Headers

Name

Type

Description

[
    {
        "city": "Olomouc",
        "competitions": [
            {
                "competitionId": 41,
                "drawSize": 32,
                "externalId": "2480-TTEMSINGLES",
                "organisation": "ITTF",
                "participantType": "MS",
                "qualifyingDrawSize": 4
            },
            {
                "competitionId": 42,
                "drawSize": 32,
                "externalId": "2480-TTEWSINGLES",
                "organisation": "ITTF",
                "participantType": "LS",
                "qualifyingDrawSize": 4
            }
        ],
        "countryCode": "SLO",
        "endDate": "2021-11-14",
        "eventsSummary": {},
        "identifier": 29,
        "location": "Sports Hall Tri Lilije",
        "numberOfMatches": 0,
        "startDate": "2021-11-08",
        "status": "Confirmed",
        "tournamentName": "WTT Contender Novo Mesto 2021",
        "utcOffset": 0,
        "year": 2021
    }
]

The value of HTTP header 'Accept' was malformed:
Accept must match .*application/vnd.imggaming.dde.api\+json;\s?version=(\d).*, image/* or text/csv

The supplied authentication is invalid

Response Model

Tournament Object

Field Name

Type

Description

sport

string

The sport of the tournament

tournamentName

string

The name of the tournament

city

string

The city where the tournament is being held

status

string

The status of the tournament - Cancelled, Confirmed or Unconfirmed. Note that occasionally scheduled tournaments will not take place (e.g. a sponsor pulls out) in which case the status will be set to Cancelled

location

string

The country or state (US only) and country where the tournament is being held. See countryCode for a fixed format location field

countryCode

string

ISO-3166-1 alpha-3 country code of the country where the tournament is taking place. If the country is currently unknown, the code “ZZZ” will be returned.

startDate

date

The date the tournament starts

endDate

date

The date the tournament starts

year

int

The year of the tournament

identifier

int

Identifier for the tournament

numberOfMatches

int

The number of matches to be played in this tournament. Note that for Tennis and Badminton this number is initially an estimate and will become more accurate as the order of play is released

utcOffset

double

The number of hours difference between the tournament location’s timezone and UTC. This accounts for daylght savings.

eventsSummary

object

The number of matches to be played on each day, if known. This data is only available once the order of play for the tournament is released. See object definition below

competitions

array [object]

The competitions which are played as part of the tournament. See object definition below

EventsSummary Object

Field Name

Type

Description

eventsSummary

object

Object containing the number of events on the specified date. There are codes for the types of events: MS - Mens Singles, LS - Ladies Singles, MD - Mens Doubles, LD - Ladies Doubles, XD - Mixed Doubles. The above codes can be prefixed with ‘Q’ to indicate they are part of qualifying for the competition

Competition Object

Field Name

Type

Description

organisation

string

Name of the organisation running the competition (ITTF or WTT)

externalId

string

External identifier for the competition.

competitionId

int

Identifier for the competition

participantType

string

The competition type - possible values are: MS - Mens Singles, LS - Ladies Singles, MD - Mens Doubles, LD - Ladies Doubles, XD - Mixed Doubles

drawSize

int

Draw size for the main competition

qualifyingDrawSize

int

Draw size for the qualifying competition

Specific Tournament

This endpoint returns details for a specific tournament if the id is valid and you are licenced for it

This endpoint should be requested if you want to understand details on a specific tournament. It will display the same types of information as the https://dde-api.imggaming.com/tabletennis/tournaments/ endpoint.

We recommend you request this end point on an ad hoc basis whenever you want this information on a specific tournament.

Example requests of this end point:

https://dde-api.imggaming.com/tabletennis/tournaments/1036

Request Parameters

This endpoint currently takes no request parameters

Response Model

Tournament Object

Field Name

Type

Description

tournamentName

string

The name of the tournament

city

string

The city where the tournament is being held

status

string

location

string

The country or state (US only) and country where the tournament is being held. See countryCode for a fixed format location field

countryCode

string

ISO-3166-1 alpha-3 country code of the country where the tournament is taking place. If the country is currently unknown, the code “ZZZ” will be returned.

startDate

date

The date the tournament starts

endDate

date

The date the tournament starts

year

int

The year of the tournament

identifier

int

Identifier for the tournament

numberOfMatches

int

The number of matches to be played in this tournament. Note that for Tennis and Badminton this number is initially an estimate and will become more accurate as the order of play is released

utcOffset

double

The number of hours difference between the tournament location’s timezone and UTC. This accounts for daylght savings.

eventsSummary

object

The number of matches to be played on each day, if known. This data is only available once the order of play for the tournament is released. See object definition below

competitions

array [object]

The competitions which are played as part of the tournament. See object definition below

EventsSummary Object

Field Name

Type

Description

eventsSummary

object

Competition Object

Field Name

Type

Description

organisation

string

Name of the organisation running the competition (ITTF or WTT)

externalId

string

External identifier for the competition.

competitionId

int

Identifier for the competition

participantType

string

The competition type - possible values are: MS - Mens Singles, LS - Ladies Singles, MD - Mens Doubles, LD - Ladies Doubles, XD - Mixed Doubles

drawSize

int

Draw size for the main competition

qualifyingDrawSize

int

Draw size for the qualifying competition

Sample Output

[
  {
    "city": "ST. PETERSBURG",
    "location": "RUSSIA",
    "endDate": "2017-02-05",
    "identifier": 846,
    "year": 2017,
    "numberOfMatches": 70,
    "countryCode": "RUS",
    "status": "Confirmed", 
    "tournamentName": "St. Petersburg Ladies Trophy - St. Petersburg, Russia",
    "eventsSummary": {
      "2017-01-31": {
        "LD": 3,
        "LS": 8
      },
      "2017-02-01": {
        "LS": 5,
        "LD": 5
      },
      "2017-01-30": {
        "LD": 1,
        "QLS": 4,
        "LS": 3
      },
      "2017-01-29": {
        "QLS": 8
      },
      "2017-02-03": {
        "LD": 1,
        "LS": 4
      },
      "2017-02-02": {
        "LD": 3,
        "LS": 4
      },
      "2017-01-28": {
        "QLS": 16
      },
      "2017-02-04": {
        "LD": 1,
        "LS": 2
      },
      "2017-02-05": {
        "LD": 1,
        "LS": 1
      }
    },
    "utcOffset": 4,
    "startDate": "2017-01-28",
    "competitions": [
      {
        "organisation": "WTT",
        "externalId": "1086",
        "participantType": "MS",
        "drawSize": 32,
        "qualifyingDrawSize": 32,
        "competitionId": 1
      }
    ]
  },
  {

Tournament Events

This endpoint lists the booked events for a tournament for which you are licenced. Note that the list of events is incomplete and will only show previous events and events for today and tomorrow. As a tournament progresses, matches will be added to the list.

This endpoint will include the order of play (OOP) updates. These include updates to events such as:

A change of table
A change of tablesequence
A change of scheduled start time

We recommend that you request the https://dde-api.imggaming.com/tabletennis/tournaments/{id}/events REST endpoint every minute so that you have the most up-to-date information on the events from live/upcoming tournaments.

Request Parameters

This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.

Response Model

Event Object

Field Name

Type

Description

eventId

string

Unique identifier for this event

date

Date the match was played or is scheduled to be played

matchType

string

Code indicating the type of match: MS - Mens Singles, LS - Ladies Singles, MD - Mens Doubles, LD - Ladies Doubles, XD - Mixed Doubles. The above codes can be prefixed with ‘Q’ to indicate they are part of qualifying for the competition

status

string

The current status of the match, one of: NotStarted, InProgress, Suspended, Finished

tableNumber

string

The number table the match is being played on

teamA

object

Team Status object for the first team in the match

teamB

object

Team Status object for the second team in the match

startTime

object

startTime object indicating when the match is scheduled to start

competitonId

integer

Identifier for the competition

round

string

The round this event is being played in. In case of a qualifier event the round number is prepended with a ‘Q’, like “Q3”. Otherwise it’s simply a number, e.g. “3”. The rounds work backwards, with 1 being the final, 2 being the semi-finals, 3 the quarters etc

Team Status Object

Field Name

Type

Description

status

string

Indicates if the player detail is known for this team. Values are KnownTableTennisTeam, UnknownTableTennisTeam or Bye. For UnknownTableTennisTeam or Bye, no other fields will be present

team

object

A table tennis Team Object

Team Object

Field Name

Type

Description

Player1

object

Player object containing details for the first player in the team

Player2

object

Player object containing details for the second player in the team. Only present if a doubles team

seed

int

This team’s seeding for the competition

entryType

string

This team’s entry type for the competition. Possible values are: Qualifier or Standard

Start Time Object

Field Name

Type

Description

time

timestamp

Contains either the start time for the match (generally if it’s the first match of the day on a court) or the earliest time it could start (e.g. if there is a rain delay and they know play will not start until midday) or an estimate of the start time based on the start time of the previous match

status

string

Indicates the type of information held for the start time.

StartsAt: The time in which the match is expected to start.

NotBefore: The time in which the match will not start before.

EstimatedStart: The time in which the match is estimated to start.

FollowsPrevious: The match will follow the previous match on the same table, therefore the time attributed with a 'Follows Previous' state is a rough estimate of the start time of that match.

NoInformation: No information available.

Sample Output

https://dde-api.imggaming.com/tabletennis/tournaments/847/events

[
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 1,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "12:30"
      },
      "status": "InProgress",
      "tableNumber": "Table 2",
      "round": "3",
      "teamA": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "CN",
               "firstName": "Zhendong",
               "id": 1,
               "lastName": "FAN"
            },
            "seed": 1
         }
      },
      "teamB": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "BR",
               "firstName": "Daniel",
               "id": 2,
               "lastName": "Black"
            },
            "seed": 2
         }
      }
   },
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 2,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "15:30"
      },
      "status": "Finished",
      "round": "4",
      "tableNumber": "Table 3",
      "teamA": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "FR",
               "firstName": "Orson",
               "id": 3,
               "lastName": "Phelps"
            },
            "seed": 3
         }
      },
      "teamB": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "PK",
               "firstName": "Oliver",
               "id": 4,
               "lastName": "Neal"
            },
            "seed": 4
         }
      }
   },
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 3,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "18:30"
      },
      "status": "NotStarted",
      "round": "5",
      "tableNumber": "Table 4",
      "teamA": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "PL",
               "firstName": "Eaton",
               "id": 5,
               "lastName": "Banks"
            },
            "seed": 5
         }
      },
      "teamB": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "QA",
               "firstName": "Noah",
               "id": 6,
               "lastName": "Campbell"
            },
            "seed": 6
         }
      }
   },
   {
      "competitionId": 2,
      "date": "2021-01-05",
      "eventId": 4,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "12:30"
      },
      "status": "NotStarted",
      "round": "6",
      "tableNumber": "Table 5",
      "teamA": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "SG",
               "firstName": "Leo",
               "id": 7,
               "lastName": "Bishop"
            },
            "seed": 7
         }
      },
      "teamB": {
         "status": "KnownTableTennisTeam",
         "team": {
            "entryType": "Standard",
            "player1": {
               "country": "DE",
               "firstName": "James",
               "id": 8,
               "lastName": "Bolton"
            },
            "seed": 8
         }
      }
   }
]

Tournament Draws

This endpoint lists the draws for a tournament. This includes the placeholders for matches in each round of the competition.

A typical table tennis draw is an expected set of matchups within a tennis tournament which is a knockout competition. Every match a player wins, they are entered into the next round of the draw

A table tennis draw on the DDE is first of all defined by the draw type, with each competition in a table tennis tournament having its own draw.

For example, the majority of table tennis tournaments require one or more qualifying rounds, which typically take place over the weekend before the tournament week starting. On the DDE, a qualifying round can be identified by each match's specific event ID. Event IDs are explained in detail on this page.

We recommend that you request the https://dde-api.imggaming.com/tabletennis/tournaments/{id}/draws REST endpoint every minute so that you have the most up-to-date information on the draws from live/upcoming tournaments.

Request Parameters

This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.

Response Model

Draw Object

Filed Name

Type

Description

competitionId

string

Unique identifier for this competition

participantType

string

Identifies the competition type e.g MD - Mens Doubles, LS - Ladies singles. There will be a draw object for each singles competition in the tournament and each doubles competition.

drawSize

int

Number of positions in the draw

entrySize

int

Number of teams in the draw (if not equal to drawSize then some teams will be given byes)

matches

array[object]

Array of Match objects describing the matches that are to be played

Match Object

Field Name

Type

Description

eventId

string

Unique identifier for this match within the competition - to match this with the eventID returned in the /[id]/events end point you just need to concatenate it with the competitionID

round

int

(Knockout tournament only) Which round of the draw this match is in. The rounds work backwards, with 1 being the final, 2 being the semi finals, 3 the quarters etc

teamA

object

A team status object describing the first team taking part (if known)

teamB

object

A team status object describing the second team taking part (if known)

estimatedDate

date

Indicates the date when the match is likely to be played

estimatedTime

timestamp

Please be advised that this is merely a placeholder until the official Order of Play has been released and will be defaulted to 10am local time

Team Status Object

Field Name

Type

Description

status

string

Indicates if the player detail is known for this team. Values are KnownTableTennisTeam, UnknownTableTennisTeam or Bye. For UnknownTableTennisTeam or Bye, no other fields will be present

team

object

A table tennis Team Object

Team Object

Field Name

Type

Description

Player1

object

Player object containing details for the first player in the team

Player2

object

Player object containing details for the second player in the team. Only present if a doubles team

seed

int

This team’s seeding for the competition

entryType

string

This team’s entry type for the competition. Possible values are: Qualifier or Standard

Sample Output

{
   "MS": {
      "competitionId": 1,
      "participantType": "MS",
      "drawSize": 3,
      "entrySize": 4,
      "matches": [
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "12:30",
            "eventId": 1,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "CN",
                     "firstName": "Zhendong",
                     "id": "1",
                     "lastName": "FAN"
                  },
                  "seed": 1
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "BR",
                     "firstName": "Daniel",
                     "id": "2",
                     "lastName": "Black"
                  },
                  "seed": 2
               }
            }
         },
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "15:30",
            "eventId": 2,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "FR",
                     "firstName": "Orson",
                     "id": "3",
                     "lastName": "Phelps"
                  },
                  "seed": 3
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "PK",
                     "firstName": "Oliver",
                     "id": "4",
                     "lastName": "Neal"
                  },
                  "seed": 4
               }
            }
         },
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "18:30",
            "eventId": 3,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "PL",
                     "firstName": "Eaton",
                     "id": "5",
                     "lastName": "Banks"
                  },
                  "seed": 5
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "QA",
                     "firstName": "Noah",
                     "id": "6",
                     "lastName": "Campbell"
                  },
                  "seed": 6
               }
            }
         }
      ]
   }
}

Tournament Results

This endpoint lists the results from a specific tournament, as a list of final match scores.

This endpoint lists information on results for a specific tournament, namely:

The match winner
The score
The time/date of match completion

As soon as a match is finished in the tournament, it will appear in this endpoint https://dde-api.imggaming.com/tabletennis/tournaments/{id}/results.

Request Parameters

This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here

Response Model

Event Result Object

Field Name

Type

Description

teamA

object

Team Status object containing details for the first team

teamB

object

Team Status object containing details for the second team

winner

string

The team ID of the winner - TeamA or TeamB

matchScore

object

The final match score object

matchExternalId

string

The external match ID for the event

matchId

int

IMG match ID

eventId

string

The event ID of the match

Team Status Object

Field Name

Type

Description

status

string

Indicates if the player detail is known for this team. Values are KnownTableTennisTeam, UnknownTableTennisTeam or Bye. For UnknownTableTennisTeam or Bye, no other fields will be present

team

object

A table tennis team object

Team Object

Field Name

Type

Description

player1

object

Player object containing details for the first player in the team

player2

object

Player object containing details for the second player in the team. Only present if a doubles team

seed

int

This team's seeding for the competition

entryType

string

This team’s entry type for the competition. Possible values are: Qualifier or Standard

Player Object

Field Name

Type

Description

string

Unique identifier for this player

firstName

string

First name of the player

lastName

string

Last name of the player

country

string

IOC (Olympic) country code for the player

Match Score Object

Field Name

Type

Description

gameScores

array [object]

The scores in the completed match games

gamesA

int

Number of games won by TeamA

gamesB

int

Number of games won by TeamB

Game Scores Object

Field Name

Type

Description

pointsA

int

Number of points won by TeamA

pointsB

int

Number of points won by TeamB

Sample Output

[
  {
    "eventId": 2,
    "matchScore": {
      "gamesA": 3,
      "gamesB": 0,
      "gameScores": [
        {
          "gamesA": 11,
          "gamesB": 4
        },
        {
          "gamesA": 11,
          "gamesB": 5
        },
        {
          "gamesA": 11,
          "gamesB": 8
        }
      ]
    },
    "matchExternalId": "m2",
    "matchId": 2,
    "teamA": {
      "status": "KnownTableTennisTeam",
      "team": {
        "entryType": "Standard",
        "player1": {
          "country": "FR",
          "firstName": "Orson",
          "id": 3,
          "lastName": "Phelps"
        },
        "seed": 3
      }
    },
    "teamB": {
      "status": "KnownTableTennisTeam",
      "team": {
        "entryType": "Standard",
        "player1": {
          "country": "PK",
          "firstName": "Oliver",
          "id": 4,
          "lastName": "Neal"
        },
        "seed": 4
      }
    },
    "winner": "TeamA"
  }
]

Competitions

Competition Events

This end point will show the same information as the /tournaments/{id}/events end point, but for a competition.

It is important to distinguish between a Tournament and a Competition.

Competitions are sub sets of tournaments. The tournament is the over-arching event, and the competitions happen within these tournaments.

Within each tournament there are multiple competitions, e.g. Men's Singles, Men's Doubles, Women's Doubles, e.t.c.. These competitions are knockout competitions that have a single winner.

Each of these Competitions has their own ID - although in every case the Men's Singles and Doubles (and Women's Singles and Doubles) will have the same competition ID.

We recommend that you request the https://dde-api.imggaming.com/tabletennis/competitions/{id}/events REST end point every minute so that you have the most up-to-date information on the events from live/upcoming competitions.

Request Parameters

This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.

Response Model

The response format is the same as the one for the /tournaments/{id}/events endpoint but provides information on specific competitions

Event Object

Field Name

Type

Description

eventId

string

Unique identifier for this event

date

Date the match was played or is scheduled to be played

matchType

string

status

string

The current status of the match, one of: NotStarted, InProgress, Suspended, Finished

tableNumber

string

The number table the match is being played on

teamA

object

Team Status object for the first team in the match

teamB

object

Team Status object for the second team in the match

startTime

object

startTime object indicating when the match is scheduled to start

competitonId

integer

Identifier for the competition

round

string

Team Status Object

Field Name

Type

Description

status

string

Indicates if the player detail is known for this team. Values are KnownTableTennisTeam, UnknownTableTennisTeam or Bye. For UnknownTableTennisTeam or Bye, no other fields will be present

team

object

A table tennis Team Object

Team Object

Field Name

Type

Description

Player1

object

Player object containing details for the first player in the team

Player2

object

Player object containing details for the second player in the team. Only present if a doubles team

seed

int

This team’s seeding for the competition

entryType

string

This team’s entry type for the competition. Possible values are: Qualifier or Standard

Start Time Object

Field Name

Type

Description

time

timestamp

status

string

Indicates the type of information held for the start time.

StartsAt: The time in which the match is expected to start.

NotBefore: The time in which the match will not start before.

EstimatedStart: The time in which the match is estimated to start.

FollowsPrevious: The match will follow the previous match on the same court, therefore the time attributed with a 'Follows Previous' state is a rough estimate of the start time of that match.

NoInformation: No information available.

Sample Output

[
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 1,
      "matchType": "MS",
      "startTime": {
         "time": "12:30"
      },
      "status": "InProgress",
      "teamA": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "CN",
	            "firstName": "Zhendong",
	            "id": 1,
	            "lastName": "FAN"
	         },
	         "seed": 1
	       }
      },
      "teamB": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "BR",
	            "firstName": "Daniel",
	            "id": 2,
	            "lastName": "Black"
	         },
	         "seed": 2
         }
      }
   },
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 2,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "15:30"
      },
      "status": "Finished",
      "teamA": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "FR",
	            "firstName": "Orson",
	            "id": 3,
	            "lastName": "Phelps"
	         },
	         "seed": 3
	       }
      },
      "teamB": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "PK",
	            "firstName": "Oliver",
	            "id": 4,
	            "lastName": "Neal"
	         },
	         "seed": 4
         }
      }
   },
   {
      "competitionId": 1,
      "date": "2021-01-05",
      "eventId": 3,
      "matchType": "MS",
      "startTime": {
         "status": "StartsAt",
         "time": "18:30"
      },
      "status": "NotStarted",
      "teamA": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "PL",
	            "firstName": "Eaton",
	            "id": 5,
	            "lastName": "Banks"
	         },
	         "seed": 5
	       }
      },
      "teamB": {
      	 "status": "KnownTableTennisTeam",
      	 "team": {
	         "entryType": "Standard",
	         "player1": {
	            "country": "QA",
	            "firstName": "Noah",
	            "id": 6,
	            "lastName": "Campbell"
	         },
	         "seed": 6
         }
      }
   }
]

Competition Draws

The response format is the same as the one of the /tournaments/{id}/draws endpoint.

A table tennis draw on the DDE is first of all defined by the draw type, with each competition in a table tennis tournament having its own draw.

We recommend that you request the https://dde-api.imggaming.com/tabletennis/competitions/{id}/draws REST endpoint every minute so that you have the most up-to-date information on the draws from live/upcoming tournaments.

Response Model

Draw Object

Filed Name

Type

Description

competitionId

string

Unique identifier for this competition

participantType

string

Identifies the competition type e.g MD - Mens Doubles, LS - Ladies singles. There will be a draw object for each singles competition in the tournament and each doubles competition.

drawSize

int

Number of positions in the draw

entrySize

int

Number of teams in the draw (if not equal to drawSize then some teams will be given byes)

matches

array[object]

Array of Match objects describing the matches that are to be played

Match Object

Field Name

Type

Description

eventId

string

Unique identifier for this match within the competition - to match this with the eventID returned in the /[id]/events end point you just need to concatenate it with the competitionID

round

int

(Knockout tournament only) Which round of the draw this match is in. The rounds work backwards, with 1 being the final, 2 being the semi finals, 3 the quarters etc

teamA

object

A team status object describing the first team taking part (if known)

teamB

object

A team status object describing the second team taking part (if known)

estimatedDate

date

Indicates the date when the match is likely to be played

estimatedTime

timestamp

Please be advised that this is merely a placeholder until the official Order of Play has been released and will be defaulted to 10am local time

Team Status Object

Field Name

Type

Description

status

string

Indicates if the player detail is known for this team. Values are KnownTableTennisTeam, UnknownTableTennisTeam or Bye. For UnknownTableTennisTeam or Bye, no other fields will be present

team

object

A table tennis Team Object

Team Object

Field Name

Type

Description

Player1

object

Player object containing details for the first player in the team

Player2

object

Player object containing details for the second player in the team. Only present if a doubles team

seed

int

This team’s seeding for the competition

entryType

string

This team’s entry type for the competition. Possible values are: Qualifier or Standard

Sample Output

{
   "MS": {
      "competitionId": 1,
      "participantType": "MS",
      "drawSize": 3,
      "entrySize": 4,
      "matches": [
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "12:30",
            "eventId": 1,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "CN",
                     "firstName": "Zhendong",
                     "id": "1",
                     "lastName": "FAN"
                  },
                  "seed": 1
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "BR",
                     "firstName": "Daniel",
                     "id": "2",
                     "lastName": "Black"
                  },
                  "seed": 2
               }
            }
         },
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "15:30",
            "eventId": 2,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "FR",
                     "firstName": "Orson",
                     "id": "3",
                     "lastName": "Phelps"
                  },
                  "seed": 3
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "PK",
                     "firstName": "Oliver",
                     "id": "4",
                     "lastName": "Neal"
                  },
                  "seed": 4
               }
            }
         },
         {
            "estimatedDate": "2021-01-05",
            "estimatedTime": "18:30",
            "eventId": 3,
            "teamA": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "PL",
                     "firstName": "Eaton",
                     "id": "5",
                     "lastName": "Banks"
                  },
                  "seed": 5
               }
            },
            "teamB": {
               "status": "KnownTableTennisTeam",
               "team": {
                  "entryType": "Standard",
                  "player1": {
                     "country": "QA",
                     "firstName": "Noah",
                     "id": "6",
                     "lastName": "Campbell"
                  },
                  "seed": 6
               }
            }
         }
      ]
   }
}

Stream API

You can use the Table Tennis REST API to create calls to get the data you need to integrate with IMG Arena.

This describes the resources that make up the Table Tennis Stream API. If you have any problems or requests, please contact our Support and Integrations team.

Websockets

Response Model

Packets

Fields

All packets have at least the following fields, and may have additional fields depending on the value of eventElementType:

Field name

JSON type

Description

number

The unique match identifier

eventElementType

string

A discriminator field that can be used to identify the type of packet. Possible values:

PointScored
PointStarted
Correction
Injury
MatchStatusUpdate
PointScored
Sanction
Undo

seqNum

number

Sequence number of the packet. The first packet will use the number zero.

timestamp

string

The ISO 8601 UTC timestamp for when the packet occurred

Sample

{
  "eventElementType": "MatchStatusUpdate",
  "id": 2345,
  "seqNum": 19,
  "timestamp": "2020-09-30T18:43:21Z",
}

Correction packets

Correction objects

Undo

Fields

In addition to the basic packet fields undo packets have the following additional fields:

Field Name

JSON type

Description

game

int

The game in which the point was scored

scores

array (scores)

An array of the game scores up until this point

matchScore

array (match score)

An array of the current match score after correction

undoneEventSeqNums

array (number)

An array of the seqNums of packets undone by this correction

{
    "eventElementType": "Undo",
    "id": 0,
    "seqNum": 27,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 4
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z",
     "undoneEventSeqNums": [
    26
    ]
}

Correction (Score Edit)

Fields

In addition to the basic packet fields undo packets have the following additional fields:

Field Name

JSON type

Description

game

int

The game in which the point was scored

scores

array (scores)

An array of the game correct scores

matchScore

array (match score)

An array of the current match score after correction

{
    "eventElementType": "Correction",
    "id": 0,
    "seqNum": 27,
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 4
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "matchScore": {
        "pointsA": 0,
        "pointsB": 1
    },
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z",
}

Scoring packets

PointStarted packets

Fields

In addition to the basic packet fields point started packets have the following additional fields:

Field name

JSON type

Description

eventElementType

string

A discriminator field that can be used to identify the type of packet.

Possible values:

SwapServe
SwapSides
Undo
Correction
Expedited
Sanction

game

number

The game in which the point was scored

number

Unique match identifier

seqNum

number

Sequence number of the packet. The first packet will use the number zero.

server

string

Name of serving player or team

nextServer

string

The team who will serve next

timestamp

The ISO 8601 UTC timestamp for when the packet occurred

Sample

{
    "eventElementType": "PointStarted",
    "game": 1,
    "id": 99991,
    "seqNum": 6,
    "server": "TeamA",
    "nextServer: "TeamA",
    "timestamp": "2021-07-13T13:42:24.867Z"
}

PointScored packets

Fields

In addition to the basic packet fields point scored packets have the following additional fields:

Field Name

JSON type

Description

server

string

The server for the point

scoredBy

sttring

The team that scored the point

game

int

The game in which the point was scored

scores

array (scores)

An array of the game scores up until this point

matchScore

array (match score)

An array of the match score up until this point

nextServer

string

The team who will serve next

{
    "eventElementType": "PointScored",
    "game": 1,
    "id": 99991,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scoredBy": "TeamB",
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 1
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "seqNum": 7,
    "server": "TeamA",
    "nextServer": "TeamA",
    "timestamp": "2021-07-13T13:42:28.808Z"
}

Sanctions packets

Sanction packets

Fields

In addition to the basic packet fields, sanction packets have the following additional fields:

Field name

JSON type

Description

team

string

The team to which the sanctions are being applied

game

int

The current game

sanctionType

string

A discriminator field that can be used to identify the type of sanction assigned to the party.

Possible values:

PlayerYellowCard
PlayerYellowRedOne
PlayerYellowRedTwo

Sample

{
    "eventElementType": "Sanction",
    "id": 0,
    "seqNum": 51,
    "sanctionType": "PlayerYellowCard",
    "team": "TeamA",
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

PenaltyPoints packets

Fields

In addition to the basic packet fields, penalty points packets have the following additional fields:

Field name

JSON type

Description

team

string

The team to which the penalty point(s) are being applied

game

int

The game in which the penalty was applied

scores

array (scores)

An array of the game scores up after the penalty

matchScore

array (match score)

An array of the match score up until this point

Sample

{
    "eventElementType": "PenaltyPoint",
    "id": 0,
    "seqNum": 26,
    "team": "TeamA",
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 5
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

Swap packets

SwapServe packets

Fields

In addition to the basic packet fields swap serve packets have the following additional fields:

Field Name

JSON type

Description

game

int

The game in which the point was scored

scores

array (scores)

An array of the game scores up until this point

matchScore

array (match score)

An array of the match score up until this point

{
    "eventElementType": "SwapServe",
    "game": 1,
    "id": 99991,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [],
    "seqNum": 2,
    "timestamp": "2021-07-13T13:41:29.944Z"
}

SwapSides packets

Fields

In addition to the basic packet fields swap sides packets have the following additional fields:

Field Name

JSON type

Description

game

int

The game in which the point was scored

scores

array (scores)

An array of the game scores up until this point

matchScore

array (match score)

An array of the match score up until this point

{
    "eventElementType": "SwapSides",
    "game": 1,
    "id": 99991,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [],
    "seqNum": 3,
    "timestamp": "2021-07-13T13:41:31.405Z"
}

MatchStatusUpdate packets

Fields

In addition to the basic packet fields match status update packets have the following additional fields:

Field name

JSON type

Description

matchStatus

object (MatchStatus)

An object describing the current status of the match

Sample

{
  "eventElementType": "MatchStatusUpdate",
  "id": 2345,
  "matchStatus": {},
  "seqNum": 19,
  "timestamp": "2020-09-30T18:43:21Z",
}

Match Status objects

Fields

This object type contains at least the following fields, and may have additional fields depending on the value of matchState.

Field name

JSON type

Description

matchState

string

A discriminator field that can be used to identify the type of match status. Possible values:

PlayersConfirmed
InProgress
Timeout

PlayersConfirmed

Status update once the players have been confirmed.

Fields

This matchSate object type has the following fields:

Field name

JSON type

Description

state

string

The current status of the game

isExpedited

Boolean

Indicates whether the game has expedited (true or false)

Sample

"matchState": {
                "state": "PlayersConfirmed",
                "isExpedited": false
              }

InProgress

Status update once the game is started.

Fields

This matchSate object type has the following fields:

Field name

JSON type

Description

state

string

The current status of the game

isExpedited

Boolean

Indicates whether the game has expedited (true or false)

Sample

"matchState": {
                "state": "InProgress",
                "isExpedited": false
              }

Timeout

Fields

This matchSate object type has the following fields:

Field name

JSON type

Description

state

string

The current status of the game

isExpedited

Boolean

Indicates whether the game has expedited (true or false)

team

string

The team that requesed the timeout

game

int

The current game

timeoutType

string

A simplified descriptor for why the timeout was called

"matchState": {
                "state": "Timeout",
                "isExpedited": false,
                "team": "TeamA",
                "game": 1,
                "timeoutType": "PlayerTimeout"
              }

MatchFinished packets

This packet indicates the reason a match was finished.

Fields

In addition to the basic packet fields match status update packets have the following additional fields:

Field name

JSON type

Description

reason

object (reason)

An object describing the reason of why the match was finished

Sample

{
    "eventElementType": "MatchFinished",
    "id": 999991,
    "seqNum": 101,
    "reason": {},
    "won": "TeamA",
    "timestamp": "2021-07-13T13:47:17.793Z"
}

MatchFinished objects

Fields

This object type contains at least the following fields, and may have additional fields depending on the value of matchFinished.

Field name

JSON type

Description

matchFinished

string

A discriminator field that can be used to identify the type of match status. Possible values:

Sample

{
  "reason": "Normally"
}

Normally

Fields

This object type has no additional fields beyond those included with all match finished objects.

Sample

{
  "reason": "Normally"
}

Injury

Fields

This object type has no additional fields beyond those included with all match finished objects.

Sample

{
  "reason": "Injury"
}

Disqualification

Fields

This object type has no additional fields beyond those included with all match finished objects.

Sample

{
  "reason": "Disqualification"
}

Walkover

Fields

This object type has no additional fields beyond those included with all .

Sample

{
  "reason": "Walkover"
}

Retired

Fields

This object type has no additional fields beyond those included with all match finished objects.

Sample

{
  "reason": "Retired"
}

Unknown Reason

Fields

This object type has no additional fields beyond those included with all match finished objects.

Sample

{
  "reason": "UnknownFinishedReason"
}

Live Data Scenarios

Overview

01. Pre-Match

This section will describe the packets that are received upon the start of the match. At the start of every table tennis match, the same packets should be received in the same order.

Overview

The following packets are expected at the beginning of every match.

Players Confirmed
In Progress

1. Players Confirmed

Event Element Type: Match Status Update

The first packet that is received is the 'Players Confirmed' packet. This indicates that players are at the table and are preparing for the match.

{
    "eventElementType": "MatchStatusUpdate",
    "id": 999991,
    "seqNum": 1,
    "matchStatus": {
        "matchState": {
            "state": "PlayersConfirmed",
            "isExpedited": false
        },
        "teamAPlayer1": "HARIMOTO Tomokazu",
        "teamBPlayer1": "OVTCHAROV Dimitrij",
        "table": "Table 1",
        "teamAPlayersDetails": {
            "player1Id": 23,
            "player1Gender": "M",
            "player1Organisation": "JPN"
        },
        "teamBPlayersDetails": {
            "player1Id": 47,
            "player1Gender": "M",
            "player1Organisation": "GER"
        }
    },
    "timestamp": "2021-07-13T13:38:22.867Z"
}

2. In Progress

Event Element Type: Match Status Update

The next packet, 'In Progress', will indicate that the match has started.

{
    "eventElementType": "MatchStatusUpdate",
    "id": 999991,
    "seqNum": 2,
    "matchStatus": {
        "matchState": {
            "state": "InProgress",
            "isExpedited": false
        },
        "teamAPlayer1": "HARIMOTO Tomokazu",
        "teamBPlayer1": "OVTCHAROV Dimitrij",
        "table": "Table 1",
        "firstServer": "TeamA",
        "teamAPlayersDetails": {
            "player1Id": 23,
            "player1Gender": "M",
            "player1Organisation": "JPN"
        },
        "teamBPlayersDetails": {
            "player1Id": 47,
            "player1Gender": "M",
            "player1Organisation": "GER"
        }
    },
    "timestamp": "2021-07-13T13:40:28.808Z"
}

02. During a Match

Scoring

Basic packets about point scoring during a game.

Overview

This section will cover the basic packets that will be a part of every game wh. A match is played the best 3 of 5 games. For each game, the first player to reach 11 points wins that game, however a game must be won by at least a two point margin. A point is scored after each ball is put into play.

Point Started
Point Scored

1. Point Started

This packet indicates that a point has now started and the ball has been served.

{
    "eventElementType": "PointStarted",
    "game": 1,
    "id": 99991,
    "seqNum": 6,
    "server": "TeamA",
    "nextServer" "TeamA",
    "timestamp": "2021-07-13T13:42:24.867Z"
}

2. Point Scored

The aim in table tennis is to strike the ball in a manner that the opponent fails to make contact with the ball, which earns the player a point. If the ball hits the net and it fails to bounce over into the opponent’s half, or hits it over the net and out of bounds without coming into contact with the table, the opponent gets a point.

In doubles, the scoring rule is a bit different. Here, the server and the partner have to alternate while attempting to push the ball on to the opponent’s side of the table. Here the service alternates as well.

The opponent can also be awarded a point if you hit the ball outside the playing surface or if the ball comes in contact with any part of your body while attempting a shot.

Once the point has completed (scored), a PointScored packet will be emitted, and the field called scoredBy , is indicating which player won the point.

This packet includes an array providing the scores for each period within the game, ordered such that the score for period one is listed first, followed by the score for period two, and so on.

Also after a game has been won, the field calle gameWon shows which team won the game.

{
    "eventElementType": "PointScored",
    "id": 99991,
    "seqNum": 1,
    "scoredBy": "TeamA",
    "scores": [
        {
            "pointsA": 11,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "server": "TeamA",
    "nextServer": "TeamA",
    "game": 1,
    "gameWon": "TeamA",
    "timestamp": "2021-10-01T00:00:00.000Z"
}

Serves

Basic packets about swapping sides and serves during a game.

Overview

This section will cover the basic packets that will be a part of every game. A match is played the best 3 of 5 games. For each game, the first player to reach 11 points wins that game, however a game must be won by at least a two point margin. A point is scored after each ball is put into play.

Change of Service (Swap Serve)
Change of Side (Swap Side)

1. Change of Service (Swap Serve)

The player to serve first is chosen at random, with the winner of the random draw able to choose to serve first or receive first.

The player who is serving changes after a certain number of points are scored. In an 11 point game, the service changes every 2 points.

Example of how it works.

Player A serves first to Player B. They each get one point, and the score is 1-1. The total score is now 2, so it is Player B's turn to serve and therefore a SwapServe packet will be emitted.
Player B gets the next 2 points, and the score is 1-3. The total score is now 4, and the serve switches back to Player A.
Player A continues serving until the total score is 6.

In an 11 point game, the game must be won by a 2-point lead. If both players score 10 points, the service switches after every point until the game is over.

The rules in doubles game are following the same logic desribed above. At each change of service, the last receiver shall become the server and the partner of the previous server shall become the receiver. For example, a correct pattern would be:

Player A has played his two serves to player X
Player X then plays his two serves to player B.
Player B will then play his two serves to Player Y
player Y will play his two serves to Player A.

Player A will then restart the sequence all over again and the sequence will repeat itself until a changeover or the end of the game.

{
    "eventElementType": "SwapServe",
    "game": 1,
    "id": 99991,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [],
    "seqNum": 2,
    "timestamp": "2021-07-13T13:41:29.944Z"
}

2. Change of Side (Swap Sides)

A changeover occurs when one team has scored 5 points. This will also change up the order of receiving.

For instance, players A & B score 5 points first, whilst A is serving to X. After changing ends, player A will serve to player Y for the remainder of the game.

{
    "eventElementType": "SwapSides",
    "game": 1,
    "id": 99991,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [],
    "seqNum": 3,
    "timestamp": "2021-07-13T13:41:31.405Z"
}

Correction

In an event of making a mistake when entering information into the match scoresheet, the problem should be fixed and correct scores should be published.

Overview

There are two ways of fixing mistakes around wrong scores, whether the latest point scored (Undo) should be fixed, or a previously assigned score (Correction) should be amended. These two messages are different, but structurally similar packets.

Undo
Correction (Score Edit)

1. Undo

The last scored point can be undone due to a point decrement or a penalty point decrement action. Semantically, an Undo packet means the official chose to revert the most recently emitted packet(s). Under the scores field a snapshot should be found of what is understood to be the latest scores of the match after taking into account the effect of the undo. Also included is a field named undoneEventSeqNums which details which packets were removed. In case of an Undo packet, it's always seqNum - 1.

{
    "eventElementType": "Undo",
    "id": 0,
    "seqNum": 27,
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 4
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z",
     "undoneEventSeqNums": [
    26
    ]
}

1. Correction (Score Edit)

A Correction packet means the official modified packets that occurred at some point in the past. Like Undo packets, under the scores field a snapshot of what is understood to be the current state of the match after taking into account the effect of the correction(s).

{
    "eventElementType": "Correction",
    "id": 0,
    "seqNum": 27,
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 4
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z",
}

Timeouts

Each player has one timeout per match lasting up to 60 seconds along with a brief towel-off breaks at every 6 points during a match.

Overview

Only normal timeouts are being supported. Towel-off breaks are currently not supported.

Timeout Started

Timeout Started

Normal Timeout Started

{
    "eventElementType": "MatchStatusUpdate",
    "id": 1,
    "seqNum": 1,
    "matchStatus": {
        "matchState": "Timeout",
        "isExpedited": false,
        "team": "TeamA",
        "game": 1,
        "timeoutType": "PlayerTimeout"
    },
    "timestamp": "1970-01-01T00:00:00.000Z"
}

Sanctions

Both players and coaches may be sanctioned during a match. A Sanction packet will be emitted in such scenarios, describing the player that was sanctioned, and which sanction(s) have been applied.

Overview

Players and coaches can be sanctioned by umpires and referees using yellow and red cards.

Note: sanctions are currently not supported about coaches.

Sanction Type

Card(s)

Description

Player

🟨

Warning

Player

🟨 🟥 (1st)

1 penalty point

Player

🟨 🟥 (2nd)

2 penalty points

Player

🟥

~~Coach~~

🟨

~~Warning~~

~~Coach~~

🟥

Penalties

Overview

For further information about the type of penalties, please see Sanctions. If a sanction involves any point decrement due to a penalty, then the action has two parts. The first part is always a Sanction packet that describes the reason of a sanction (yellow and red card for the 1st time, or for the 2nd time, etc), followed by a PenaltyPoint packet that contains the actual scores of the match, indicating a 1 point or 2 points decrements.

Player - Yellow Card 🟨
~~Coach~~ ~~- Yellow Card~~ 🟨 (Currently not supported)
Player - Yellow and Red Card (1st) 🟨 🟥
Player - Yellow and Red Card (2nd) 🟨 🟥

1. Player - Yellow Card (Warning) 🟨

Showing a yellow card by the umpire is a warning to the player. If the player repeats the action or do something else wrong they can get a red card and then lose a point (See Penalty Points). A Sanction packet, along with the sanction type will be emitted. (no penalty points).

{
    "eventElementType": "Sanction",
    "id": 0,
    "seqNum": 51,
    "sanctionType": "PlayerYellowCard",
    "team": "TeamA",
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

1. Coach - Yellow Card 🟨 (Currently not supported)

Showing a yellow card by the umpire is a warning to the coach. A Sanction packet, along with the sanction type will be emitted. (no penalty points).

{
    "eventElementType": "Sanction",
    "id": 0,
    "seqNum": 51,
    "sanctionType": "CoachYellowCard",
    "team": "TeamA",
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

1. Player - Yellow & Red Card (1st) 🟨 🟥

Showing a yellow and red card together for the 1st time means the player repeated any wrongdoing or did something else wrong and now losing a point (See Penalty Points). After the Sanction packet, a PenaltyPoint packet is emitted showing the current state of scores - 1 point decrement is expected.

{
    "eventElementType": "Sanction",
    "id": 0,
    "seqNum": 51,
    "sanctionType": "PlayerYellowRedOne",
    "team": "TeamA",
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

1. Player - Yellow & Red Card (2st) 🟨 🟥

Showing a yellow and red card together for the 2nd time means the player repeated any wrongdoing or did something else wrong and now losing a point (See Penalty Points). After the Sanction packet, a PenaltyPoint packet is emitted showing the current state of scores - 2 points decrement is expected.

{
    "eventElementType": "Sanction",
    "id": 0,
    "seqNum": 51,
    "sanctionType": "PlayerYellowRedTwo",
    "team": "TeamA",
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

1. Penalty Point(s)

Showing a yellow and red card together means the player repeated any wrongdoing or did something else wrong, and one or two points are awarded to the opponent for the offence(s). Before a PenaltyPoint packet, a Sanction is expected to be received (See Player Yellow and Red 1 Card or Player Yellow and Red 2 Card), and the current state of scores is being sent as part of the PenaltyPoint packet.

{
    "eventElementType": "PenaltyPoint",
    "id": 0,
    "seqNum": 26,
    "team": "TeamA",
    "matchScore": {
        "pointsA": 0,
        "pointsB": 0
    },
    "scores": [
        {
            "pointsA": 0,
            "pointsB": 11
        },
        {
            "pointsA": 5,
            "pointsB": 5
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        },
        {
            "pointsA": 0,
            "pointsB": 0
        }
    ],
    "game": 2,
    "timestamp": "1970-01-01T00:00:00.000Z"
}

Disqualification

The referee has the power to disqualify a player from a match, an event or a whole competition by holding up a red card. The umpire can also issue a red card to coaches.

Disqualification

The referee has the power to disqualify player(s) from a match for a seriously unfair or offensive behaviour by holding up a red card. In this case the match will end and a MatchFinished event type is submitted, indicating the reason of a player being disqualified.

{
    "timestamp": "2021-07-20T16:17:45.426Z",
    "eventElementType": "MatchFinished",
    "reason": "Disqualification",
    "seqNum": 656,
    "won": "TeamA"
}

Expediting

This regulation in table tennis, also known as the Expedite System, begins after 10 minutes of gameplay and fewer than 18 total points have been recorded.

Expedite Rule

In case the match has officially gone past 10 minutes and the Expedite Rule has been enacted, an Expedited packet will be emitted.

{
   "eventElementType":"Expedited",
   "id":999991,
   "seqNum":101,
   "game":2,
   "timestamp":"2021-07-13T13:47:17.793Z"
}

03. Post-Match

Overview

Match results will be calculated as soon as the umpire enters the final point into their tablet or in case of a serious injury, disqualification, sudden death or other reason that is causing the end of a game.

The game is confirmed as FINAL when the 'Match Finished' packet is sent.

Until the final message that confirms the end of the game allows a mistakenly entered scored to be undone.

There are various reasons - other than normal - for finishing a match.

Normal Game End
Injury
Disqualification
Walkover
Retiring
Unknown Reason

1. Normal Game End

The Match Finished packet is the final packet that is sent through for a match at the end.

{
    "eventElementType": "MatchFinished",
    "id": 999991,
    "seqNum": 101,
    "reason": "Normally",
    "won": "TeamA",
    "timestamp": "2021-07-13T13:47:17.793Z"
}

2. Injury

If a player is injured during a match, then an Match Finished packet will be emitted, indicating the reason as Injury. At present, this packet only describes which team the injured players is a member of, or in other words which team is the winner. In the future, we expect to describe the actual injured player to this packet, and we'll also track the injury status of players throughout the course of a match.

{
    "timestamp": "2021-07-20T16:17:45.426Z",
    "eventElementType": "MatchFinished",
    "reason": "Injury",
    "seqNum": 656,
    "won": "TeamA"
}

3. Disqualification

The referee has the power to disqualify player(s) from a match for a seriously unfair or offensive behaviour by holding up a red card.

See section of Disqualification under Sanctions for further info.

4. Walkover

When a player doesn't turn up to the game before it begins due to sickness or injury, their opponents are granted a walkover and given a victory. Walkovers often occur due to a player not being able to play the next game because of an accident that happened during warm-up. In this case a Match Finished packet will be emitted, indicating the reason as Walkover

{
    "timestamp": "2021-07-20T16:17:45.426Z",
    "eventElementType": "MatchFinished",.
    "reason": "Walkover",
    "seqNum": 656,
    "won": "TeamA"
}

5. Retired

When a player advances after their opponent retires during a match a Match Finished packet will be emitted, indicating the reason as Retired . Injuries are the primary reason this would happen.

{
    "timestamp": "2021-07-20T16:17:45.426Z",
    "eventElementType": "MatchFinished",
    "reason": "Retired",
    "seqNum": 656,
    "won": "TeamA"
}

6. Unknown Reason

If a match is finished due to an unknown reason a Match Finished packet will be emitted, indicating the reason as Unknown Finished Reason .

{
    "timestamp": "2021-07-20T16:17:45.426Z",
    "eventElementType": "MatchFinished",
    "reason": "UnknownFinishedReason",
    "seqNum": 656,
    "won": "TeamA"
}