1. Home
  2. 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 secretNever 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-KeyYOUR_RAPIDAPI_KEYRequired
X-RapidAPI-Hosttennis-api-atp-wta-itf.p.rapidapi.comRequired

Step 3 — URL Structure

There are almost 3 url prefix exist -- default, advanced & extend. And most endpoints follow this pattern:

Pattern
// Default prefix
// "/tennis/v2"

// Advanced API prefix 
// "/tennis/v2/ms-api"

// Extend API prefix 
// "/tennis/v2/extend/api"

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 & all responses are JSON arrays or objects:

Example Request: curl
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/fixtures' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'
Example Response: JSON
[
  {
    "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
PlayerGroupstringFilter fixtures by match type: singles, doubles, or both (default).
TourRankstringComma-separated tournament rank IDs to filter by. Requires tournament include.
TourCourtstringComma-separated court type IDs. Requires tournament include.
TourCountrystringComma-separated country acronyms (e.g. USA,FRA). Requires tournament include.
ℹ️
Filters with includesSome 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 firstThe 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:

  • Fixtures — match schedule, live fixtures, date-range queries
  • Players — player profiles, stats, surface summaries
  • Head-to-Head — rivalry records and per-match stats
  • Rankings — live ATP & WTA world rankings
  • Tournaments — event calendar, seasons, past champions
  • Miscellaneous — reference data and full-text search