API Reference

Miscellaneous

Reference data endpoints for countries, court surfaces, round types, tournament ranking tiers, and a full-text search across players and tournaments.

✅

Cache these lookup tables locally Countries, Courts, Rounds, and Ranking Tiers are stable reference data — fetch once on startup and cache. The IDs from these endpoints are the same foreign key values used in Fixture, Tournament, and Player responses.

ℹ️

Response envelope All endpoints on this page return a { "data": [...] } wrapper. Field names use the entity alias prefix from the underlying SQL query (e.g. country_id, country_name rather than id, name).

Endpoint Summary

Method	Path	Description
GET	`/tennis/v2/countries`	All countries
GET	`/tennis/v2/ranking`	All ranking tiers / levels
GET	`/tennis/v2/round`	All round types
GET	`/tennis/v2/court`	All court surface types
GET	`/tennis/v2/search?search={query}`	Search players & tournaments by name

Countries

GET /tennis/v2/countries Returns a list of all countries present in the database

No path or query parameters are required. Use the returned country_acronym values to cross-reference nationality data in player and tournament objects — both use the same 3-letter IOC codes.

Response Schema

Country Object

country_id integer Unique country identifier.

country_name string Full English country name (e.g. Spain, United States).

country_acronym string 3-letter country code following IOC/tennis convention (e.g. ESP, USA, GBR). This is the same value used in countryAcr fields across Players, Fixtures, and Tournaments.

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/countries' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    { "country_id": 1, "country_name": "Spain", "country_acronym": "ESP" },
    { "country_id": 2, "country_name": "Italy", "country_acronym": "ITA" },
    { "country_id": 3, "country_name": "United States", "country_acronym": "USA" },
    { "country_id": 4, "country_name": "France", "country_acronym": "FRA" }
  ]
}

Ranking Tiers

GET /tennis/v2/ranking Returns all tournament ranking tier definitions (Grand Slam, Masters 1000, etc.)

Returns every tier level defined in the system. The rank_id corresponds to the rankId foreign key on Tournament objects. ATP and WTA use different tier systems — see the Tournaments page for details on how ATP uses rank.name while WTA uses its own tier field.

Response Schema

Rank Object

rank_id integer Tier ID — matches the rankId field on Tournament objects.

rank_name string Human-readable tier label. Typical values include Grand Slam, ATP Masters 1000, ATP 500, ATP 250, WTA 1000, WTA 500, WTA 250, ITF.

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ranking' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    { "rank_id": 1, "rank_name": "Grand Slam" },
    { "rank_id": 2, "rank_name": "ATP Masters 1000" },
    { "rank_id": 3, "rank_name": "ATP 500" },
    { "rank_id": 4, "rank_name": "ATP 250" },
    { "rank_id": 5, "rank_name": "WTA 1000" },
    { "rank_id": 6, "rank_name": "WTA 500" }
  ]
}

Rounds

GET /tennis/v2/round Returns all tournament round type definitions

The round_id corresponds to the roundId foreign key on Fixture objects. Rounds progress from qualifying (lowest) through to Final (highest). Knowing the round ID lets you filter or label fixtures precisely.

Response Schema

Round Object

round_id integer Round ID — matches the roundId field on Fixture objects. Lower IDs generally correspond to later rounds (Final = 1), but verify with actual data as IDs may vary by tour.

round_name string Round name. Typical values: Final, Semi-Final, Quarter-Final, Round of 16, Round of 32, Round of 64, Round of 128, Qualifying Round 1, Qualifying Round 2.

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/round' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    { "round_id": 1, "round_name": "Final" },
    { "round_id": 2, "round_name": "Semi-Final" },
    { "round_id": 3, "round_name": "Quarter-Final" },
    { "round_id": 4, "round_name": "Round of 16" },
    { "round_id": 5, "round_name": "Round of 32" },
    { "round_id": 6, "round_name": "Round of 64" },
    { "round_id": 7, "round_name": "Round of 128" }
  ]
}

Courts

GET /tennis/v2/court Returns all court surface type definitions

Court surface IDs are used as the courtId foreign key on Tournament objects, and as a filter value for the TourCourt query parameter when fetching fixtures. Note that the Player entity separately tracks surface-specific win/loss statistics (see Players — Surface Breakdown).

Response Schema

Court Object

court_id integer Court surface ID — matches courtId in Tournament objects and the TourCourt filter parameter.

court_name string Surface name. Typical values: Hard (outdoor), Clay, Grass, Carpet, Indoor Hard. Outdoor hard and indoor hard are tracked separately in player surface statistics.

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/court' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    { "court_id": 1, "court_name": "Hard" },
    { "court_id": 2, "court_name": "Clay" },
    { "court_id": 3, "court_name": "Grass" },
    { "court_id": 4, "court_name": "Carpet" },
    { "court_id": 5, "court_name": "Indoor Hard" }
  ]
}

Search

GET /tennis/v2/search Search players and tournaments by name across ATP and WTA

How Search Works

The search endpoint runs a case-insensitive substring match (ILIKE '%query%') against player names and tournament names simultaneously, across both ATP and WTA databases. Results are returned as four separate category buckets — ATP players, WTA players, ATP tournaments, and WTA tournaments — each capped at 5 results. Each bucket also includes a total count of all matching records even if more than 5 exist.

For players, it also filters out records where the name contains a slash (/), which removes doubles pair entries from appearing in individual player results.

Query Parameters

Parameter	Type	Description
`search` Required	string	Search term. Partial names work — `Alcar` matches Carlos Alcaraz. URL-encode spaces as `%20`.

Response Schema

Top-level Envelope

data array Array of 4 category result buckets, always in the same order: player_atp, player_wta, tournament_atp, tournament_wta.

Category Bucket

category string One of: player_atp, player_wta, tournament_atp, tournament_wta.

total integer Total number of matching records in the database for this category (may be larger than the 5 returned in result).

result array Up to 5 matching objects. See Player Result and Tournament Result schemas below.

Player Result Object

name string Player full name (e.g. Carlos Alcaraz).

birthday string | null Player date of birth in YYYY-MM-DD format, or null if unknown.

countryAcr string 3-letter country code. Cross-reference with the /countries endpoint.

Tournament Result Object

name string Tournament name (e.g. Wimbledon, Roland Garros).

countryAcr string Country where the tournament is held.

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/search?search=Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

JavaScript

const query = 'Alcaraz';
const res = await fetch(
  `https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/search?search=${encodeURIComponent(query)}`,
  { headers: { 'X-RapidAPI-Key': 'YOUR_KEY', 'X-RapidAPI-Host': 'tennis-api-atp-wta-itf.p.rapidapi.com' } }
);
const results = await res.json();

Python

import requests
r = requests.get(
  "https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/search",
  params={"search": "Alcaraz"},
  headers={"X-RapidAPI-Key": "YOUR_KEY", "X-RapidAPI-Host": "tennis-api-atp-wta-itf.p.rapidapi.com"}
)
print(r.json())

Example Response

JSON

{
  "data": [
    {
      "category": "player_atp",
      "total": 1,
      "result": [
        {
          "name": "Carlos Alcaraz",
          "birthday": "2003-05-05",
          "countryAcr": "ESP"
        }
      ]
    },
    {
      "category": "player_wta",
      "total": 0,
      "result": []
    },
    {
      "category": "tournament_atp",
      "total": 0,
      "result": []
    },
    {
      "category": "tournament_wta",
      "total": 0,
      "result": []
    }
  ]
}

Search Tips

Use full or partial names: Djoko, Wimbledon, Roland
Country codes work for tournaments: ESP, USA
The match is case-insensitive — alcaraz and ALCARAZ both work
URL-encode spaces and special characters (e.g. Roland%20Garros or Roland+Garros)
Each category returns at most 5 results; use total to know if there are more matches
To look up a specific player's full profile after searching, pass their name to the Players endpoint