Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
An event ID is a 3-part unique event identifier. The DDE uses them to identify each single event that happens on the platform.
Example ID: 2024-0083-MD013
2024 This is the year the event takes place
0083 This is the Competition ID
MD013 This is the match ID. Match IDs are structured as follows:
MD - The draw that the match is from 013 - The place of the match within the draw
See below for a full breakdown of these for the main draws within tennis tournaments
Acronym
Type
MS
Men's Singles
QS
Qualifying Men's Singles
MD
Men's Doubles
QD
Qualifying Men's Doubles
LS
Ladies' Singles
RS
Qualifying Ladies' Singles
LD
Ladies' Doubles
RD
Qualifying Ladies' Doubles
XD
Mixed Doubles
MX
Mixed Doubles - United Cup only
Tournament Round
DDE Round
Event ID's
Final
Round 1
001
Semi Final
Round 2
002 & 003
Quarter Final
Round 3
004 to 007
Round of 16
Round 4
008 to 015
Round of 32
Round 5
016 to 031
Round of 64
Round 6
032 to 063
Round of 128
Round 7
064 to 128
N.B, the above are valid for the main draw of knockout tournaments. Qualifying draws will not end in a single match (001) - there will be 2 or more qualifiers progressing through to the main draw.
Also, round robin tournaments will of course have a slightly different structure to the above, depending on how big the groups are. However, the Final will always be 001 and the Semi Finals 002 and 003 within a Round Robin tournament.
Endpoint: /tournaments/{id}/draws
The draws endpoint returns draw information that is published pre-tournament. This draw information is then updated on an event by event basis as the tournament progresses. Each time a player wins a match, they are entered into the next round of the draw and the draw is updated accordingly. Draws are also updated when players drop out due to injury and are replaced by lucky losers, or when there is a walkover.
Large numbers of the events in the draw will be placeholders (i.e. with no player information) until the tournament is close to conclusion.
Associated information returned from the endpoint regarding scheduling should be taken as a very rough estimate until the corresponding event has been published on the events endpoint.
Endpoint: tournaments/{id}/events
The events endpoint is a direct reflection of the Order of Play (OOP). The OOP is exactly as it says on the tin - the order of play for each court. Each court will have a number of matches lined up, and each match will have a court sequence number, so you know what order matches will be played in on each court.
In addition to this, each match will have a scheduled start time and state. Either 'not before' (the match will not start before this time) or 'follows previous' (the match will follow the previous match on the court). The time attributed with a 'follows previous' state is a rough estimate of the start time of that match.
The tournament director is responsible for publishing the OOP for the following day's play at the end of the current day. This is normally not published until the final match of the current day has ended, unless they need to make exceptions in cases like walkovers or delays. Expect new OOP information on this endpoint around 30 mins after the last match of the day.
The OOP can be used as the definitive point of confirmation around when specific events are going to take place and can be reconciled against the draw accordingly.
The various standards of scoring across all Tennis included in our portfolio.
Throughout the United Cup and Grand Slams covered by IMG, there are a number of tennis scoring types. These are returned as part of our "Match Status Update" packets within the live data stream, e.g below is a 5 set match, with Standard scoring type:
The following are the possible Tennis Scoring types
Standard
scoringType
Description
Standard
A normal match, with advantage scoring, and a tiebreak at 6/6 in a set. The "tieBreakType" field will return info on whether the last set is a tiebreak or an advantage set
ModernSetWithNoAdv
All sets excluding the final set are as 'Standard' above, with no advantage scoring. Instead of playing a final set (at 2-2 in a 5 set match and 1-1 in a 3 set match) a 'Supertiebreak' is played. This is like a regular tiebreak but is first to 10 points rather than 7
ATPShortSetNoAdv
Sets are played first to 4 games, with a regular tiebreak at 3-3. No advantage scoring. No lets (serve is either in or a fault). Only 1 medical timeout per player
LastSetTiebreak12
A normal match, with advantage scoring, and a tiebreak at 6/6 in sets 1 and 2 (of a 3 set match) or sets 1 to 4 (in a 5 set match). The last set is also a tiebreak set, but the tiebreak will be at 12/12, rather than 6/6. A player can still win this last set by being two games clear after winning their 6th game (e.g. 6/4, 7/5, or 8/6 e.t.c)
The Association of Tennis Professionals (ATP); the following scoring standard will cover United Cup
Match Type
Scoring standard
scoringType
Men's Singles (MS)
Best of 3, 3 tiebreak sets
Standard
Men's Doubles (MX)
Best of 3, 2 tiebreak sets, 3rd supertiebreak (No-ad scoring)
ModernSetWithNoAdv
Men's Qualifying Singles (QMS)
Best of 3, 3 tiebreak sets
Standard
Men's Qualifying Doubles (QMD)
Best of 3, 2 tiebreak sets, 3rd supertiebreak (No-ad scoring)
ModernSetWithNoAdv
Men's Singles (At ATP NextGenFinals Tournament only)
Best of 5, 5 tiebreak sets (No-ad scoring). Sets are first to 4 games, tiebreak at 3-3. No lets
ATPShortSetNoAdv
The below are the competition types at the French Open Grand Slam tournament. Please note that the standard scoring for French Open 2022 are standard tiebreaks apart from the last set which is a 10-point tiebreak set.
Match Type
Scoring Standard
scoringType
Men's Singles (MS)
Best of 5, 4 tiebreak sets, 5th advantage set. 5th tiebreak set at a 10 -point tiebreak.
Standard
Women's Singles (LS)
Best of 3, 2 tiebreak sets, 3rd advantage set. 3rd tiebreak set a 10- point tiebreak.
Standard
Men's Doubles (MD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Women's Doubles (LD)
Best of 3, 3 tiebreak sets. 3rd tiebreak set a 10- point tiebreak.
Standard
Mixed Doubles (XD)
Best of 3, 2 tiebreak sets, 3rd supertiebreak (No-ad scoring). 10 point match tiebreak in the final set.
ModernSetWithNoAdv
Men's Singles Qualifying (QMS)
Best of 3, 3 tiebreak sets. 3rd tiebreak set a 10- point tiebreak.
Standard
Women's Singles Qualifying (QLS)
Best of 3, 3 tiebreak sets. 3rd tiebreak set a 10- point tiebreak.
Standard
The below competition types at the Wimbledon tournament. Please note that the standard scoring for Wimbledon 2022 are standard tiebreaks apart from the last set which is a 10 - point tie break. (We have kept the scoring type as the previous year as this year's 10 point tiebreak is a trial, if taken on in a permanent basis we will update the scoring type for next year.)
Match Type
Scoring Standard
scoringType
Men's Singles (MS)
Best of 5, 4 regular tiebreak sets, 5th tiebreak set at a 10 -point tiebreak.
Standard
Women's Singles (LS)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set a 10- point tiebreak.
Standard
Men's Doubles (MD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Women's Doubles (LD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Mixed Doubles (XD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Men's Singles Qualifying (QMS)
First round matches, best of 3 sets. 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Final round matches, best of 5 sets. 4 regular tiebreak sets, 5th tiebreak set at a 10 point tiebreak.
Standard
Women's Singles Qualifying (QLS)
Best of 3, 2 tiebreaks sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
The below competition types at the US Open tournament
Match Type
Scoring Standard
scoringType
Men's Singles (MS)
Best of 5, 4 regular tiebreak sets, 5th tiebreak set at a 10 -point tiebreak.
Standard
Women's Singles (LS)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Men's Doubles (MD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Women's Doubles (LD)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Mixed Doubles (XD)
Best of 3, 2 regular tiebreak sets, 10 point match tiebreak in the final set.
ModernSetWithNoAdv
Men's Singles Qualifying (QMS)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Women's Singles Qualifying (QLS)
Best of 3, 2 regular tiebreak sets, 3rd tiebreak set at a 10 point tiebreak.
Standard
Tiebreak set - The set is played until a player reaches 6 or 7 regular games, with a 2-game margin. A tiebreak is played when the score is 6-6. Each point in a tiebreak counts for 1 point. To win a tiebreak, a player needs to win at least 7 points, with a 2-point margin -- 7-5, 8-6, etc.
Advantage set - no tiebreaks are played, and the set continues until one of the players has a 2-game margin (8-6, 9-7, etc). Today, only the last and deciding set of the match (the 5th or the 3rd) can be played as an advantage set, while all the other sets are tiebreak sets
Supertiebreak - A set that consists of a tiebreak, in which a player has to win at least 10 points with a 2-point advantage
10-point tiebreak set - The procedure of the 10-point match tiebreak is the same as in the 7-point set tiebreak, but the winning player or team must reach 10 points by a margin of at least 2 points to win the final set 1-0 and therefore the match
No-ad scoring - A scoring method in which at 40-40 the next point is the deciding - whoever wins it, wins the game. This scoring is employed in ATP doubles matches, and in Grand Slam Mixed Doubles -- except for Wimbledon
Ad scoring - after getting to 40-40, the player/team must win two points in a row to win the game -- the first of those is the "advantage" point
The United Cup is a global tennis competition where teams from 18 different countries, made up of both men and women, compete on hard courts. The first tournament took place from December 2022 to January 2023 and happened in three Australian cities for 11 days right before the Australian Open. It's unique because, for the first time in mixed-gender team events.
Looking ahead to the 2025 United Cup, it's the third time this event is happening. It's an outdoor tennis tournament played on hard courts and involves mixed-gender teams. The event runs from December 27, 2024, to January 5, 2025, across two locations in Perth and Sydney, Australia. In this edition of United Cup, nine teams from each city will participate, which is three more than in 2023. The teams will be drawn into six groups of three countries each. Note each team will also have a captain.
Each match in the tournament comprises 2 men's singles matches, 2 women's singles matches, and a mixed doubles match.
The matches are split into two sessions held on different days. On the first day, one men's singles match and one women's singles match are played. On the second day, another men's singles match and another women's singles match are followed by a mixed doubles match.
During the first week, each city hosts two groups of three countries, competing in a round-robin format. One group plays all its ties in the morning sessions, while the other group plays in the evening sessions.
The group winners in each city then face off in a city final for one of three semifinal spots. This city final occurs in one day, with both morning and evening sessions. Among the three losing teams, the one with the best record at that point becomes the fourth semifinalist.
A travel day is allocated before the semifinals and finals, which take place in Sydney.
Semifinal ties occur over two days, similar to the round-robin stage. The final is played in one day. If the match winner is determined after four singles matches, the mixed doubles match is not played.
A total of 18 countries qualify through the following criteria:
Six countries secure qualification based on the ATP ranking of their top-ranked singles player.
Another six countries qualify based on the WTA ranking of their leading singles player.
The remaining six countries earn qualification based on the combined ranking of their top-ranked players in both ATP and WTA.
As the host nation, Australia is assured one of the spots reserved for teams with the best combined ranking in the event it does not qualify independently.
Each team is comprised of three or four players from each tour.
For both events, In both cities, three groups, each comprising three countries, will host a round-robin format. This format involves one men's and one women's singles match, along with one mixed doubles match.
The winners of each group and the top-performing runner-up from a city will progress to the quarterfinals. A day for travel will be scheduled before the semifinals and final unfold in Sydney.
More information on the format:
2024 Edition
The 2024 United Cup was hosted in two Australian cities: Perth and Sydney.
Perth's RAC Arena: The event commenced on Friday, 29 December 2023.
Sydney's Ken Rosewall Arena: Group stage matches began on Saturday, 30 December 2023.
Sydney Finals:
Semifinals: Held on 6 January 2024.
Finals: Held on 7 January 2024.
2025 Edition
The third edition of the United Cup is scheduled to take place from Friday, 27 December 2024, to Sunday, 5 January 2025, again in Perth and Sydney.
Perth's RAC Arena: Opening matches begin on 27 December 2024.
Sydney's Ken Rosewall Arena: Group stage matches start on 28 December 2024.
Quarterfinals:
Perth: 1 January 2025
Sydney: 2 and 3 January 2025
Sydney Finals:
Semifinals: Held on 4 January 2025.
Finals: Held on 5 January 2025.
A total of 18 countries qualify through the following criteria:
Six countries secure qualification based on the ATP ranking of their top-ranked singles player.
Another six countries qualify based on the WTA ranking of their leading singles player.
The remaining six countries earn qualification based on the combined ranking of their top-ranked players in both ATP and WTA.
As the host nation, Australia is assured one of the spots reserved for teams with the best combined ranking in the event it does not qualify independently.
Each team is comprised of three or four players from each tour.
2024 Edition
Eighteen countries earned qualification based on the ATP and WTA rankings of their No. 1 singles players and their combined team rankings. As the host nation, Australia was guaranteed a spot if it did not qualify directly.
2025 Edition
The qualification process for 2025 introduces new adjustments:
Since 16 October 2024 the Initial Qualification:
Ten countries will qualify through the top five highest-ranked male and female players entered, as determined by ATP and WTA rankings.
Eight additional teams will qualify based on the best combined rankings of the highest-ranked male and female players from the same country.
Second Qualification Date:
Any player in the ATP or WTA Top 10 (up to one from each tour) who has entered the tournament and has an eligible team, but whose team has not qualified, will be granted entry.
In such cases, their team will replace the lowest-ranked team based on combined rankings.
Australia retains guaranteed entry as the host nation.
The MatchID for Mixed Doubles will be designated as "MX."
Throughout the tournament, the Order of Play, along with an updated draw file, will be dispatched once nominations and match confirmations are finalised on-site. This information will be provided a day before the scheduled matches.
It's important to note that Mixed Doubles pairings may undergo last-minute updates before being played, as the team captain has the flexibility to alter their selection based on their preference.
Note MatchID Acronyms:
Sample draw file:
OOP sample:
The API is versioned, and all requests should be made by supplying an Accept header with the following value:
application/vnd.imggaming.dde.api+json;version=1
Calls to the API are authenticated using the API token. All calls to the REST endpoints need to be made with the following header set:
Authorization: Bearer {auth_token}
Note the space between Bearer and the token itself. An example of the data to be set (with a truncated token) is:
Bearer eyJhbGciOiJIUzUxMiIIkpXVCJ9.eyJqdGkiOiIyNmQ2
Attempting to access a resource without the header included will result in a permission denied error. The response body will contain the details in the following format:
{ “error”: “<reason of the error>”, “status”: <HTTP status code> }
When accessing the streaming web sockets it is not possible to include a header on the initial GET request, so instead the token needs to be sent over the web socket before the stream will start. See 'Connecting to a Streams Endpoint' for examples of how to do this.
All calls to the API must be made over HTTPS. This ensures that the tokens used for authentication/authorisation cannot be intercepted and used to access content without permission. For the same reason, you must make sure that you do not expose your token externally, though this is mitigated by the use of the IP whitelist.
We do not provide a fixed set of IP addresses for our services. Therefore if you use IP-based security rules, you will need to dynamically resolve our services IPs with each request that you make.
Additionally, for DNS resolution we present a 1 hour TTL and you will also need to ensure this is being effectively respected when resolving from CNAME to host.
Examples: • Date only – 2024-06-01 • UTC Time only – 10:12:54 (also used for match time) • Offset time – 17:20-04:00 or 15:15:30+01:00 • UTC Datetime – 2024-06-01T15:15:30 Note that the date and time returned in UTC local time.
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.
To connect to the system programmatically, you will need to provide the IP address (or addresses/blocks) that you will connect from.
You will then be provided with one API token that will allow you to gain secured access to both the list of events (Schedule) and the live data (Streams) that you have licensed from IMG Gaming.
For non-streaming schedule data, all API requests should be directed to the following URL:
URL: https://dde-api.data.imgarena.com/
Requests for streamed live data should be issued to:
URL: wss://dde-streams.data.imgarena.com/
Our Schedule API provides the following end points. These end points are all related to Draw or Order of Play (OOP) information:
/players
/tournaments
/tournaments/{id}
/tournaments/{id}/draws
/tournaments/{id}/events
/competitions/{id}/events
/competitions/{id}/draws
/tournaments/{id}/results
/tournaments/liveevents
When a new event appears on the /tournaments/liveevents endpoint, you should automatically connect to the SSL websocket address for that event:
1) Call https://dde-api.data.imgarena.com/tournaments/liveevents (this should be requested every 10 seconds, so you do not miss a new event starting).
2) See a new event appear on the /tournaments/liveevents endpoint, e.g.
3) Connect to the new match on the live streams endpoint:
There are two stream endpoints that you can connect to for a live event:
Live Streams, e.g: wss://dde-streams.data.imgarena.com/tennis/events/2024-0540-MS001/stream
Live Statistics, e.g: wss://dde-streams.data.imgarena.com/tennis/events/2024-0540-MS001/statistics
Within our data is 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 (see examples below).
Example - Wimbledon:
Grand Slam Tournament IMG Covers:
The Championships 2024, Wimbledon (Tournament ID: 11956)
Competitions IMG Cover within this:
Wimbledon Men's Championships 2024 (Competition ID: 2024-0540, the same for both Singles and Doubles)
Wimbledon Women's Championships 2024 (Competition ID: 2024-0904, the same for both Singles and Doubles)
Wimbledon Mixed Doubles Championships 2024 (Competition ID: 2024-0005)
This section contains details on the following RESTful endpoints:
Establishing appropriate reconnection logic is an integral element when integrating with our APIs. Our streaming endpoint issues a heartbeat every ten seconds to validate that the connection to an event is healthy.
Disconnection from an event can happen without warning; if the connection to the WebSocket is closed or a heartbeat is not received for ten seconds, we recommend a mechanism to automatically reconnect. If a heartbeat is not received for ten seconds, an automatic attempt to reconnect to the event should be made after eleven seconds.
Possessing the correct reconnection methodology within your integration will prevent a select number of issues arising in the future. Please see - this defines what alarm packets are and why these should not be mistaken for a disconnection.
All DateTime objects are returned using the ISO 8601 combined format. For more information about ISO 8601, please read .
Acronym
Type
MS
Men's Singles
LS
Ladies' Singles
MX
Mixed Doubles
We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times:
REST Endpoint
Frequency
/tournaments/liveevents
Every 10 seconds
/tournaments/{id}/draws
Every minute
/tournaments/{id}/events
Every minute
/tournaments
Every 12 hours
/players
Every week
IMG suggests the above recommendations because of the order in which we value these updates.
Polling the /liveevents endpoint is essential when attempting to connect to an event at the earliest possible convenience. If this was polled any less then every 10 seconds, then you may not connect to a game as quickly as you may like.
Polling the /draws and /events endpoints is only needed every minute because it is not as vital to know draw or Order of Play (OOP) updates as it is to know that a match is live. These updates include draw updates like player changes or OOP updates such as court changes.
The /tournaments endpoint should be polled every 12 hours because IMG generally only receive information on new tournaments two to three times a week, for events months in advance.
Lastly, polling the /players endpoint anymore than once a week does not offer a value as IMG only receives player updates once per week. This is due to player information (e.g. ranking) only changing post-tournament and not mid-tournament.
All REST endpoints have a dedicated page and contain our recommended frequency of rest requests
An array of live event objects.
Field Name
Type
Description
tournamentName
string
Name of the tournament
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 object describing the second team taking part
This endpoint lists the currently live booked events for which you are licenced. This allows you to determine which events have live streams available.
URL: https://dde-api.data.imgarena.com/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.
You will use the response from this end point to decide which live streams that you should connect to. As soon as you see a live stream available on this end point you should commence connecting to the websocket for that individual live stream event.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
Live Event: Note: api will return a list of LiveEvent when hitting LiveEvents endpoint.
An example from the Tournaments Live Events end point in December 2024
New URL: https://dde-api.data.imgarena.com/tournaments/liveevents
This endpoint lists all tournaments for which you are licensed, and you have booked at least one event. With unlimited licences, you will see all tournaments and events as they are automatically booked for you
The /tournaments endpoint will display the following types of information on each tournament:
City (LA)
Location (California)
Country (USA)
Surface
Year
Environment (Indoors or outdoors)
Name
Number of matches
Match Schedule Plan info (expected matches each day)
Draw Sizes
Start/End Date
Competition IDs (2024-0540)
Organisation (ATP/AELTC/USTA/FFT)
We recommend that you request the https://dde-api.data.imgarena.com/tournaments REST endpoint every 12 hours so that you have the most up-to-date information on the tournaments that we offer at all times.
Example requests of this end point:
https://dde-api.data.imgarena.com/tournaments?includeUnbooked=true (includes all matches, booked and unbooked, that you may have for this tournament)
https://dde-api.data.imgarena.com/tournaments?dateFrom=2024-02-28&dateTo=2024-03-01 (All matches between 28 Feb and 1 March)
This endpoint takes the following parameters:
Parameter
Type
Purpose
includeUnbooked
boolean
When set to true we will return a list of all tournaments for which you are licensed irrespective of whether you have booked events in them. If not specified then only booked tournaments are returned
dateFrom
date
Filter the tournaments by date. Only tournaments which have events on or after the specified date will be included.
E.g. dateFrom=2024-06-01
dateTo
date
Filter the tournaments by date. Only tournaments which have events on or before the specified date will be included.
E.g. dateTo=2024-06-30
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.data.imgarena.com/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.data.imgarena.com/tournaments/11904
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
An example of a request for the tournament end point for the BNP Paribas Open, Indian Wells
https://dde-api.data.imgarena.com/tournaments/10840
Most of the tournaments within the ATP tours are Knock Out tournaments - where a player is eliminated if they lose, and progresses to the next round if they win. However, in a few tournaments each year, the tournaments take a different format: Round Robin.
Round Robin refers to a group where all players play against each other in turn.
The Round Robin tournaments that the ATP organise are normally in the following format:
Group Stage:
Group 1: 4 Teams* Group 2: 4 Teams
*Teams can consist of a single player, or two players (in a doubles match)
Each team will play each other once in their respective groups. They will be awarded points for winning matches/sets (This varies for each tournament). The players are then ranked 1-4 in their groups based on these points.
Semi-Finals & Finals:
The Semi-Finals are made up of the top 2 teams in each group. They are decided as follows:
Semi-Final 1: Winner of Group 1 vs Runner-Up in Group 2 Semi Final 2: Winner of Group 2 vs Runner-Up in Group 2
Final: Winner of Semi-Final 1 vs Winner of Semi-Final 2
N.B. There are other formats of Round Robin tournaments, e.g. where there can be 4 groups of 3 teams. In this instance the four group winners go through to the semi finals.
1 - TOURNAMENTS ENDPOINT RESPONSE- COMPETITION TYPE
Round Robin tournaments have different competitionType field. This is WorldChampionships
This field can be found within the competitions object within the response to the /tournaments and /tournaments/{id} endpoints.
2 - TOURNAMENTS ENDPOINT RESPONSE - COMPETITION OBJECT
For Round Robin tournaments, additional fields can be found within the competitions object within the response to the /tournaments and /tournaments/{id} endpoints
These are as follows:
N.B - these fields will not be returned in the response until the draws for the tournament have been released.
3 - DRAW ENDPOINTS RESPONSE- MATCH OBJECT
For Round Robin tournaments, there will be the following additional fields within the match object within the response to the /tournaments/{id}/draws and /competitions/{id}/drawsendpoint
These are as follows:
Additionally, the round Field will return null for Round Robin tournaments in the above endpoints.
Below are two (limited to 100 lines each for this page) example responses (/tournaments/{id} and /tournaments/{id}/draws from a round robin tournament (ATP United Cup 2024, Tournament ID 12469):
United Cup draws:
Field Name
Type
Description
drawPoolSize
int
The number of teams within each group in the Round Robin tournament
drawNumPools
int
The number of groups within the Round Robin tournament
Field Name
Type
Description
stageType
string
Indicates if this match in the group stage or the knockout stage. Values are group or knockout
groupId
int
If a group stage match then this shows the id of the group the match is in
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. Note that when a tournament is cancelled, the location will be set to CANCELLED as well. 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
surface
string
The surface the tournament is being played on. Can be one of Hard, Clay, Grass or Carpet
year
int
The year of the tournament
identifier
int
Identifier for the tournament
environment
string
Whether the tournament is held Indoor or Outdoor
numberOfMatches
int
The number of matches to be played in this tournament. Note that 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. Note that this offset does not account for Daylight Saving Time (DST) rules, so at the time of the tournament the actual offset may be slightly different
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. Generally there is a single tournament but some events have both ATP and WTA competitions. See object definition below
eventsResource
url
Location of details of the tournament events
bookingStatus
string
Indicates if this tournament is booked. One of: “Booked”, “Autobooked”, “NotBooked” or “PartiallyBooked”. PartiallyBooked indicates that some of the events have been booked
Field Name
Type
Description
booked
int
Optional field indicating the number of events booked from the tournament if the bookingStatus was “PartiallyBooked”
Field Name
Type
Description
{date}
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/MX - 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
Field Name
Type
Description
organisation
string
Name of the organisation running the competition (ATP, WTA, FFT, AELTC, USTA, TA or ITF)
externalId
string
Identifier for the competition. Note that the tournament year and this id uniquely identify a competition e.g. 2015-9028
competitionId
string
Identifier for the competition - this is the year and the externalId
competitionType
string
The competition type - possible values are: Challenger, 250, 500, 1000, GrandSlam, WorldChampionships, Premier, Premier5, Qualifying, Internationals, PremierMandatory, ITF
singlesDrawSize
int
Draw size for the singles competition
singlesQualifyingDrawSize
int
Draw size for the singles qualifying competition
doublesDrawSize
int
Draw size for the doubles competition
doublesQualifyingDrawSize
int
Draw size for the doubles qualifying competition
startDate
date
Start date of the competition
endDate
date
End date of the competition
licensingProperty
string
The license covering the event
drawPoolSize (Round Robin only)
int
The number of teams within each group in the **round robin tournament**
drawNumPools (Round Robin only)
int
The number of groups within the **round robin tournament**
Tournament: Note - Multiple tournaments can be returned after a call in an array.
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. Note that when a tournament is cancelled, the location will be set to CANCELLED as well. 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
surface
string
The surface the tournament is being played on. Can be one of Hard, Clay, Grass or Carpet
year
int
The year of the tournament
identifier
int
Identifier for the tournament
environment
string
Whether the tournament is held Indoor or Outdoor
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. Note that this offset does not account for Daylight Saving Time (DST) rules, so at the time of the tournament the actual offset may be slightly different
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. Generally there is a single tournament but some events have both ATP and WTA competitions. See object definition below
eventsResource
url
Location of details of the tournament events
bookingStatus
string
Indicates if this tournament is booked. One of: “Booked”, “Autobooked”, “NotBooked” or “PartiallyBooked”. PartiallyBooked indicates that some of the events have been booked
venueNames
array [object]
Venue name of where the tournament is hosted. Note if available
Field Name
Type
Description
numberOfMatchesBookedToday
int
Optional field indicating the number of events booked from the tournament if the bookingStatus was “PartiallyBooked”
Field Name
Type
Description
{date}
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/MX - 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
Field Name
Type
Description
organisation
string
Name of the organisation running the competition (ATP, FFT, AELTC, USTA)
externalId
string
Identifier for the competition. Note that the tournament year and this id uniquely identify a competition e.g. 2024-9028
competitionId
string
Identifier for the competition - this is the year and the externalId
competitionType
string
The competition type - possible values are: Challenger, 250, 500, 1000, GrandSlam, WorldChampionships, Premier, Premier5, Qualifying, Internationals, PremierMandatory, ITF
singlesDrawSize
int
Draw size for the singles competition
singlesQualifyingDrawSize
int
Draw size for the singles qualifying competition
doublesDrawSize
int
Draw size for the doubles competition
doublesQualifyingDrawSize
int
Draw size for the doubles qualifying competition
startDate
date
Start date of the competition
endDate
date
End date of the competition
licensingProperty
string
The license covering the event
drawPoolSize (Round Robin only)
int
The number of teams within each group in the **round robin tournament**
drawNumPools (Round Robin only)
int
The number of groups within the **round robin tournament**
An array of Event objects.
Field Name
Type
Description
eventId
string
Unique identifier for this event
date
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/MX - 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
courtId
string
The identifier for the court the match is on. Note that this value is assigned by the ATP’s software - it will likely not correlate with the actual court name
courtName
string
The name of the court the match is on
courtSeq
int
Defines the ordinal position of the match on this court. First match will have a value of 1, the second 2 etc.
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
startTimeText
string
Text description of the start time. Note that the start time object contains detailed information about the start and is likely to be more useful than this field
additionalText
string
Additional information about the match
bookingStatus
structure
Indicates if this event is booked. One of: “Booked”, “Autobooked” or ”NotBooked”
competitionId
string
Identifier for the competition - this is the year and the externalId
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
globalCourtId
string
Unique global court ID for the court. UTR events only
venueId
string
Unique Venue court ID for the venue. UTR events only
Field Name
Type
Description
status
string
Indicates if the player detail is known for this team. Values are KnownTennisTeam or UnknownTennisTeam. For UnknownTennisTeam, no other fields will be present
team
object
A tennis team object
Field Name
Type
Description
id
string
Unique identifier for this player as defined by the ATP/UTR
firstName
string
First name of the player
lastName
string
Last name of the player
country
string
IOC (Olympic) country code for the player
Field Name
Type
Description
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.
time
offset time
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
A map of competitionType -> Draw objects, populated with players where they are known.
Filed Name
Type
Description
competitionId
string
Unique identifier for this competition
competitionType
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. Therefore, for a tournament with both ATP & WTA events there may be 4 or 5 draws
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)
numberOfPools
int
(Round robin tournament only) The number of pools in the round robin
matches
array[object]
Array of Match objects describing the matches that are to be played
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
stageType
string
(Round robin only) Indicates if this match is in the group stage or the knockout stage. Values are Group or Knockout
groupId
int
(Round robin only) If a group stage match then this shows the id of the group the match is in
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
estimatesTime
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
Field Name
Type
Description
status
string
Indicates if the player detail is known for this team. Values are KnownTennisTeam, UnknownTennisTeam or Bye. For UnknownTennisTeam or Bye, no other fields will be present
team
object
A tennis 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: Wildcard, Qualifier, LuckyLoser, ProtectedRank, Alternate, SpecialExempt or Standard
An example JSON response of a draws endpoint for the ATP Hamburg European Open in Hamburg, Germany 2022.
Endpoint URL: https://dde-api.data.imgarena.com/tournaments/11904/draws
Tournament Draws: Note: A map of competitionType -> Draw objects, populated with players where they are known.
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 court
A change of court sequence (An event is moved from 5th to 1st on a certain court)
A change of scheduled start time
We recommend that you request the https://dde-api.data.imgarena.com/tournaments/{id}/events REST endpoint every minute so that you have the most up-to-date information on the events from live/upcoming tournaments.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
This endpoint lists the draws for a tournament. This includes the placeholders for matches in each round of the competition.
A typical 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 Tennis draw on the DDE is first of all defined by the draw type, with each competition in a tennis tournament having its own draw.
For example, the majority of 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.data.imgarena.com/tournaments/{id}/draws REST endpoint every minute so that you have the most up-to-date information on the draws from live/upcoming tournaments.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
:
Note - Multiple events can be returned after a call in an array.
Field Name
Type
Description
competitionId
string
Unique identifier for this competition
competitionType
string
Identifies the competition type e.g MD/MX - Mens Doubles, LS - Ladies singles. There will be a draw object for each singles competition in the tournament and each doubles competition. Therefore, for a tournament with both ATP & WTA events there may be 4 or 5 draws
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)
numberOfPools
int
(Round robin tournament only) The number of pools in the round robin
matches
array[object]
Array of Match objects describing the matches that are to be played
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
stageType
string
(Round robin only) Indicates if this match is in the group stage or the knockout stage. Values are Group or Knockout
groupId
int
(Round robin only) If a group stage match then this shows the id of the group the match is in
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
Field Name
Type
Description
status
string
Indicates if the player detail is known for this team. Values are KnownTennisTeam, UnknownTennisTeam or Bye. For UnknownTennisTeam or Bye, no other fields will be present
team
object
A tennis 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: Wildcard, Qualifier, LuckyLoser, ProtectedRank, Alternate, SpecialExempt or Standard
An example Competition Draw from the Roland Garros 2024.
https://dde-api.data.imgarena.com/competitions/2024-0520/draws
N.B: If a request was made mid-way through the tournament, unknowns players will be returned as draws have not been released.
An example from the tournament events endpoint JSON response from Roland Garros 2024
https://dde-api.data.imgarena.com/tournaments/11904/events
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 set scores
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.data.imgarena.com/tournaments/{id}/results.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
A map of competitionType -> Draw objects, populated with players where they are known.
The response format is the same as the one for the /tournaments/{id}/events endpoint - see here - except that the start time may not be available if we have not received that information.
Field Name
Type
Description
eventId
string
Unique identifier for this event
date
date
Date the match was played or is scheduled to be played
matchType
string
string Code indicating the type of match: MS - Mens Singles, LS - Ladies Singles, MD/MX - 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
courtId
string
The identifier for the court the match is on. Note that this value is assigned by the ATP’s software - it will likely not correlate with the actual court name
courtName
string
The name of the court the match is on
courtSeq
int
Defines the ordinal position of the match on this court. First match will have a value of 1, the second 2 etc.
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
startTimeText
string
Text description of the start time. Note that the start time object contains detailed information about the start and is likely to be more useful than this field
additionalText
string
Additional information about the match
bookingStatus
structure
Indicates if this event is booked. One of: “Booked”, “Autobooked” or ”NotBooked”
competitonId
string
Identifier for the competition - this is the year and the externalId
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
Field Name
Type
Description
status
string
Indicates if the player detail is known for this team. Values are KnownTennisTeam or UnknownTennisTeam. For UnknownTennisTeam, no other fields will be present
team
object
A tennis team object
Field Name
Type
Description
id
string
Unique identifier for this player as defined by the ATP
firstName
string
First name of the player
lastName
string
Last name of the player
country
string
IOC (Olympic) country code for the player
Field Name
Type
Description
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.
time
offset time
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
This endpoint lists the events for a competition for which you are licensed. Please note that the list of events is incomplete and will generally only show previous events and events for today and tom
This end point will show the same information as the /tournaments/{id}/events end point, but for a competition.
The difference between competitions and tournaments is explained here.
We recommend that you request the https://dde-api.data.imgarena.com/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.
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
Competition Events: Note: It is possible that we may not have been informed of the start time, in which case that information will not be available.
An example Competition Events from the Roland Garros 2024.
https://dde-api.data.imgarena.com/competitions/2024-0520/events
This endpoint lists the draws for a competition. This includes the placeholders for matches in each round of the competition.
This end point will show the same information as the /tournaments/{id}/draws end point, but for a competition.
The difference between competitions and tournaments is explained here.
We recommend that you request the https://dde-api.data.imgarena.com/competitions/{id}/draws REST end point every minute so that you have the most up-to-date information on the draws from live/upcoming competitions.
Note to pass the competitionId as the {ID} when hitting the /competition endpoint.
CompetitionId for competition type qualifying men's singles for Roland Garross 2024 M"2024-0520". i.e: https://dde-api.data.imgarena.com/competitions/2024-0520/draws
This endpoint currently takes no request parameters, we aim to add them, and once we have they will be detailed here.
An array of player details objects.
Field Name
Type
Description
playerSummary
object
Player Object containing basic information about the player
active
boolean
indicating whether the player is active or inactive
gender
string
Possibles values are “Male” and “Female”
rankDate
string
The most recent rankdate
*Please note that the optional fields are dependent on data being known and available in our database.
Field Name
Type
Description
currentSinglesRank
int
Current singles rank
currentSinglesRankTied
boolean
True if tied for current singles rank
currentDoublesRank
int
Current doubles rank
currentDoublesRankTied
boolean
True if tied for current doubles rank
currentYTDRank
int
Current YTD rank
currentYTDRankTied
boolean
True if tied for current YTD rank
singlesRollingPoints
int
Singles rolling points. Points earned by a player in the last 52 weeks
doublesRollingPoints
int
Doubles Rolling Points. Points earned by a player in the last 52 weeks
singlesRacePoints
int
Singles Race Points. Points earned by a player in the calendar year
The /players endpoint contains over 60,000 players, both active and inactive - this changes infrequently. It will generally be updated once a week when new ranking information comes in, following the end of a tournament.
We recommend that you request the https://dde-api.data.imgarena.com/players REST end point once a week, for this reason, so that you have the most up-to-date information on the players in the ATP
Due to the large response message size for requests made using the "activity=inactive" and "activity=all" parameters, the responses, although successful, will not return any information. We therefore recommend that any requests made to the /players REST endpoint are no larger than "results=10000"
This endpoint lists all the players registered with the ATP & UTR
*Please note that the optional fields are dependent on data being known and available in our database.
This endpoint takes the following parameters:
Parameter
Type
Purpose
activity
string
This is an optional field. Possible values are "active" "inactive" and "all". They are not case sensitive. active returns just active players, inactive returns only the inactive players and all, returns all. If not specified, only the active players are returned. E.g. activity=all
gender
string
This is an optional field. Possible values are "male" and "female"
results
string
This is an optional field, and should be used in conjunction with the offset parameter. Possible values are numbers: "1", "2" etc, but will only return information on the first X players in the response. E.g. "activity=active&results=3" will return information for the first three active players in the response, and nothing else
offset
string
This is an optional field, and should be used in conjunction with the results parameter. Possible values are numbers: "1", "2" etc, but will only return information on players who are after X players in the response. E.g. "activity=active&offset=3" will ignore the first 3 players in the active list, and return everything from player four onwards
showRanking
boolean
By default, if no value passed or set as true, we will return ranking for players. Passing False will not return rankings.
gender
boolean
By default, feed will return both men and women. Possible values: "men" "female"
Best practice (using the results and offset parameters):
When results and offset are used together, you can specify how many players are 'ignored' and not included in the response, as well as the number of players who are included in the response. E.g. "results=10&offset=10" will bring back the first 10 players after the first 10 are ignored (Players 11 through 20)
If you would like to obtain the full list of inactive players (over 50,000 players), you can do so in increments of 5000, increasing the 'offset' value, whilst keeping 'results' the same. Examples below:
"results=5000" - this will bring back information for the first 5000 players. "results=5000&offset=5000" - this will bring back information for players 5001 through 10000. "results=5000&offset=10000" - this will bring back information for players 10001 through 15000. "results=5000&offset=15000" - this will bring back information for players 15001 through 20000. etc.
Field Name
Type
Description
teamA
object
Team object containing details for the first team
teamB
object
Team 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
finishReason
string
The reason of winning - one of “Normal”, “Retirement”, “SuddenDeath”, “Default” or “Unknown”
matchId
string
IMG match ID
eventId
string
The event ID of the match
Field Name
Type
Description
status
string
Indicates if the player detail is known for this team. Values are KnownTennisTeam, UnknownTennisTeam or Bye. For UnknownTennisTeam or Bye, no other fields will be present
team
object
A tennis 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: Wildcard, Qualifier, LuckyLoser, ProtectedRank, Alternate, SpecialExempt or Standard
Field Name
Type
Description
id
string
Unique identifier for this player as defined by the ATP
firstName
string
First name of the player
lastName
string
Last name of the player
country
string
IOC (Olympic) country code for the player
Field Name
Type
Description
setScores
object
The scores in the completed match sets
Field Name
Type
Description
gamesA
int
Number of games won by TeamA
gamesB
int
Number of games won by TeamB
tieBreakPointsA
int
Tie-break score for the Set if it went to a tie break for TeamA
tieBreakPointsB
int
Tie-break score for the Set if it went to a tie break for TeamB
A snippet of an example of the Tournaments Results end point from Roland Garros 2024.
https://dde-api.data.imgarena.com/tournaments/11904/results
A snippet of the /players endpoint, with rankings from December 2024
https://dde-api.data.imgarena.com/players
i.e return first 100 results: https://dde-api.data.imgarena.com/players?results=100
This stream contains the events happening within the tennis match and generally corresponds to data being entered by the umpire on the court.
Please note that if the match for the requested stream has not yet started then a 204 response code will be returned and the Websocket will not be accessible. As soon as the event starts the Websocket will become available.
The first event is always a dummy placeholder event (i.e. not produced by the upstream provider) with a match status of NotStarted:
Not Started - JSON Example
This response takes the following parameters:
ParameterTypePurpose
startPosition
int
The position in the stream that you want to start from. Each packet in the stream has an integer id, where 1 is the first packet in the stream. By default, the stream will start from the beginning. This is useful if you get disconnected from a stream and need to reconnect. When reconnecting, if you specify the id of the last packet you received + 1, then you can pick up where you left off without the need to reprocess all the events already received.
New URL: wss://dde-streams.data.imgarena.com/tennis/events/{event-id}/stream
Legacy URL: wss://dde-streams.imggaming.com/tennis/events/{event-id}/stream
N.B. – Please use event ID “2022-2789-MS027” to return the sample data. The authentication token provided will be required to make a connection to this WebSocket endpoint.
Connect to SSL WebSocket address
Send JSON packet containing the API token
Format to send API token:
{"authToken": "authentication 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.
The Stream API provides a stream of live match data as JSON over a WebSocket connection. Please see the below for how to connect to the stream endpoint.
The process for connecting to the stream endpoints and receiving data is always the same:
● Connect to the SSL websocket address ● Send JSON packet containing API token
Format to send API token:
{"authToken": "authentication token"}
● Receive response indicating that the connection is authorised (or else a response indicating why the connection cannot be made) ● Receive heartbeat packets every 10 seconds to verify that the connection is live ● Receive data packets
Once you have sent the API token, any further data that you send over the connection will be ignored.
Security protocol: Please note that we currently we do not support SSL. We only support the use of TLS Version 1.2+.
The code below shows how to make the connection using Java. It uses the following dependencies but you can use any libraries you wish:
Then use the following code:
Java
In Java, to send a Web request via a SSL-based protocol (i.e. HTTPS or WSS) one has to add the signed certificate to the keystroke ‘ jssecacerts’ for the specific domain as alias. For that the utility Java program ‘ InstallCert.java’ is used:
To compile and run:
When it asks for the input, press ‘ 1 ’. After this step, the informed domain will be added as a trusted keystore, and a file called “ jssecacerts“ will be generated.
Finally,this“ jssecacerts”fileneedstobecopiedtoyour“$ JAVA_HOME/jre/lib/security” folder.
The code below shows how to make the connection using Javascript. It assumes you already have a variable named token holding your API token:
We can provide code samples in other languages on request.
A Test Server for event streams is also available for testing purpose. To be able to consume events coming from the Test Server one can connect via WebSocket following the steps above and point to the endpoint containing the matchId as “2 015-999-XX999”:
The test feed will play a real historical match (with the names of the players modified). The match events are sent in an interval of 5 secs with heartbeats messages every 10 secs.
"startPosition" parameter
Note that you can pass the "startPosition=*" parameter in the websocket, where "*" refers to the sequence number the connection should start from. i,e: wss://dde-streams.data.imgarena.com/tennis/events/2024-XXXX-MSXXX/stream?startPosition=100 The websocket feed will start the at sequence number 100 instead of 0.
This section contains details on the following websockets endpoints:
This stream summarises the scoring events from a tennis match. E.g. number of aces served, 1st serve percentage, break points, e.t.c... If you connect to the stream when the match has already started, you will receive only the latest statistics. Unlike the events stream, there is no facility to replay the statistics from the start.
This endpoint takes no parameters.
New URL:
Old URL:
N.B. – Please use event ID “2022-0784-QS010” to return you the sample data. The authentication token provided will be required to make a connection to this websocket endpoint.
Connect to SSL websocket address
Send JSON packet containing API token
Format to send API token:
{"authToken": "authentication 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.
After the websockets connection has been made and the connection authorised, you will receive the packets (assuming you haven’t specified a start position).
Note that packets are checked for timeliness and in the event that data from the supplier is delayed, an extra field: delayStatus will be added to the packets below. If the field is present then the packets should be considered as not live.
The delayStatus field will typically take one of two values:
● DELAYED - click here for more information on delayed packets
● RECONSTRUCTED - click here for more information about Alarms and Reconstructions
Field Name
Type
Description
matchState
object
The match state object
teamAPlayer1
string
The name of the first player in team A
teamBPlayer1
string
The name of the first player in team B
teamAPlayer2
string
(Doubles only) The name of the second player in team A
teamBPlayer2
string
(Doubles only) The name of the second player in team B
teamAPlayersDetails
object
The players details (e.g. ID and IOC country code) for team A
teamBPlayersDetails
object
The players details (e.g. ID and IOC country code) for team B
umpire
string
The name of the umpire
umpireCode
string
The code for the umpire
umpireCountry
string
The country of the umpire
scoringType
string
The scoring type being used for the match: Standard, StandardWithNoAdv, ShortSets, ProSet, MatchTieBreak, SuddenDeath, ModernSetShort, ModernSetLong, ModernSetWithNoAdv, Unknown, LastSetTiebreak12,ATPShortSetNoAdv
numSets
int
How many sets the match may involve
firstServer
string
The team who is serving first in the match
courtNum
string
The court the match is being played on
tieBreakType
string
The type of tie breaks being used in the match - possible values are “TieBreakInFinalSet” and “NoTieBreakInFinalSet”
tossWinner
string
Player who won the toss
tossChooser
string
What the player who won the toss elected to do - possible values are “Serve”, “Ends”, “GaveChoiceToOpponent”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
matchTime
string
The match time of this packet
Field Name
Type
Description
player1Id
string
The player Id of the first player in team A
player2Id
string
(Doubles only) The player Id of the second player in team A
player1Country
string
The country code of the first player in team A
player2Country
string
(Doubles only) The country code of the second player in team A
Field Name
Type
Description
player1Id
string
The player Id of the first player in team A
player2Id
string
(Doubles only) The player Id of the second player in team A
player1Country
string
The country code of the first player in team A
player2Country
string
(Doubles only) The country code of the second player in team A
Field Name
Type
Description
state
string
The state of the match can be one of: NotStarted, UmpireOnCourt, PlayersArriveOnCourt, Warmup, InProgress, Suspended, Unsuspended, Complete, ToiletBreak, MedicalTimeout, MedicalTreatment, ChallengeInProgress, BallMarkInspection, CorrectionMode, PostSuspensionWarmup, PostSuspensionMatchRestart, Default, Retire
locationTimestamp*
string
(*) This is an optional field for all match state changes
suspensionType*
string
(*) This is an optional field for a Suspended/Unsuspended match state only: Rain, Heat, Darkness, Pause, TenMinuteHeatBreak, Other, Unknown
suspensionEnded*
timestamp
(*) This is an optional field for a Suspended/Unsuspended match state only
team*
string
(*) This is an optional field for a ChallengeInProgress, ToiletBreak, MedicalTreatment or Default/Retire match states only, meaning who called the challenge or who has decided to retire from the match.
playerId*
int
(*) This is an optional field for MedicalTreatment match state only indicating which player is being treated
won*
string
(*) This is an optional field for a ChallengeInProgress match state only, meaning who won the challenge.
challengeEnded*
timestamp
(*) This is an optional field for a ChallengeInProgress match state only, meaning when the challenge has ended.
reason*
string
(*) This is an optional field for a Default/Retire match states only, meaning the retirement reason: Illness, Injury, Walkover, Other, Unknown, Unspecified, UnreasonableDelay ,AudibleObscenity, VisibleObscenity, BallAbuse, RacquetAbuse, VerbalAbuse, PhysicalAbuse,Coaching, UnsportsmanlikeConduct
evaluationStarted*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio started evaluating the player
treatmentStarted*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio started treating the player
treatmentLocation*
string
(*) This is an optional field for a MedicalTreatment match state only indicating where the physio is treating the player. Either “OnCourt”, “OffCourt” or “Unknown”
treatmentEnded*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio stopped treating the player
toletBreakEnded**
timestamp
(**) This will be within the second toiletBreak packet.
When there is a declined TenMinuteHeatbreak, we will return a Unsuspended packet (without a proceeding Suspended packet) with the suspensionType set as TenMinuteHeatBreak and suspensionEnded.
ToiletBreak consists of two consecutive packets - the first is the start, the second is the end of the break. The game will recommence properly with the InProgress packet that will follow shortly afterwards.
Field Name
Type
Description
state
string
The state of the match can be one of: NotStarted, UmpireOnCourt, PlayersArriveOnCourt, Warmup, InProgress, Suspended, Unsuspended, Complete, ToiletBreak, MedicalTimeout, MedicalTreatment, ChallengeInProgress, BallMarkInspection, CorrectionMode, PostSuspensionWarmup, PostSuspensionMatchRestart, Default, Retire
locationTimestamp*
string
(*) This is an optional field for all match state changes
suspensionType*
string
(*) This is an optional field for a Suspended/Unsuspended match state only: Rain, Heat, Darkness, Pause, TenMinuteHeatBreak, Other, Unknown
suspensionEnded*
timestamp
(*) This is an optional field for a Suspended/Unsuspended match state only
team*
string
(*) This is an optional field for a ChallengeInProgress, ToiletBreak, MedicalTreatment or Default/Retire match states only, meaning who called the challenge or who has decided to retire from the match.
playerId*
int
(*) This is an optional field for MedicalTreatment match state only indicating which player is being treated
won*
string
(*) This is an optional field for a ChallengeInProgress match state only, meaning who won the challenge.
challengeEnded*
timestamp
(*) This is an optional field for a ChallengeInProgress match state only, meaning when the challenge has ended.
reason*
string
(*) This is an optional field for a Default/Retire match states only, meaning the retirement reason: Illness, Injury, Walkover, Other, Unknown, Unspecified, UnreasonableDelay ,AudibleObscenity, VisibleObscenity, BallAbuse, RacquetAbuse, VerbalAbuse, PhysicalAbuse,Coaching, UnsportsmanlikeConduct
evaluationStarted*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio started evaluating the player
treatmentStarted*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio started treating the player
treatmentLocation*
string
(*) This is an optional field for a MedicalTreatment match state only indicating where the physio is treating the player. Either “OnCourt”, “OffCourt” or “Unknown”
treatmentEnded*
timestamp
(*) This is an optional field for a MedicalTreatment match state only indicating when the physio stopped treating the player
tolietBreakEnded**
timestamp
(**) This will be within the second toiletBreak packet.
Field Name
Type
Description
team
string
Which team is serving: TeamA or TeamB
member
int
Which member of the team is serving
Field Name
Type
Description
team
string
Which team is serving: TeamA or TeamB
member
int
Which member of the team is serving
Field Name
Type
Description
seqNum
int
Sequence number of the packet
timestamp
timestamp
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The match time of this packet
server
object
The server of this point
nextServer
object
The next team to serve
score
object
The match score
details
object
Additional details about the how the point was scored: Ace, Double Fault
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of three values: DELAYED, RECONSTRUCTED or RECONSTRUCTED_INACCURATE
Field Name
Type
Description
seqNum
int
Sequence number of the packet
timestamp
timestamp
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The match time of this packet
server
object
The server of this point
nextServer
object
The next team to serve
score
object
The match score
details
object
Additional details about the how the point was scored: Ace, Double Fault
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of three values: DELAYED, RECONSTRUCTED or RECONSTRUCTED_INACCURATE RECONSTRUCTED_INACCURATE is very rare and is used in the extreme edge case where the reconstructed scoring packets add up to a score that does not equal the current match score sent in the latest upstream packet. This would be applied to all reconstructed packets that are sent in the catch-up stream.
Field Name
Type
Description
currentGameScore
object
Current game score
currentSetScore
object
Current Set score
previousSetsScore
object
Array of previous Set scores
overallSetScore
object
The overall set score in the match
Field Name
Type
Description
currentGameScore
object
Current game score
currentSetScore
object
Current Set score
previousSetsScore
object
Array of previous Set scores
overallSetScore
object
The overall set score in the match
Field Name
Type
Description
gameType
string
The type of the game (e.g. “TieBreaker” or “StandardGame”)
pointsA
string
Points scored by TeamA
pointsB
string
Points scored by TeamB
Field Name
Type
Description
gameType
string
The type of the game (e.g. “TieBreaker” or “StandardGame”)
pointsA
string
Points scored by TeamA
pointsB
string
Points scored by TeamB
Field Name
Type
Description
gamesA
int
Number of games won by TeamA
gamesB
int
Number of games won by TeamB
Field Name
Type
Description
gamesA
int
Number of games won by TeamA
gamesB
int
Number of games won by TeamB
Field Name
Type
Description
gamesA
int
Number of games won by TeamA
gamesB
int
Number of games won by TeamB
tieBreakScore
object
Tie-break score for the Set
Type
Description
gamesA
int
Number of games won by TeamA
gamesB
int
Number of games won by TeamB
tieBreakScore
object
Tie-break score for the Set
Field Name
Type
Description
pointsA
int
Points scored by TeamA
pointsB
int
Points scored by TeamB
Field Name
Type
Description
pointsA
int
Points scored by TeamA
pointsB
int
Points scored by TeamB
Field Name
Type
Description
scoredBy
string
The team who has scored the point
pointType
string
The type of the point: Standard, DoubleFault, Ace, Unknown
Field Name
Type
Description
scoredBy
string
The team who has scored the point
pointType
string
The type of the point: Standard, DoubleFault, Ace, Unknown
Field Name
Type
Description
setsA
int
Number of sets for Team A
setsB
int
Number of sets for Team b
Field Name
Type
Description
setsA
int
Number of sets for Team A
setsB
int
Number of sets for Team b
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
The PointStarted packet is used to signify the start of a point. Point Started can be used to close markets for the next available point e.g.
Point Started JSON
Can be used to close markets on the next available point in this game/match.
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
faultType
string
The type of the fault:“Fault”, “FootFault”
matchId
string
The match id
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
faultType
string
The type of the fault:“Fault”, “FootFault”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
The point must be replayed. The umpire indicates this type of let by announcing "Let. First serve," or "Let. Second serve." Lets typically occur when an otherwise-valid serve makes contact with the net before hitting the ground. Theoretically, a player could serve an infinite number of otherwise-valid let serves, but a serve that touches the net and then lands out of bounds counts as one of the two allowed serves (fault). A let can also be called during play when there is some distraction to either player not caused by the players themselves, such as a ball boy moving behind a receiver, debris flying across the court in windy conditions, or a ball accidentally falling out of a player's pocket or entering from a neighbouring court. The call is made by the chair umpire when one is assigned to the match
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised (e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised (e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised(e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised(e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised(e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
N.B - The game penalty packets will be delivered sequentially until a full game has been awarded to the opposing team (e.g. if a game penalty is triggered at 15-0 by the receiver, you will receive three packets sequentially to complete the game)
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
server
object
The server for this point
nextServer
object
The next player/team to server
team
string
The name of the team penalised(e.g. “TeamA” or “TeamB”)
score
object
The match score after the penalty has been applied
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
score
object
The current score of the match
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
N.B - that the undo packet only occurs when the match state has been changed to correction mode. A number of undo packets may be received which indicates that the umpire is correcting information that has previously been entered.
Once the umpire comes out of correction mode (match state would typically move back to inProgress) they will reissue the correct score as a point scored packet, as the definitive confirmation of the current match score.
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
score
object
The current score of the match
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
score
object
The current score of the match
numOverrules
int
Total number of overrules in the match
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
score
object
The current score of the match
numOverrules
int
Total number of overrules in the match
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The name of the team (e.g. “TeamA” or “TeamB”)
playerId
int
The identifier of the player on the team: 0 (= whole team if doubles), 1 or 2
reason
string
The reason of the code violation:
Unspecified
UnreasonableDelay
AudibleObscenity
VisibleObscenity
BallAbuse
RacquetAbuse
VerbalAbuse
PhysicalAbuse
Coaching
UnsportsmanlikeConduct
Unknown
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The name of the team (e.g. “TeamA” or “TeamB”)
playerId
int
The identifier of the player on the team: 0 (= whole team if doubles), 1 or 2
reason
string
The reason of the code violation:Unspecified, UnreasonableDelay, AudibleObscenity, VisibleObscenity, BallAbuse, RacquetAbuse, VerbalAbuse, PhysicalAbuse, Coaching, UnsportsmanlikeConduct, Unknown
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The ATP packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The name of the team (e.g. “TeamA” or “TeamB”)
playerId
int
The identifier of the player on the team: 0 (= whole team if doubles), 1 or 2
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The ATP packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The name of the team (e.g. “TeamA” or “TeamB”)
playerId
int
The identifier of the player on the team: 0 (= whole team if doubles), 1 or 2
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team which asked for the physio to be called
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team which asked for the physio to be called
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team which asked for the physio to be called
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The ATP packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team which asked for the physio to be called
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The ATP packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next player/team to server
server
object
The server of this point
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next team serving
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
nextServer
object
The next team serving
server
object
The server of this point (same as nextServer for this packet)
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team name (“TeamA” or “TeamB”)
status
string
The status of coaching on court: “Started”, “Finished”, “Unknown”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
team
string
The team name (“TeamA” or “TeamB”)
status
string
The status of coaching on court: “Started”, “Finished”, “Unknown”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
time
string
The local time of the match
matchTime
string
The match time of this packet
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
time
string
The local time of the match
matchTime
string
The match time of this packet
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
won
string
The team name who has won the match
reason
string
The reason of winning - one of: - “Normally”, “Retirement”, “SuddenDeath”, “Default", “Unknown”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
N.B - If you are looking for a programmatic way of closing event websocket connections at the end of a match we would recommend using the MatchFinished packet as the trigger.
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type
matchTime
string
The current match time
won
string
The team name who has won the match
reason
string
The reason of winning - one of: - “Normally”
“Retirement”
“SuddenDeath”
“Default"
“Unknown”
delayStatus
string
Optional field, if present this packet should be considered delayed. Can take one of two values: DELAYED or RECONSTRUCTED
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type - Alarm
lastReceivedTimestamp
string
The timestamp of the last received upstream event packet
The Alarm Packet is sent when we suspect we have been disconnected from an onsite event. We will resend this packet every 25 seconds until the issue has been resolved, at which point we will send the next returned packet.
Field Name
Type
Description
seqNum
int
The packet sequence number
timestamp
string
Timestamp of this packet
eventElementType
string
The event element type - Alarm
lastReceivedTimestamp
string
The timestamp of the last received upstream event packet
If the umpire makes a mistake when entering data on the scoring tablet they will correct it. This changes the match state to CorrectionMode.
Within correction mode a sequence of packets will be received. These will either be:
● Undo packets which will reverse previous events. The score may be altered (e.g. going from 30-0 to 15-0) and the indicator for next server may change.
● Other packets effectively replacing the ones that were undone. These could be any other standard packets.
When all corrections have been made the next packet will change the match state from CorrectionMode to whatever the correct value is. The umpire will then reissue the correct score as a point scored packet, as the definitive confirmation of the current match score. From this point all packets are standard live packets as described previously.
This section will cover the basic packets that will be a part of every game
This is the packet that starts the point.
Point Started JSON
Use 'Point Started' packets to automatically close markets and to suspend betting
This packet indicates that a team has faulted on service.
Fault JSON
A point packed is received whenever a player wins a point. They are generally standard, aces or double faults.
Standard Point JSON
Ace Point JSON
Double Fault JSON
When you receive a new packet, with a currentGameScore of 0-0, with the currentSetScore updated and the server being changed, this indicates that a player has won the previous game. The player who won the point will be the player who has won that particular game.
Game Won JSON
This packet indicates that the umpire has called time at the end of the changeover and that the match needs to continue
Time Called JSON
This section will describe the packets that are received upon the start of the match. At the start of every tennis match, the same packets should be received in the same order.
If you connect to any match that has not started, you will receive the following packet. This packet is always a response to any match that has not started and it will always be the packet with sequence number 0 when connecting to any websocket event.
The packet is as follows:
MATCH STATUS UPDATE - Not Started JSON
The first packet with information on each match, with "seqNum" : 1 will always be the Umpire On Court Packet.
This will include information on the Umpire and the players, the scoring type and set length of the match. Receiving this packet means that the match is going to start shortly.
The packet is as follows:
MATCH STATUS UPDATE - Umpire On Court JSON
The second packet that is received is the 'Players Arrive on Court' packet. This indicates that both players are on the court and are preparing for the match.
The packet is as follows:
MATCH STATUS UPDATE - Players Arrive On Court JSON
The next packet will indicate that the state of the match is in 'Warmup' and that the players are warming up.
This packet will also contain information on which player won the coin toss, and whether they chose to serve, receive or chose a particular side.
The packet is as follows:
MATCH STATUS UPDATE - Warmup JSON
The next packet, 'In Progress', will indicate that the match has started.
The packet is as follows:
MATCH STATUS UPDATE - In Progress JSON
Following the above, when the first point in the match is under way, the umpire will issue a 'Point Started' packet.
This packet is issued at the start of every point in any match.
Use 'Point Started' packets to automatically close markets and to suspend betting.
Point Started JSON
After the WebSockets connection has been made and the connection authorised, you will first receive the initial packet:Field NameTypeDescription
Field Name
Type
Description
teamAPlayer1
string
The name of the first player in the team
teamAPlayer2
string
(Doubles only) The name of the second player in the team . referred to as team A.
teamBPlayer1
string
The name of the first player in the team referred to as team B.
teamBPlayer2
string
(Doubles only) The name of the second player in the team . . . referred to as team B.
Every subsequent packet will be a Combined Statistics object with the following format:
Field Name
Type
Description
match
object
The overall statistics for the match
set1
object
The statistics for set 1
set2
object
The statistics for set 2 (if set has started)
set3
object
The statistics for set 3 (if set has started)
set4
object
The statistics for set 4 (if set has started)
set5
object
The statistics for set 5 (if set has started)
Only Grand Slam matches go up to five sets for men and three for women. Usually, the first player to win six games wins a set. Click here for more specific tournament scenarios.
Field Name
Type
Description
teamA
object
The team statistics for team A serving
teamB
object
The team statistics for team B serving
Field Name
Type
Description
aces
int
The number of aces served by the player
totalServes
int
The total number of serves by the player
1stServe
int
The total number of successful (non-fault) 1st serves
1stServe%
double
The percentage of successful 1st serves
1stServePointsWon
int
The number of points won on a 1st serve
1stServePointsWon%
double
The percentage of points won on a 1st serve
2ndServes
int
The total number of successful (non-fault) 2nd serves
2ndServePointsWon
int
The number of points won on a 2nd serve
2ndServePointsWon%
double
The percentage of points won on a 2nd serve
breakPointsPlayed
int
The number of break points against the player’s serve
breakPointsSaved
int
The number of break points saved
faults
int
The number of faults served by the player
doubleFaults
int
The number of double faults served by the player
Please find a breakdown of the full schema for /statistics endpoint
We provide four test streams; these streams allow the end user to connect and consume data in one environment. We have a unique test flow for Singles and Doubles.
Singles: In this stream, you will consume a singles match, the event starts with a delayed packet and then comes online in an expected pre-match sequence. The remaining match data can be found is explained here.
https://dde.imggaming.com/#/tennis/tournaments/179/event/2015-999-XX999?day=2015-10-01
Doubles: In this stream, you will consume a doubles match; the event starts off with an expected pre-match sequence. Which is followed by a variety of suspensions, the suspensions are prior to a range of different packets Toilet Break, Medical Timeout, Challenge, Ball Mark Inspection, Correction Mode, Retire and Penalties.
https://dde.imggaming.com/#/tennis/tournaments/179/event/2015-999-XX998?day=2015-10-01
Please find a breakdown of the full schema for /events endpoint
An overrule happens when an umpire disagrees with a line judge on a call. It is occasionally linked with 'Point Replayed' - See 'Point Replayed' section for when they are used in conjunction with Point Replays.
Scenario A
Player A hits the ball wide down the line. It is really close, so the line judge calls it in. The umpire disagrees and overrules the line judge's decision and calls the ball out. The point goes to player B.
Scenario B A line judge may call a ball out. The players stop playing as a result. The umpire disagrees that the ball was out and overrules the line judge's decision. As the players stopped playing the point, the point needs to be replayed.
Generally, an overrule packet will come after a 'Point Started' packet, and before the Point packet.
For example, using Scenario A from above:
Receive 'Point Started' packet
Point plays through
Umpire and line judge disagree, umpire overrules line judge
Receive Point Packet
Receive 'Overrule' packet, e.g.:
Overrule JSON
There are a number of scenarios when a point may be replayed in a match:
Scenario A A line judge may call a ball out. The players stop playing as a result. The umpire disagrees that the ball was out and overrules the line judges decision. As the players stopped playing the point, the point needs to be replayed.
Scenario B Players are in a long rally. Player A thinks the ball was out, as does the umpire. The rally stops. Player B challenges this call, and wins the challenge (the ball was in). The point is replayed.
Scenario C
Player X is preparing to take a first serve. The crowd is silent. As she goes to serve, someone shouts out loudly and puts her off and she misses the serve. The umpire decides to replay the point on a first serve.
Generally, the packets will come between 'Point Started' packets.
The flow will be (for scenario A above):
'Point Started' packet received
Point plays out
Umpire disagrees with line judge over decision and overrules it. Umpire decides to replay the point
'Point Replayed' packet received, e.g:
Point Replayed JSON
On certain courts at certain tournaments, when the technology is available, players/teams can choose to challenge the call of the umpire or line judge if they think that they have made a mistake.
Teams have 3 unsuccessful challenges per set, with one more added if the set goes to a tiebreak. If they are successful in a challenge then they keep that challenge (e.g. if they are on 2 challenges and they win the challenge, they still have 2 challenges remaining)
There are a number of scenarios, e.g:ScenarioExample
A
Player A hits the ball OUT, the ball is called IN. Player B challenges, and WINS the challenge.
B
Player A hits the ball IN, the ball is called OUT. Player A challenges, and WINS the challenge.
C
Player A hits the ball OUT, the Ball is called OUT. Player A challenges. and LOSES the challenge.
D
Player A hits the ball IN, the ball is called IN. Player B challenges, and LOSES the challenge.
The 'Challenge' packets will come after 'Point Started' packets and before 'Point' packets.
Here is a standard challenge scenario (Score is 0-0 in the game):
'Point Started' packet received
Player B hits the ball long, ball is called long. Player B challenges. 'Challenge' Packet received, e.g:
Challenge JSON
Next, after the challenge has been reviewed, the Challenge will either have won or lost, and you will receive a packet like the following.
The packet contains the information that Team A won the challenge:
Challenge Lost (Player B) JSON
The next packet will be the 'In Progress' packet, indicating that the match is out of 'Challenge' Mode
After this the 'Point' packet will be sent with the correct score (In this case 15-0, as Player A won the point)
A toilet break can be taken by either, or both teams, at any changeover between games including before the start of the first game.
After a 'Game Won' packet has been received and one or both teams have requested a toilet break, the next packet that will be received will be a 'Toilet Break' packet, e.g for one team (Team A):
Toilet Break JSON
Once the team have finished their toilet break, the 'Toilet Break - Over' packet will be sent, e.g:
Toilet Break - Over JSON
After this point, time will be called by the umpire and the match status will be updated to 'In Progress'. The match will resume as normal.
A Ball Mark Inspection (BMI) is an event that only happens on clay courts.
They work very similarly to challenges, a BMI happens when a line judge calls a ball and the team/player disagrees. The umpire will then come down to the court and take a look at the mark that the ball made on the clay, and judge if the ball was out or in.
A BMI will occur at the same time as a challenge - After 'Point Started' and before the 'Point' packet.
It does not include information on if it was 'won' or 'lost' - just that there was a BMI. The next point is always the outcome of the BMI (who the point is awarded to).
An example from the French Open, 2024:
Ball Mark Inspection JSON
Followed by an "inProgress packet to indicate that the BMI is being carried out:
There are three cases when there is a Game Penalty packet. One of them is fully explained in the 'Code Violations, Game Penalties & Defaults' section
There are two other cases where the Game Penalty Keystroke is used by the umpire as the official way of reporting points; one where a player must forfeit points before receiving medical treatment, and the other when an umpire has to manually modify the score.
This is a relatively new rule that has been in place since 2010. I stipulates that, when a player gets cramp, they are not allowed to take a medical timeout straight away. The player has to play through until the next changeover or end of set.
However, if the player is unable to play through to the changeover or the start of the next set, then they are entitled to forfeit all of the points up until the changeover/start of the next set if they want to receive treatment.
In this case, the player who has cramp will forfeit the points. These forfeited points will show up as Game Penalties for that player. A way to differentiate this from any other use of the Game Penalty would be to note that in this case the game penalties will all be for one of the players only.
An example of the keystrokes would be as follows:
*There are two games until the changeover, the score is 0/40 to player B
Point Started
Point Scored
PLAYER A GETS INJURED
Game Penalty Player A - Game Player B
Game Penalty Player A - 0/15
Game Penalty Player A - 0/30
Game Penalty Player A - 0/40
Game Penalty Player A - Game Player B
Medical Timeout - Player A
The Umpire modifying the score is a very rare event. It occurs mostly when there is a faulty tablet.
e.g. a match started but the tablet was faulty. A new tablet will be sourced, but the match will continue without a tablet until it is sourced. (All tournaments have spare tablets so this is normally not long). When the new tablet is sourced, the umpire will have to manually input the score into the tablet so that the score is up to date - this is when the 'Umpire Modifying the Score' event happens.
In this case, the ATP will send us Game Penalty packets for both players that makes up to the correct state in the game. The Game Penalty packets will be sent by awarding games to players alternatingly and will always start from the beginning of the match.
An example of the keystrokes would be as follows:
*There is a faulty tablet at the start of the match - the players played on until 2-1 to Player A in the first set:
Game Penalty Player B - 15/0
Game Penalty Player B - 30/0
Game Penalty Player B - 40/0
Game Penalty Player B - Game Player A - 1-0
Game Penalty Player A - 15/0
Game Penalty Player A - 15/0
Game Penalty Player A - 15/0
Game Penalty Player A - Game Player B - 1-1
Game Penalty Player B - 15/0
Game Penalty Player B - 30/0
Game Penalty Player B - 40/0
Game Penalty Player B - Game Player A - 2-1
In a match, an umpire can also call a Code Violation against a player.
- Code Violation: A player is judged to have violated the code of conduct that the tennis federations have set out. This includes but is not limited to; audible obscenity, physical abuse, ball abuse and unsportsmanlike conduct.
The following occurs as a result of the above Code Violations:
- First Offence: Warning - Second Offence: Point Penalty (The player's opposition are given the next point in the game) - Third Offence: Game Penalty (The player's opposition are given the next game in the set)
Any further offences will result in more Game Penalties. However, after the third violation, the umpire is within their right to default the match in the favour of the opponent of the player who continues to carry out Time/Code violations.
In this case, the CodeViolation packet will be send whenever the offence occurred in the match. In this case it occurred straight after a point.
The packet is as follows:
CodeViolation JSON
In this case, the team has committed their second Time/Code Violation of the match.
The packet will be sent through as a Time/CodePenalty packet. This means that the team committing the offence will lose a point.
The packet is as follows:
Point Penalty JSON
In the example above, the score was at 30-30, but Team A committed a Code Violation, and as it was their second Code Violation, they received a Point Penalty, and the score is changed to 30-40.
In this case, the team has committed their third Time/Code Violation of the match.
The packet will be sent through as a GamePenalty packet. This means that the team committing the offence will lose the current game / the next game in the match.
The packet is as follows:
Game Penalty JSON
N.B - We will send through a number of GamePenalty packets until the game has been fully awarded to the opposing team.
For example: If the score is 15-0 and the receiver triggers a game penalty packet through their third Code Violation, then we will send THREE packets to finish the game (30-0, 40-0, game). The packets will all be identical.
After a team commits a third violation, the umpire has the right, if that team commits another violation, to default the match in favour of the opposition. The umpire can also wait and do this on the 4th, 5th, e.t.c... violation if they so wish.
Additionally, an umpire can also default a match after the first or second violation, if they deem the violation to be considered serious enough. An example of this happening in the first violation is if a player hits a tennis ball at the umpire.
The packet is as follows:
Match Default JSON
Delayed packets are packets that we have flagged as receiving late and are not being sent in real time. Any packets flagged with a Delayed status should be explicitly treated as non-live. A delayed packet is commonly noticed when connectivity issues are experienced locally at the given Tennis tournament.
Delayed packets can occur at any time during the match, as long as we understand that the packet has not been sent in real time.
An example of a delayed packet:
Delayed Packets JSON
Match results will be calculated as soon as the umpire enters the final point into their tablet.
However, the match is not confirmed as FINAL until the 'Match Finished' packet is sent.
This is done so that if the umpire makes a mistake awarding a point to a team, they can undo it.
The 'Match Finished' packet is the final packet that is sent through for a match, e.g:
Match Finished JSON
You should use this packet to:
Settle Winner Markets
Assume that the event has finished and disconnect from the event
Matches can be suspended for a number of reasons. The most common reasons are:
Rain Delays (Outside Courts only)
Darkness (Outside Courts only)
Pause (E.g. Streaker on court, or when the rain is very light and the umpire pauses briefly to check if play can continue)
Heat - this can also be specified as a 10 minute heat break (Court becomes too hot, or they need a water break)
Other (Can be for any of the reasons stated above, and is the default suspension reason prior to a match entering warm-up pre-match)
Suspension packets can come at any time, as matches can become suspended at any time.
Below is a Rain suspension
Suspension - Rain JSON
Once a suspension is over, an unsuspended packet is sent, e.g:
Unsuspended JSON
Then, depending on how long the suspension was, there may be a 'Post Suspension Warm Up' packet, e.g:
Post Suspension Warm Up JSON
However, if the suspension was not long, there will not be a warm up. The next packed will simple be the 'In Progress' packet.
Our API sends heartbeats every 10 seconds to still indicate a healthy connection to the event.
However, if there are local connection/power issues at an event we will send an alarm packet. From that point on, we will send a new alarm packet every 25 seconds until the connection is restored at which point we will reconstruct all of the lost packets.
Whilst we aim to limit this, in global areas with limited internet infrastructure there will always unfortunately be an amount of connectivity issues. This is improving year on year.
As soon as we are aware there are connectivity issues, we will issue an alarm packet much like the following:
ALARM JSON
You should use Alarm packets to suspend markets
If the connectivity issues persist and the players continue to play, we may not deliver packets live. As soon as connectivity is re-established, we will reconstruct all of the missing keystrokes, as live. They should not be treated as live but will provide an accurate point-by-point description of what happened.
An example of a reconstructed packet is as follows:
RECONSTRUCTED JSON
In the event that a match goes offline and we need to reconstruct the keystrokes, we will attempt to reconstruct the correct keystroke sequence up to the confirmed state of the match upon the match coming back online.
If we are unable to do so, the keystroke packets that we know are inaccurate will be marked with RECONSTRUCTION INACCURATE. You should assume these are inaccurate and these should not be used to settle point-by-point markets.
Please note that these are incredibly rare.
This section summarises the Player & Ball Tracking Websockets that are available via the DDE
Within this section you will find schema information, samples with supporting documentation, as well as information about authentication protocol.
For availability of P&B Tracking feeds across specific Tournaments and Tours, please contact support@openbet.com
The Stream API provides a stream of live match data as JSON over a WebSocket connection. Please see the below for how to connect to the stream endpoint.
This section defines how to connect to the websocket. This works well in Postman.
Once a fixture has been requested and accepted, any further fixture requests will be ignored
The connection must be closed and a new one opened to get a new fixture feed
The connection will be closed with a message
The connection will remain open and a warning message will be returned
Players can retire from tennis matches at two points; either before the match has started (and it is granted as a walkover for their opposition) or during the match.
This occurs when a player sustained an injury and cannot compete in their next match.
In this case the umpire will log into the tablet and the match will process as follows:
'Umpire on Court' packet sent
'Retire - Walkover' packet sent, e.g:
Retire - Walkover JSON
'Match Finished' - Retirement packet sent, e.g:
Match Finished - Retirement JSON
A player can retire from injury at any point in a match. The packets are normally sent after a 'Point' packet mid-game, or during a changeover.
An example as follows:
Retirement - Injury JSON
Following this packet, a 'Match Finished' packet will be sent, as above. i.e:
If a player takes longer than 25 seconds between a point, they are in violation of tennis rules and the umpire will issue them a Time Violation.
The following occurs as a result of the above Time Violations:
- First Offence: Warning - Second Offence - Receiver: Point Penalty (The player's opposition are given the next point in the game) - Second Offence - Server: Serve Loss (The server is given a fault) - Third and Subsequent Offences - Receiver: Point Penalty (The player's opposition are given the next point in the game) - Third and Subsequent Offences - Server: Serve Loss (The server is given a fault)
This will continue for as long as the umpire sees fit. If the Time Violations continue, then the umpire is within their right to start issue Code Violations (see ).
When an umpire realises that they have made a mistake and have keyed in some incorrect information into their tablet, they will attempt to undo this mistake.
An umpire can undo any input on the tablet. The two main categories are; undoing a point event (this will alter the score of the game/set/match) or undoing a non-point scoring event (for example accidentally keying in a toilet break for a player).
When an umpire presses 'Undo' the tablet they are using will go into 'Correction Mode'. From this point, every packet that is sent through is in 'Correction Mode', and our packets will reflect this. The packets will come out of 'Correction Mode' when the umpire has finished correcting their mistakes.
After the packets have come out of 'Correction Mode', we will re-issue the last correct keystroke before the mistake, so that you can easily work out at what point the match is.
If an umpire accidentally gives the point to the wrong team, and immediately realises this, they will undo the point.
Here's an example scenario (Score of this game is 0-40):
'Point Started' packet received
Umpire incorrectly awards the point to Player B, 'Point' packed received with 15-40 as the score
'Correction Mode' packet received:
'Undo' packet received, with the score undone back to 0-40
JSON
'Match Status Update - In Progress' packet received, to indicate the match is out of 'Correction Mode'
Last Correct Keystroke packet sent again. In this case, this is the last point of the previous game, which manifests itself as the ‘Game Won’ keystroke.
Correct 'Point' Keystroke
As mentioned, an umpire can also undo a mistake on the tablet that is not based around points.
For example, this scenario shows an umpire undoing a challenge (Score is at 15-0 to Player A at the start):
'Point Started' packet received
'Challenge' packet received
Umpire realises they put this in as mistake, 'Correction Mode' packet received
'Undo' packet received, but NO change in the score (still 15-0)
'Match Status Update - In Progress' packet received, to indicate the match is out of 'Correction Mode'
Last keystroke packet sent (15-0).
This section summarises the Rally player & ball tracking websocket that is available via the DDE.
Below are the available websocket with more information on the data being returned.
CONNECT wss://dde-generic-datastream.dde-prod.imgarena.dev/ws/tennis/rally/tracking/tdi
This endpoint returns 4 different types of rally information for a match:
For availability of P&B Tracking feeds across specific Tournaments and Tours, please contact support@openbet.com
It important to note that a retirement packet may or may not be received after a - sometimes a player will request medical attention and attempt to continue before retiring, but in other circumstances they will be too injured to continue and will retire without treatment.
Please see this example on the DDE UI at 01:07:00 match time .
Rally Summary
Describes all the summary for a rally - Breakdown of points won per player by rally length grouping and the Average number of shots per rally, distance travelled, winning shot (speed/stroke/result)
Per Rally Event
Describes all the events which happened during a rally (spin, type (back/forehand), speed, duration, result)
Per Rally Ball/Shot Tracking
Describes all the shots in a rally (arcs x/y/z)
Per Rally Player Tracking
Describes all the player movement in a set timeframe- (Time, Position, velocity)
When a player has a medical problem that requires assistance from a physio, they must call for a physio and wait until the next changeover in order to receive treatment.
In the case that their issue is so severe that they cannot continue to the changeover, but do not want to forfeit the match, a team/player can choose to forfeit all of the points up until the next changeover, and then receive treatment during a medical timeout.
If a player needs a medical timeout, they will ask the umpire to call the physio so that the physio can prepare for the medical timeout.
This can happen at any point, and the following packet will be sent:
Then as soon as the changeover starts, after the 'Game Won' packet, the Medical Timeout Packet will be sent. The first medical timeout has information on when the evaluation of the player starts.
There are always 2 medical timeout packets - the first indicates when the player evaluation starts (below). This is when the physio and the player talk about the injury and how the physio can help, but no treatment is given, e.g:
Medical Timeout - Player Evaluation JSON
The next packet is sent when the actual treatment starts, e.g:
Medical Timeout - Treatment Started JSON
And then once the treatment has finished, you will receive the 'Treatment Finished' Packet, e.g:
MATCH STATUS UPDATE - Medical Timeout - TeamA - Treatment Finished JSON
The match will then resume, time will be called, and the match will enter back in progress.