Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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
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
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 here).
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
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
Please see this example on the DDE UI at 01:07:00 match time here.
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).
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
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
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.
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:
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
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)
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.
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.
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.
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.
It important to note that a retirement packet may or may not be received after a 'Medical Timeout' - 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.
An example as follows:
Retirement - Injury JSON
Following this packet, a 'Match Finished' packet will be sent, as above. i.e: