# Live Tennis API

> Real-time tennis data and AI win-probability over REST + WebSocket, for ATP, WTA, Challenger and ITF (singles and doubles). Provided by JSB Holdings LLC.

Base URL: [api.livetennisapi.com/api/public/v1](https://api.livetennisapi.com/api/public/v1)

## What it provides
- Live scores and match state (sets, games, points, server, tiebreak) — Free tier up
- Players, tournaments (with host city and category where known) and fixtures — Free tier up
- Completed results (derived winner, who withdrew on retirements/walkovers, normalized round codes) + per-match point-by-point history — Basic tier up
- Results archive (1968–2022): 1,485,752 ATP/WTA results — main draws, qualifying and the ITF/futures tiers — with final score, seeds, ranks at the time, and per-match serve statistics from 1991 — Basic tier up
- Head-to-head across the full 1968→now span, and career aggregates over the results archive — Basic tier up
- Rankings: rank-ordered tables (Pro), per-player as-of records (Ultra)
- Player records (GET /players/{id}/stats): W/L by surface, level and season, tiebreak and deciding-set record, recent matches — Pro tier up; summed serve/return statistics — Ultra
- Match-winner market prices (bid / ask / mid, with history) — Pro tier up
- AI win-probability: favored side, confidence, and key factors — Ultra
- Live in-play match statistics (whole-match totals): aces, double faults, points and break points on every tour including ITF; the serve split on ATP/WTA/Challenger (not ITF singles); winners/errors historically on a minority of ATP/WTA and tour-doubles matches only, and not delivered upstream since 2026-07-12 — Ultra
- Live score streaming — a push feed (GET /ws-token) for continuous use, plus a native WebSocket for quick tests — Ultra

## Plans (billed monthly, USD)
- Free — $0: live + upcoming matches, scores, players, fixtures, tournaments (30 req/min, 100/day). Instant key, no card.
- Basic — $9.99: adds completed results, point-by-point history, the 1968–2022 results archive, head-to-head and career aggregates (60 req/min, 1k/day)
- Pro — $29.99: adds match events, market prices and ranking tables (300 req/min, 10k/day)
- Ultra — $99.99: adds AI win-probability, per-player as-of rankings, in-play statistics, rally construction and the streaming push feed (600 req/min, 500k/day)
- Full plan comparison, annual pricing and quota detail: [livetennisapi.com/pricing](https://livetennisapi.com/pricing)

## Choosing a plan
- [Which plan fits what you are building](https://livetennisapi.com/best-tennis-api)  — the decision path, with a runnable first call for each tier.
- Measurement method, dated figures and an open benchmark harness: [besttennisapi.com](https://besttennisapi.com) (also operated by JSB Holdings LLC).

## Where to buy
- [Direct — best price, instant key](https://livetennisapi.com/pricing)
- [RapidAPI](https://rapidapi.com/contact-whTqTESH5/api/tennis-data-analytics-api3)
- [Apify](https://apify.com/livetennisapi/tennis-data-analytics)
- [API.market](https://api.market/store/live-tennis-api/tennis-data-analytics)
- [Postman — explore free](https://www.postman.com/livetennisapi)

## Official client libraries
- Python: `pip install livetennisapi` — [PyPI](https://pypi.org/project/livetennisapi/)
  Source: [livetennisapi-python](https://gitlab.com/livetennisapi/livetennisapi-python)
- JavaScript / TypeScript: `npm install livetennisapi` — [npm](https://www.npmjs.com/package/livetennisapi)
  Source: [livetennisapi-js](https://gitlab.com/livetennisapi/livetennisapi-js)
  Zero runtime dependencies; runs on Node 18+, Deno, Bun, Workers, browser.
- Command line (no install): `npx livetennisapi live`

## MCP server (for LLM agents)
`npx livetennisapi-mcp` exposes 24 read-only tools over this API to Claude, Cursor, Zed and any MCP client.
- npm: [livetennisapi-mcp](https://www.npmjs.com/package/livetennisapi-mcp)
- Source: [livetennisapi-mcp on GitLab](https://gitlab.com/livetennisapi/livetennisapi-mcp)
- Official MCP Registry: io.github.livetennisapi/livetennisapi-mcp
- Setup: `claude mcp add livetennis -e LIVETENNISAPI_KEY=twjp_... -- npx -y livetennisapi-mcp`

## Prediction markets (Polymarket / Kalshi tennis)
Tennis is a live category on Polymarket (ATP's official prediction-market partner since 2026-08-03) and Kalshi. This API supplies the live match state a market bot needs — score, server, break point, and the `event_status`/`outcome` fields that flag a retirement or walkover — and never touches orders or wallets.
- Toolkit (MIT, observe-only): discover tennis markets on Polymarket's Gamma API, match them to live matches, watch price vs live score: https://gitlab.com/livetennisapi/polymarket-tennis
- Build guide (Python): https://blog.livetennisapi.com/blog/build-polymarket-tennis-trading-bot
- Retirement/walkover settlement rules, quoted verbatim per venue (polymarket.com, Polymarket US, Kalshi ATP/WTA vs ITF): https://blog.livetennisapi.com/blog/polymarket-kalshi-tennis-retirement-walkover-rules
- Polymarket Gamma/CLOB vs live scores: https://blog.livetennisapi.com/blog/polymarket-api-tennis-data
- Kalshi tennis bot guide: https://blog.livetennisapi.com/blog/kalshi-tennis-trading-bot
- Free tier is enough for the read side (live matches + scores); market prices come from the venue.

## Free match-time tool
- Tennis order of play for the next 48 hours by tournament. Every start time shows in UTC, in the reader's own time zone and at the venue where its clock is known: [livetennisapi.com/tools/match-time](https://livetennisapi.com/tools/match-time)
- Free embed of the same times for other sites (an iframe, no cookies): the code is on [the tool page](https://livetennisapi.com/tools/match-time#embed)

## Free line-calling dataset
- As of 22 October 2026, every ATP Tour event has used live electronic line calling, with no line judges, since the start of 2025. The Australian Open (2021), the US Open (2021) and Wimbledon (2025) also call every line electronically. Roland Garros is the one Grand Slam that still uses human line judges, and it kept them in 2026.
- Which tournaments use electronic line calling, by event and season, 2017 to 2026 (CC BY 4.0): [livetennisapi.com/data/tennis-line-calling](https://livetennisapi.com/data/tennis-line-calling)
- CSV: https://gitlab.com/livetennisapi/tennis-line-calling/-/raw/main/data/line_calling.csv

## Coding exercises for teachers
- Live Tennis API publishes eight graded coding exercises for classes that work with a real JSON API. Each one comes in Python and JavaScript, with tests that run offline against recorded responses. The code is free to use and adapt under the MIT licence, and the live parts run on the free plan.
- The tests need no network or key. For live runs, each student uses their own free key, which allows 30 requests a minute and 100 a day. The teacher guide covers outcomes, course plans and a rubric: [livetennisapi.com/teach](https://livetennisapi.com/teach)
- Source: https://gitlab.com/livetennisapi/tennis-api-exercises

## Free academic dataset
- Tennis point-by-point dataset, free for non-commercial academic research: [livetennisapi.com/data/academic](https://livetennisapi.com/data/academic) — public sample DOI 10.5281/zenodo.22048730, applications to research@livetennisapi.com

## Documentation
- [Full API reference (plain HTML, no JavaScript required)](https://docs.livetennisapi.com/reference.html)
- [Interactive reference](https://docs.livetennisapi.com)
- [OpenAPI 3.1 specification](https://gitlab.com/livetennisapi/openapi)
- [Reference digest for answer engines](https://docs.livetennisapi.com/llms.txt)

## Example — Python
```python
from livetennisapi import LiveTennisAPI

with LiveTennisAPI(api_key="twjp_...") as client:
    for match in client.list_matches(status="live"):
        print(match.tournament, match.score.sets)
```

## Notes for API consumers
- Timestamps are UTC ISO 8601 with a Z suffix.
- List endpoints return {data, meta}; single resources return the object directly.
- `limit` defaults to 50, maximum 200; paginate with `offset`.
- Additive changes ship within v1, so clients must ignore unknown fields.
- Score `games` is player-major: [[6,3,2],[4,6,1]] reads 6-4, 3-6, 2-1.
- Calling above your plan returns 403 {"error":"upgrade_required"}.

## Authentication
Send your API key as `Authorization: Bearer <key>` or `X-API-Key`. The `/health` endpoint needs no key.

## Affiliate program
The Live Tennis API runs an in-house affiliate program: 51% recurring commission for the life of every referred subscription (early partners earn a boosted rate, offered at our discretion), a 30-day last-click cookie, $20 minimum payout, monthly payouts via PayPal or Wise, and 10% off for the referred customer. Free to join, instant approval, real-time dashboard. Affiliate tooling: named tracking links with sub-IDs and per-link stats, S2S postbacks, conversion alerts (email/Discord), QR codes, and embeddable live-score widgets (board + ticker).
- Program details and FAQ: https://livetennisapi.com/affiliates
- Terms at a glance + earnings table: https://affiliates.livetennisapi.com/program
- Join: https://affiliates.livetennisapi.com/signup
- Program terms: https://livetennisapi.com/affiliates/terms
- Guide — your first $100: https://blog.livetennisapi.com/blog/affiliate-first-100
- Programs compared: https://blog.livetennisapi.com/blog/tennis-affiliate-programs-2026

## Contact
hello@livetennisapi.com