Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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)
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.
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.
All DateTime objects are returned using the ISO 8601 combined format. For more information about ISO 8601, please read here.
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.
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 Event Disconnections - this defines what alarm packets are and why these should not be mistaken for a disconnection.
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
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:
Acronym
Type
MS
Men's Singles
LS
Ladies' Singles
MX
Mixed Doubles
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:
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
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:
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
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:
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
