v2
Home › Getting Started

Getting Started

Your First Request

This guide walks you through authentication, the base URL structure, query parameters, and working code examples so you can integrate the Tennis API in minutes.

Step 1 — Subscribe on RapidAPI

The Tennis API is distributed exclusively through RapidAPI.

  1. Visit the Tennis API (ATP, WTA, ITF) listing on RapidAPI.
  2. Click Subscribe and select a pricing plan.
  3. Copy your X-RapidAPI-Key from the Security tab or the code snippets panel.
⚠️
Keep your key secret Never expose your X-RapidAPI-Key in client-side JavaScript or public repositories. Use environment variables or a secrets manager.

Step 2 — Base URL & Headers

Every request targets:

Base URL
https://tennis-api-atp-wta-itf.p.rapidapi.com

Include these two headers on every request:

HeaderValue
X-RapidAPI-Key YOUR_RAPIDAPI_KEY Required
X-RapidAPI-Host tennis-api-atp-wta-itf.p.rapidapi.com Required

Step 3 — URL Structure

Most endpoints follow this pattern:

Pattern
GET /tennis/v2/{type}/{module}/{params}
SegmentValuesDescription
{type}atp · wtaTour selection
{module}fixtures · player · h2h · ranking · tournamentResource module
{params}IDs, dates, etc.Module-specific path parameters

Step 4 — Make Your First Call

Let's fetch today's ATP fixtures as a quick smoke-test:

cURL
curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'
JavaScript (fetch)
const response = await fetch(
  'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures',
  {
    method: 'GET',
    headers: {
      'X-RapidAPI-Key': 'YOUR_RAPIDAPI_KEY',
      'X-RapidAPI-Host': 'tennis-api-atp-wta-itf.p.rapidapi.com'
    }
  }
);

const data = await response.json();
console.log(data);
Python (requests)
import requests

url = "https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures"

headers = {
    "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
    "X-RapidAPI-Host": "tennis-api-atp-wta-itf.p.rapidapi.com"
}

response = requests.get(url, headers=headers)
print(response.json())
PHP (cURL)
<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY",
    "X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com"
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response Format

All responses are JSON arrays or objects. A typical fixtures response looks like:

JSON Response
[
  {
    "id": 482910,
    "date": "2025-06-02T10:00:00.000Z",
    "player1Id": 68074,
    "player2Id": 47275,
    "tournamentId": 20340,
    "roundId": 3,
    "player1": {
      "id": 68074,
      "name": "Carlos Alcaraz",
      "countryAcr": "ESP"
    },
    "player2": {
      "id": 47275,
      "name": "Jannik Sinner",
      "countryAcr": "ITA"
    }
  }
]

Query Parameters

Several endpoints support optional query parameters for filtering. These are passed as standard URL query strings:

ParameterTypeDescription
PlayerGroup string Filter fixtures by match type: singles, doubles, or both (default).
TourRank string Comma-separated tournament rank IDs to filter by. Requires tournament include.
TourCourt string Comma-separated court type IDs. Requires tournament include.
TourCountry string Comma-separated country acronyms (e.g. USA,FRA). Requires tournament include.
ℹ️
Filters with includes Some filters (like TourRank, TourCourt, TourCountry) only take effect when the corresponding relation is requested using an include query parameter.

Rate Limits

A server-side throttle of 100 requests per minute per IP applies to all endpoints. On breach, the API returns:

HTTP 429
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Always check the HTTP status code before processing the response body.

Status CodeDescription
200 OKRequest succeeded. Response contains the requested data.
400 Bad RequestInvalid input parameters (e.g., invalid date format, non-numeric ID, invalid type parameter).
404 Not FoundResource not found (e.g., invalid player ID, tournament ID, or season ID).
429 Too Many RequestsRate limit exceeded. Wait before retrying.
500 Internal Server ErrorServer error. Contact support if this persists.

When an error occurs, the response body contains a JSON object with error details:

Error Response
{
  "error": true,
  "statusCode": 400,
  "message": "Invalid date format. Expected YYYY-MM-DD."
}
⚠️
Always check HTTP status first The API returns the appropriate HTTP status code for errors. Do not rely solely on the response body to detect errors — check the HTTP status code before parsing the JSON.

Next Steps

Now that you can make requests, explore the individual modules: