# 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)
- Players, rankings and season stats; fixtures and completed results
- Match-winner market prices (bid / ask / mid, with history)
- AI win-probability: favored side, confidence, and key factors
- WebSocket live score stream

## Plans (billed monthly, USD)
- Basic — $9.99: live scores, players, fixtures, history (60 req/min, 10k/day)
- Pro — $29.99: adds match events and market prices (300 req/min, 100k/day)
- Ultra — $99.99: adds AI win-probability and the WebSocket feed (600 req/min, 500k/day)

## 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://github.com/livetennisapi/livetennisapi-python)
- JavaScript / TypeScript: `npm install livetennisapi` — [npm](https://www.npmjs.com/package/livetennisapi)
  Source: [livetennisapi-js](https://github.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 12 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 GitHub](https://github.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`

## 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://github.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.

## Contact
hello@livetennisapi.com