API Basics
This page covers the technical foundations of the Tennis API: authentication, URL structure, response formats, pagination, error handling, and the companion resources available for your integration.
Authentication
Every request is authenticated with your API key, sent in the x-api-key request header:
GET https://api.sportradar.com/tennis/{access_level}/v3/{language_code}/competitions.{format}
x-api-key: {your_api_key}A request with a missing or invalid key returns HTTP 403 with an HTML body rather than a JSON error object, so branch on the status code:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Authentication Error</title>
</head>
<body>
<p>Authentication Error</p>
</body>
</html>If you receive HTTP 429, you have exceeded your request quota: slow your request rate and retry, increasing the wait between attempts. See the full Response Codes reference for other statuses.
Base URL and Path Structure
All Tennis API feeds share one base URL and path shape:
https://api.sportradar.com/tennis/{access_level}/v3/{language_code}/{feed}.{format}access_levelistrialorproduction, matching your key.v3is the current API version.language_codeis a supported 2-letter code (see Supported Languages below).formatisjsonorxml. Every feed serves both.
The Tennis Probabilities API uses the same shape on its own base URL: https://api.sportradar.com/tennis-probabilities/{access_level}/v3/{language_code}/....
Tennis API Map
Most integrations follow the same paths through the API. Use the map below to orient yourself: each pill is an endpoint, colored by the identifier it takes, and each box is a common task. Click any endpoint to open its reference page.
Understanding Competitions and Seasons
The Two Core Containers
- A Competition is a professional tournament or tour event, such as the Australian Open, Wimbledon, or an ATP 1000. Singles, doubles, and mixed draws are separate competitions, each with its own
competition_id.- A Season is one edition of a competition (for example, Wimbledon Men Singles 2026). Each season has its own
season_idand contains all matches, competitors, and results for that edition.
A typical discovery walk starts at Competitions, narrows to one competition's editions with Competition Seasons, and then pulls season-scoped feeds with the season_id:
{
"generated_at": "2026-07-27T21:50:48+00:00",
"competitions": [
{
"id": "sr:competition:620",
"name": "Hopman Cup",
"type": "mixed",
"gender": "mixed",
"category": {
"id": "sr:category:181",
"name": "Hopman Cup"
}
},
{
"id": "sr:competition:660",
"name": "World Team Cup",
"type": "mixed",
"gender": "men",
"category": {
"id": "sr:category:3",
"name": "ATP"
},
"level": "atp_250"
},
{
"id": "sr:competition:2555",
"name": "Wimbledon Men Singles",
"parent_id": "sr:competition:2553",
"type": "singles",
"gender": "men",
"category": {
"id": "sr:category:3",
"name": "ATP"
},
"level": "grand_slam"
}
]
}The catalog carries several thousand competitions. Filter on category (ATP, WTA, Challenger, ITF, UTR, and the team cups), type (singles, doubles, mixed_doubles, mixed), gender, and level (grand_slam, atp_1000, atp_500, atp_250, wta_1000, and so on) to find what you need.
Supported Languages
The Tennis API serves 11 languages: de (German), en (English), es (Spanish), fr (French), id (Indonesian), it (Italian), ja (Japanese), ru (Russian), th (Thai), zh (Chinese, simplified), and zht (Chinese, traditional). English is the most complete; see the language support sheet for per-competition availability.
Pagination
List-shaped feeds page their results and report totals in response headers: X-Max-Results (total rows), X-Offset, and X-Result (rows in this response). Use the start query parameter to move through pages. For example, Season Summaries returns up to 200 matches per page; a Grand Slam season with 242 matches needs a second request with ?start=200. Always read the headers rather than assuming a page size.
Data Flow: RESTful and Push
RESTful feeds are the foundation of a Tennis API integration: poll them at the cadences in Update Frequencies and reconcile with the change feeds described in Monitoring Data Changes. Push feeds stream live match data over a persistent connection for real-time use cases; see Push Feeds for access requirements and usage.
Integration Resources
Companion Tools
- OpenAPI specs: Tennis v3 and Tennis Probabilities v3 interactive Swagger documentation.
- Postman: fork the Tennis API collection to explore feeds interactively.
- XML schemas: download the Tennis v3 XSD bundle if you consume XML.
- Coverage Matrix: check per-competition coverage before you build.
- FAQ: the Tennis API FAQ answers common integration questions.
Updated 2 days ago