langchain-livetennis

Official LangChain integration for the Live Tennis API.

Give an agent real tennis: live scores, match detail, player profiles, upcoming fixtures, head-to-head records, rankings, in-play statistics and a 1968–2022 results archive — across ATP, WTA, Challenger, ITF and juniors.

Installation

pip install -U langchain-livetennis

Credentials

Get a free key (100 requests/day) at https://livetennisapi.com/subscribe/free, then:

export LIVETENNISAPI_KEY="twjp_..."

A request without a key is answered with HTTP 401 {"error": "unauthorized"}.

Quickstart

from langchain_livetennis import LiveTennisToolkit

toolkit = LiveTennisToolkit()
tools = toolkit.get_tools()

matches = tools[0].invoke({"status": "live", "tour": "atp", "limit": 5})
print(matches)

Or use a single tool on its own:

from langchain_livetennis import LiveTennisScoreTool

LiveTennisScoreTool().invoke({"match_id": 18953})

In an agent

from langchain.agents import create_agent
from langchain_livetennis import LiveTennisToolkit

agent = create_agent(model="claude-sonnet-4-6", tools=LiveTennisToolkit().get_tools())

agent.invoke(
    {"messages": [{"role": "user", "content": "Who is leading the live ATP matches right now?"}]}
)

Tools

Every tool returns the API's JSON payload as a string, so nothing is lost on the way to the model. Tools above the key's plan still bind and appear in get_tools(); calling one surfaces the API's 403 as a ToolException naming the plan that unlocks it, so an agent can explain the gate instead of retrying it.

tour accepts atp, wta, challenger, itf or juniors. Each value covers that tour's singles and doubles draws, and juniors covers the boys' and girls' Grand Slam draws. An unrecognised value is a 400 rather than a silent pass-through, so a caller never receives a tour it did not ask for.

Plans & quotas

On a free key (100/day), poll no faster than every 15 minutes; for an always-on dashboard, BASIC is recommended. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and 429s a Retry-After.

Authentication

The API accepts, in order of preference:

• Authorization: Bearer twjp_... — preferred for direct HTTP calls
• X-API-Key: twjp_... — what this package sends
• ?token=twjp_... — for header-less contexts (e.g. WebSockets)

This package reads the key from the LIVETENNISAPI_KEY environment variable, or takes it explicitly via LiveTennisToolkit(api_key=...).

Errors

All inherit from LiveTennisAPIError (LiveTennisAbuseThrottled also from LiveTennisRateLimited). Inside a tool call they are re-raised as LangChain's ToolException, so an agent can be configured to recover:

from langchain_livetennis import LiveTennisMatchesTool

tool = LiveTennisMatchesTool(handle_tool_error=True)

Requests retry automatically on per-minute 429s and 5xx only, honouring Retry-After with exponential backoff and jitter. A 401 or 403 is never retried — a bad key or an unentitled plan cannot start working, and retrying only burns the rate limit. Nor are a daily-cap 429 or the abuse block — waiting a few seconds cannot fix either, so they surface immediately with .resets_at / .retry_at_epoch.

Configuration

from langchain_livetennis import LiveTennisClient, LiveTennisToolkit

toolkit = LiveTennisToolkit(api_key="...")

# Or share a fully configured client across every tool:
client = LiveTennisClient(api_key="...", timeout=10.0, max_retries=3)
toolkit = LiveTennisToolkit(client=client)

Development

uv sync --all-groups
uv run pytest tests/unit_tests
uv run ruff check .
uv run ruff format --check .
uv run mypy langchain_livetennis

The unit suite runs entirely against an in-process fake API (tests/mock_api.py) — no key and no network access required. The integration tests under tests/integration_tests/ skip themselves unless LIVETENNISAPI_KEY is set.

Links

• Live Tennis API documentation
• Get a free API key
• Discord
• GitHub org
• Official Python client — the standalone SDK, for use outside LangChain
• OpenAPI specification

Affiliate program

Know developers who need tennis data? The affiliate program pays 51% recurring commission for the life of every referred subscription — 30-day cookie, and the people you refer get 10% off.

License

MIT