Live Tennis API DocsGet a free key
Explore the documentation

Live Tennis API · docs · guide

Tennis score mapping to IPTC SportsML

How does the Live Tennis API score object map to IPTC SportsML? Each field of the Score object is listed with the SportsML 3.1 element or attribute it becomes, or with no direct equivalent. Every SportsML name links to IPTC's documentation. A worked example and six synthetic fixtures show the mapping in real files.

Mapped against IPTC SportsML 3.1 as published on iptc.org, read on . Fixtures under CC BY 4.0.

Which SportsML version does this map to?

The mapping uses SportsML 3.1, the newest version on iptc.org. IPTC released it in June 2019. The tennis part of the standard is a plugin schema, sportsml-specific-tennis.xsd, which the main schema includes. Both files carry IPTC's CC BY 4.0 notice.

The mapping was read from the schema files, the tennis plugin documentation, the core schema documentation and IPTC's own tennis example. It is our reading. IPTC has not reviewed it.

Our own comparison of tennis score notation formats sets SportsML beside three other formats.

How does each Score field map to SportsML?

The rows follow the Score schema in the spec, every field in its order. Each SportsML name links to the section of IPTC's documentation that defines it.

Each Score field and the SportsML 3.1 element or attribute it maps to
Score fieldSportsML 3.1Notes
setsplayer-stats/@scoreSets won. Each player gets the value from their slot of the array. IPTC's Davis Cup example puts sets won in this attribute.
gamesstats-tennis-set/@score
stats-tennis-set/@set-number
sub-score/@score
One stats-tennis-set per set and player. IPTC's example also writes the same numbers as sub-score. SportsML has no match tie-break, so the fixtures write one as a set won 1-0, with its points in score-tiebreaker.
pointsaction/@server-score
action/@receiver-score
event-metadata-tennis/@server-score
event-metadata-tennis/@receiver-score
On an action and on event-metadata-tennis the game score is ordered by server, and ours by player. 0 becomes love and AD becomes ad. The fixtures write 40-40 as 40 and 40, though the list also has deuce. A tie-break count has no code, so tie-break points carry no game score.
serverevent-metadata-tennis/@server-idref
event-metadata-tennis/@receiver-idref
participant/@role
server-idref exists only on event-metadata-tennis. On an action the server is a participant with a role. IPTC publishes no tennis role codes, so the fixtures use ltapirole:server. A null server leaves the attribute out.
is_tiebreakNo direct equivalentNo attribute says the current game is a tie-break. score-tiebreaker gives a set's tie-break points, but not whether the breaker is still being played.
win_probability_p1No direct equivalentA model output. SportsML has no field for it. wagering-odds holds a bookmaker's line, and the generic stat element would need a code of our own.
dangerNo direct equivalentThe value the break_point frame calls prob_swing.
win_probability_p1_modelNo direct equivalentThe same model read without the market-prior anchor.
win_probability_metaNo direct equivalentThe model version and the time the two probabilities were made.
timestampNo direct equivalentOur clock, refreshed while a source keeps sending the same state. action/@date-time is when the play took place on court, which this field never claims. last-modified is closest, but a state sent again is not a change to the record.
accepted_ataction/@createdThe instant we accepted the state, stamped once. IPTC describes created as the time the action record was made.
sequenceaction/@sequence-numberOur per-match accept counter. In the fixtures, the action for a point carries the sequence of the state that point produced.
age_secondsNo direct equivalentSeconds since the score last changed.
staleNo direct equivalentOur staleness verdict on a live match.
observed_age_secondsNo direct equivalentSeconds since any source last confirmed the state.
sources_countNo direct equivalentHow many sources reported the match in the last 60 seconds.
changing_sources_countNo direct equivalentHow many sources changed the score in the last 300 seconds.
corroboratedNo direct equivalentWhether a second source sent this exact state.
corroborated_age_secondsNo direct equivalentSeconds since that second source confirmed it.
detailNo direct equivalentWhy something is withheld, for example a null games array.
verdictNo direct equivalentWhy a read is not the newest state we judged, for example a withdrawn state.

Read the arrays the usual way. sets, games and points put player 1 first and player 2 second.

Which match and point fields does SportsML cover?

A SportsML match document also says who played, how the match ended and what happened on each point. These fields come from the Match, LivePoint and HistoryTapeRow schemas.

Match and point fields the fixtures also map
FieldSportsML 3.1Notes
Match.playersplayer
player-metadata/name
The fixtures give the two players the ids p1 and p2.
Match.formatevent-metadata-tennis/@number-of-setsBO3 is 3 and BO5 is 5.
Match.statusevent-metadata/@event-statusThe codes come from speventstatus. An upcoming match is pre-event, live is mid-event and cancelled is canceled. A completed match is post-event unless its outcome says otherwise.
Match.outcomeevent-metadata/@event-status
event-metadata/@event-status-reason
event-metadata/@event-status-note
event-metadata/@event-outcome-type
IPTC has no code for a retirement or a default. The fixtures mark retired, walkover and default as forfeited and add the reason withdrawal to the first two. A default also gets the outcome type authority-decision. The note holds our outcome value. The fixtures do not cover abandoned or unresolved.
Match.winnerplayer-stats/@event-outcomespeventoutcome win for the winner, loss for the other player.
Match.withdrewNo direct equivalentThe fixtures show it only through the loser's loss and the note.
LivePoint.winnerparticipant/@roleThe point winner is a participant too. IPTC's Davis Cup example uses a vendor code, ball-winner. The fixtures use ltapirole:point-winner.
LivePoint.setaction/@set
event-metadata-tennis/@set
The set the point was played in.
LivePoint.gameaction/@game
event-metadata-tennis/@game
13 is the game number of a tie-break at six all. The fixtures count a match tie-break as game 1.
LivePoint.serveaction/@serve-number
event-metadata-tennis/@serve-number
It takes first or second on event-metadata-tennis. On an action it takes a code, and IPTC publishes no list for it. The fixtures leave it out.
HistoryTapeRow.tiebreak_finalstats-tennis-set/@score-tiebreakerThe breaker's closing score, on the row that closes a tie-break set.
Court time of a pointaction/@date-timeWe publish no court time. LivePoint.ts is when our pipeline committed the state.

Worked example: a match decided by a match tie-break

Player A and Player B are synthetic. They split the first two sets 6-4 and 4-6. A ten-point match tie-break replaces the third set and Player A wins it 10-8.

These are the last two score states, at 9-8 in the breaker and after the match point. The deciding set's slot holds the breaker's points while it is played. The last state shows the match over.

[
  {"sets": [1, 1], "games": [[6, 4, 9], [4, 6, 8]], "points": ["9", "8"], "server": 1, "is_tiebreak": true, "timestamp": "2026-01-05T10:11:20Z", "accepted_at": "2026-01-05T10:11:20Z", "sequence": 318},
  {"sets": [2, 1], "games": [[6, 4, 10], [4, 6, 8]], "points": ["0", "0"], "server": null, "is_tiebreak": false, "timestamp": "2026-01-05T10:12:00Z", "accepted_at": "2026-01-05T10:12:00Z", "sequence": 319}
]

The same match as a SportsML document. The third set is written as a set won 1-0, with the breaker's points in score-tiebreaker. The action is the match point.

<?xml version="1.0" encoding="UTF-8"?>
<!-- SYNTHETIC tennis scoring fixture. No real players, matches or results.
     Fixture: 02-match-tiebreak. Licence: CC BY 4.0, https://creativecommons.org/licenses/by/4.0/
     From the Live Tennis API SportsML fixtures, https://github.com/livetennisapi/openapi/tree/main/examples/sportsml -->
<sports-content xmlns="http://iptc.org/std/nar/2006-10-01/">
  <sports-metadata doc-id="ltapi-synthetic-02-match-tiebreak" date-time="2026-01-05T10:12:00Z" language="en">
    <catalogRef href="http://www.iptc.org/std/catalog/catalog.IPTC-Sports_1.xml"/>
    <sports-title>Synthetic fixture: match tie-break to ten</sports-title>
  </sports-metadata>
  <sports-event>
    <event-metadata event-status="speventstatus:post-event">
      <event-metadata-tennis number-of-sets="3"/>
    </event-metadata>
    <player id="p1">
      <player-metadata><name>Player A (synthetic)</name></player-metadata>
      <player-stats score="2" event-outcome="speventoutcome:win">
        <player-stats-tennis>
          <stats-tennis-set set-number="1" score="6"/>
          <stats-tennis-set set-number="2" score="4"/>
          <stats-tennis-set set-number="3" score="1" score-tiebreaker="10"/>
        </player-stats-tennis>
      </player-stats>
    </player>
    <player id="p2">
      <player-metadata><name>Player B (synthetic)</name></player-metadata>
      <player-stats score="1" event-outcome="speventoutcome:loss">
        <player-stats-tennis>
          <stats-tennis-set set-number="1" score="4"/>
          <stats-tennis-set set-number="2" score="6"/>
          <stats-tennis-set set-number="3" score="0" score-tiebreaker="8"/>
        </player-stats-tennis>
      </player-stats>
    </player>
    <actions>
      <!-- 17 earlier points, one action each, are in the fixture file -->
      <action type="sptenaction:point" sequence-number="319" created="2026-01-05T10:12:00Z" set="3" game="1">
        <participant idref="p1" role="ltapirole:server"/>
        <participant idref="p2" role="ltapirole:receiver"/>
        <participant idref="p1" role="ltapirole:point-winner"/>
      </action>
    </actions>
  </sports-event>
</sports-content>

The Score schema says a finished match tie-break is often published as a one-game set, 1-0. The fixture keeps the breaker's points in that slot instead. Take the winner from sets either way.

Test fixtures for tennis scoring edge cases

The examples/sportsml folder holds six synthetic matches. No player, match or result in them is real. Each fixture is two files. One is the sequence of score states as JSON. The other is the same match as a SportsML document. The fixtures are under CC BY 4.0.

The six synthetic fixtures and what each covers
FixtureWhat it coversStatesFiles
Deciding-set tie-break at six allThe third set reaches 6-6 and a seven-point tie-break decides it, 9-7.17JSON SportsML
Match tie-break to tenA ten-point match tie-break replaces the third set and ends 10-8.19JSON SportsML
No-ad gamesTwo games reach 40-40. One deciding point is a break and the other wins the match.15JSON SportsML
RetirementPlayer B retires serving at 15-30 in the second set.4JSON SportsML
WalkoverPlayer A withdraws before a ball is struck, so the fixture has no score states.0JSON SportsML
DefaultPlayer A is defaulted while serving at advantage Player B, after deuce, in the second set.8JSON SportsML

The folder's check script validates every SportsML document against the IPTC schema. It replays each point from the first JSON state with the rules of tennis and compares every state. It also compares the result and the way the match ended.

pip install lxml
python examples/sportsml/check_fixtures.py

The IPTC schema files are vendored unchanged, with their CC BY 4.0 notice and source address. The script refuses to run if one differs from its pinned SHA-256.

Where does SportsML 3.1 leave tennis open?

Writing the fixtures needed a choice in each of these places. Each one is in the published files.