TennisDatum

Tennis API / Python guide

Use a Tennis Data API with Python

Retrieve structured tennis match results for analysis, research and prediction-model experiments. This guide uses the TennisDatum REST API and keeps your API key on your own server.

Start with match records and a private API key

Choose Live monthly for current scores and match status, or Complete quarterly for Live and Historical access. Historical is also a one-off add-on to an active monthly subscription. After payment, we verify your subscription and email API access details and getting-started instructions to your checkout email.

Set TENNISDATUM_API_KEY in your server environment. Do not commit it to Git, embed it in frontend JavaScript, or put it in query parameters. Install the Python requests package in your project environment.

python -m pip install requests

Retrieve tennis results as JSON

This example requests up to 25 finished match observations. Historical access is required for your subscription. A timeout prevents a stalled request from blocking your application indefinitely. HTTP errors are raised before the response is processed.

import os
import requests

response = requests.get(
    "https://api.tennisdatum.com/v1/tennis/matches",
    headers={"Authorization": f"Bearer {os.environ['TENNISDATUM_API_KEY']}"},
    params={"status": "finished", "limit": 25, "offset": 0},
    timeout=20,
)
response.raise_for_status()
payload = response.json()

for match in payload["data"]:
    print(match["id"], match["players"], match["score"])

The response includes data, total, limit and offset. Request the next page by increasing the offset by the page limit. Stop when an empty page is returned or the next offset reaches the total. Avoid repeatedly downloading records you have already stored.

Request match statistics and recorded point histories

Use the returned match ID to request /v1/tennis/matches/{id}/statistics or /v1/tennis/matches/{id}/points. The JSON shapes are documented in the OpenAPI specification. A recorded score history is different from the generated replay on the homepage; inspect the endpoint response before building your parser.

Store the API match ID with each row. Preserve competitor order when mapping side-specific statistics. Keep missing values distinct from zero and retain observation timestamps with each saved record. The coverage page lists published tours and dates; the data definitions explain identity and freshness fields.

Prepare data for a tennis prediction model

Start with a clear prediction time: before the match, before a set, or during play. Build features only from information available before that time. Final scores and full-match statistics belong in evaluation labels when predicting the match outcome, rather than in pre-match features.

Train on earlier matches and evaluate on later matches. Compare against a simple baseline before introducing more complex AI models. Measure probability calibration as well as classification accuracy. Separate records by their actual identities before training so overlapping observations do not appear on both sides of a train/test split.

If you add market data, the optional bundle covers Betfair, Matchbook and BETDAQ together. Align prices to the prediction time, preserve the exchange identity, and account for commission and available liquidity in your own tests. Model performance does not establish a future financial return.

Handle errors and keep integration reliable

A 401 response means the key is missing or invalid. A 429 response means the request quota is exhausted: inspect the rate-limit headers and wait rather than retrying in a tight loop. For temporary 503 responses, use a bounded retry with increasing delay. Check observation timestamps before treating a score as current.

Keep your server between the customer API and your application. Your frontend should receive only the data it needs. Read authentication and endpoint documentation, explore historical tennis data, or compare subscription plans.