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 locallyCountries, 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 envelopeAll 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

Get 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.

Example Request: CURL

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

Example Response: JSON

{
  "data": [
    {
      "country_name": "Spain",
      "country_acronym": "ESP"
    },
    {
      "country_name": "Italy",
      "country_acronym": "ITA"
    },
    {
      "country_name": "United States",
      "country_acronym": "USA"
    },
    {
      "country_name": "France",
      "country_acronym": "FRA"
    }
  ]
}

Response Properties

Parameter	Type	Description
`data[0].country_name`	string	Full English country name (e.g. `Spain`, `United States`).
`data[0].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.

Get 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.

Example Request: CURL

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

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"
    }
  ]
}

Response Properties

Parameter	Type	Description
`data[0].rank_id`	string	Tier ID — matches the `rankId` field on Tournament objects.
`data[0].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`.

Get 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.

Example Request: CURL

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

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"
    }
  ]
}

Response Properties

Parameter	Type	Description
`data[0].round_id`	string	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.
`data[0].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`.

Get 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).

Example Request: CURL

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

Example Response: JSON

{
  "data": [
    {
      "court_id": 1,
      "court_name": "Hard"
    },
    {
      "court_id": 2,
      "court_name": "Clay"
    },
    {
      "court_id": 3,
      "court_name": "I.hard"
    },
    {
      "court_id": 4,
      "court_name": "Carpet"
    },
    {
      "court_id": 5,
      "court_name": "Grass"
    },
    {
      "court_id": 6,
      "court_name": "Acrylic"
    }
  ]
}

Response Properties

Parameter	Type	Description
`data[0].court_id`	string	Court surface ID — matches `courtId` in Tournament objects and the `TourCourt` filter parameter.
`data[0].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.

Get 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 Parameter

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

Example Request: CURL

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

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": []
    }
  ]
}

Response Properties

Parameter	Type	Description
`data[0].category`	string	One of: player_atp, player_wta, tournament_atp, tournament_wta.
`data[0].total`	number	Total number of matching records in the database for this category (may be larger than the 5 returned in result).
`data[0].result`	array	Up to 5 matching objects. See Player Result and Tournament Result schemas below.