Tennis point-by-point data API
Point-by-point tennis data is the ordered sequence of score states we observed or reconstructed for a match. Each row carries the sets, the games, the running game score and the server. Coverage is declared per match, and most tapes start mid-match. With Live Tennis API, the completed-match tape is available on the Basic tier via GET /history/matches/{id}. Live per-point events as a match unfolds require the Ultra tier (GET /matches/{id}/points plus the WS /ws stream). This guide shows both, with runnable code.
All requests use the base URL https://api.livetennisapi.com/api/public/v1 and authenticate with an X-API-Key header. Coverage spans ATP, WTA, Challenger and ITF. Grab a free key (no card) at livetennisapi.com/subscribe/free to explore live scores first, then upgrade when you need the tape.
What "point-by-point" means here
A point-by-point record is the ordered sequence of points inside a match. For each point the record carries:
- Who served, as
server(1 or 2, null when not known) - The game score after the point, as
points(e.g.["15","0"],["40","AD"]) - The set and game context, as
setsandgames - Who won the point, as
winner, on thesequence=cleanandpoints=completereads
The tape carries no break-point flag. You derive break points from the rows with the standard rule. The receiver is at advantage, or the receiver holds 40 against a server on 0/15/30. The rule does not apply in tiebreaks, or when the server or point fields are null.
The tier split (read this honestly)
There are two distinct things people mean by "point-by-point data", and they sit on different tiers:
| What you want | Endpoint | Tier |
|---|---|---|
| The point tape of a completed match | GET /history/matches/{id} |
Basic ($9.99/mo) |
| Live per-point events as the match happens | GET /matches/{id}/points + WS /ws |
Ultra ($99.99/mo) |
| Match analysis / win-probability per point | GET /matches/{id}/analysis |
Ultra |
The Free tier does not include the tape. It covers the current state of play only (live matches and current scores). If you only need the live scoreline (not every point), see the tennis scores API guide, which works on the free key.
Getting a completed-match tape (Basic)
First find a match id. Completed matches are listed by GET /history/matches.
Here we assume you already have an id. Then pull its tape:
curl -s "https://api.livetennisapi.com/api/public/v1/history/matches/MATCH_ID" \
-H "X-API-Key: $LIVE_TENNIS_API_KEY"
The response holds the match, the ordered tape and a meta block that states the coverage. Two rows look like this (trimmed, and some fields are null on some matches):
{
"match": { "id": 12345, "status": "completed" },
"tape": [
{
"sets": [0, 0],
"games": [[1], [0]],
"points": ["15", "0"],
"server": 2,
"is_tiebreak": false,
"origin": "observed",
"timestamp": "2026-10-31T14:02:11Z"
},
{
"sets": [0, 0],
"games": [[1], [1]],
"points": ["30", "40"],
"server": 1,
"is_tiebreak": false,
"origin": "observed",
"timestamp": "2026-10-31T14:07:40Z"
}
],
"meta": { "rows": 195, "coverage": "from_start", "point_source": "observed" }
}
Python
import os, requests
BASE = "https://api.livetennisapi.com/api/public/v1"
headers = {"X-API-Key": os.environ["LIVE_TENNIS_API_KEY"]}
r = requests.get(f"{BASE}/history/matches/MATCH_ID", headers=headers, timeout=10)
r.raise_for_status()
data = r.json()
print(data["meta"]["coverage"], data["meta"]["rows"], "rows")
for row in data["tape"]:
p1, p2 = row["points"]
print(f"sets {row['sets']} games {row['games']} "
f"points {p1}-{p2} server {row['server']}")
An official Python SDK (pip install livetennisapi) wraps the same endpoint.
JavaScript / TypeScript
const BASE = "https://api.livetennisapi.com/api/public/v1";
const headers = { "X-API-Key": process.env.LIVE_TENNIS_API_KEY };
const res = await fetch(`${BASE}/history/matches/MATCH_ID`, { headers });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data.meta.coverage, data.meta.rows, "rows");
for (const row of data.tape) {
const [p1, p2] = row.points;
console.log(
`sets ${row.sets} games ${JSON.stringify(row.games)} ` +
`points ${p1}-${p2} server ${row.server}`
);
}
An official JavaScript SDK (npm i livetennisapi) wraps the same endpoint.
Reconstructing break points yourself
The tape has no break-point flag, so you apply the rule to each row. It only holds outside tiebreaks and when the server and score are known:
def is_break_point(server, receiver_score, server_score, in_tiebreak):
if in_tiebreak:
return False
if receiver_score is None or server_score is None:
return False
if receiver_score == "AD":
return True
return receiver_score == "40" and server_score in ("0", "15", "30")
Feed it the receiver's and the server's entries of points, picked by server, and is_tiebreak from the same row.
Live per-point events (Ultra)
For a match in progress, Ultra includes per-point events as they happen. You can poll GET /matches/{id}/points on a live match. The efficient path is the WebSocket stream at WS /ws, which pushes updates instead of making you poll. The subscribe and message shapes below are illustrative. See the docs for the exact schema:
import asyncio, json, websockets
async def stream_points(match_id, api_key):
url = "wss://api.livetennisapi.com/api/public/v1/ws"
async with websockets.connect(url, extra_headers={"X-API-Key": api_key}) as ws:
await ws.send(json.dumps({"subscribe": "match", "id": match_id}))
async for raw in ws:
msg = json.loads(raw)
if msg.get("type") == "point":
print(msg["server"], "->", msg["point_winner"], msg.get("score"))
asyncio.run(stream_points("MATCH_ID", "YOUR_API_KEY"))
Ultra also adds GET /matches/{id}/analysis for per-point win-probability and analysis on top of the raw points.
Tips
- Start on the free key to learn the live-match and score endpoints, then add Basic for the completed tape.
- The tape is per completed match. Iterate over your fixtures/results to backfill history.
- Fields can be null early in a point stream. Guard for missing
server/scorebefore deriving break points. - See the pillar developer guide for the full endpoint map, and the stats & player database guide for rankings and Elo.
Full reference and the OpenAPI spec live at docs.livetennisapi.com. An MCP server is available at mcp.livetennisapi.com.