One flat object for on-air graphics (ULTRA)

Added 2026-09-24, from a broadcaster's request. ONE flat JSON object for one match, built so a graphics template can bind each field to a fixed path.

Three properties make it different from GET /matches/{matchId}, and each exists because a graphics pipeline breaks without it. The object is FLAT — no nested score object, no arrays of arrays. Every key is PRESENT on every read: a value we do not hold is null, never missing, because a missing key breaks a template binding. And the score is already in DISPLAY form — p1_points reads "40" or "AD", set_line is one string such as "5-7 2-0", and each set has its own column — so nothing has to be formatted downstream.

It is a PROJECTION of what the public API already publishes: the match object, its embedded score and the model probability, plus the break-, set- and match-point flags derived by the same classifiers the scoring pipeline uses. Nothing here is a new fact and nothing is guessed.

BUILT FOR 1 Hz. Every response carries a strong ETag and Cache-Control: no-cache, max-age=1; send If-None-Match and an unchanged state costs a 304 with no body. ULTRA's burst window is 600 requests a minute, so ten single-match pollers at 1 Hz fit on one key. Detect a new state on sequence, not on served_at, which changes on every read.

The key may be sent as Authorization: Bearer <key>, as X-API-Key, or as ?token=<key> for tools that cannot set a header.

get/broadcast/match/{matchId}

Request

  • Base URL: https://api.livetennisapi.com/api/public/v1
  • URL: https://api.livetennisapi.com/api/public/v1/broadcast/match/{matchId}
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Path parameters

matchIdinteger required

The match id. Every match route shares ONE id space, so the same value works everywhere matchId appears.

Get it from any match list, where it is the id field of each match object: GET /matches?status=live (in progress), GET /matches?status=upcoming or GET /fixtures (scheduled), GET /matches?status=completed or GET /history/matches (finished).

Ids are stable for the life of a match, so one captured before it starts still resolves after it finishes.

Response

The broadcast object for this match

match_idinteger
statusstring

live, completed, upcoming

event_statusstring nullable

The terminal badge where one is stated (Finished, Retired, Walk Over, Interrupted); null on a normal live row.

outcomestring nullable
winnerinteger nullable

1 or 2, null until a result is established.

tourstring nullable
tournamentstring nullable
roundstring nullable
surfacestring nullable
best_ofinteger nullable
is_doublesboolean
p1_idinteger nullable
p1_namestring nullable
p1_shortstring nullable

Display short form, "J. Sinner". A doubles team keeps each side's last token.

p1_countrystring nullable

Three-letter code.

p1_rankinginteger nullable
p2_idinteger nullable
p2_namestring nullable
p2_shortstring nullable
p2_countrystring nullable
p2_rankinginteger nullable
p1_setsinteger nullable
p2_setsinteger nullable
p1_gamesinteger nullable

Games in the set in play.

p2_gamesinteger nullable
p1_pointsstring nullable

As printed: "0", "15", "30", "40", "AD", or the tiebreak count.

p2_pointsstring nullable
p1_set1integer nullable

Per-set columns. A set not yet played is null on both sides.

p2_set1integer nullable
p1_set2integer nullable
p2_set2integer nullable
p1_set3integer nullable
p2_set3integer nullable
p1_set4integer nullable
p2_set4integer nullable
p1_set5integer nullable
p2_set5integer nullable
set_linestring nullable

The completed and in-play sets as one string, "5-7 2-0".

current_setinteger nullable
is_tiebreakboolean
match_tiebreakboolean

True while a deciding match tiebreak is in play.

serverinteger nullable

1 or 2.

p1_servingboolean nullable
p2_servingboolean nullable
break_point_forinteger nullable

1, 2 or null. Cue an animation on the transition to non-null.

set_point_forinteger nullable
match_point_forinteger nullable
p1_win_pctinteger nullable

The model probability as a whole percent. Null where no model figure was computed for this state — never guessed.

p2_win_pctinteger nullable
sequenceinteger nullable

The per-match accept counter. THIS is how a poller detects a new state.

updated_atstring date-time nullable
age_secondsinteger nullable

Seconds since the score CONTENT last changed.

staleboolean nullable

A live match whose content has frozen past the threshold.

served_atstring date-time

When this response was built. Changes on every read — do not use it to detect a new state.

Changes

No recorded changes to this operation across all 1 revision of this API.