API Reference

Reference Data

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

✅

Cache these lookups locallyCountries, courts, rounds, and ranking tiers change rarely — fetch once on startup and reuse. Use the returned IDs as roundId, courtId, and rankId on fixture, tournament, and player responses.

ℹ️

Response envelopeAll endpoints on this page return a "data": [...] wrapper. Field names are prefixed (e.g. country_id, country_name rather than id, name).

Endpoint Summary

GET/tennis/v2/countries/

GET/tennis/v2/rankings

GET/tennis/v2/round

GET/tennis/v2/court

GET/tennis/v2/search?search=

Countries

GET/tennis/v2/countries

Returns all countries. No path or query parameters. Use country_acronym (3-letter IOC codes) to match nationality on player and tournament objects.

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'

Response Properties

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

Tournament Ranking Tiers

GET/tennis/v2/ranking

Canonical tournament-level IDs. Use rank_id as rankId on tournament objects and as TourRank inside filter. ATP 250 and ATP 500 both use rank_id 2 (Main tour); the calendar tier string distinguishes those labels. Grand Slam is rank_id 4, not 1.

This table is the lookup for fixtures, calendar, and player-match TourRank filters. Do not mix it with marketing names such as ATP 500 / WTA 1000 — those appear on the calendar tier field. ATP and WTA share the same rank_id integers; older WTA codes (T1–T5, …) are also in the live array.

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'

Response Properties

Field	Type	Description
`data[0].rank_id`	integer	Integer used as `rankId` on tournaments and as `TourRank` in `filter`. Live examples: `1` Challenger/ITF > $10K, `2` Main tour, `3` Masters, `4` Grand Slam.
`data[0].rank_name`	string	Label for that id. The live payload continues after id 9 with historic WTA/ITF codes.

Rounds

GET/tennis/v2/round

Returns every tournament round (id and label).

Use round_id as roundId on fixture rows. Rounds run from qualifying (lowest) through to Final (highest).

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'

Response Properties

Field	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`.

Court Surfaces

GET/tennis/v2/court

Returns every court surface with its ID and name: Hard, Clay, I.hard (indoor hard), Carpet, Grass and Acrylic. The IDs match courtId in tournament objects and are the values to use in TourCourt and GameCourt filters. No pagination.

Use court IDs as courtId on tournaments and as TourCourt when filtering fixtures. Surface win/loss for a player is on 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'

Response Properties

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

Global Search (Players & Tournaments)

GET/tennis/v2/search?search=Carlos%20Alcaraz

Search players and tournaments by name across ATP and WTA.

What search returns

Partial, case-insensitive name match across ATP and WTA players and tournaments. Results come back in four buckets — ATP players, WTA players, ATP tournaments, and WTA tournaments — each capped at 5 results. Each bucket includes a total count even if more than 5 exist.

Player results omit doubles pairs (names that contain /).

Query Parameter

Parameter	Required	Type	Description
`search`	Yes	string	Search term (query string, not a path segment). Partial names work — `Alcar` matches Carlos Alcaraz. URL-encode spaces. Example: `search=Carlos%20Alcaraz`. Returns names, not numeric IDs.

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'

Response Properties

Field	Type	Description
`data[0].category`	string	One of: player_atp, player_wta, tournament_atp, tournament_wta.
`data[0].total`	number	Total matches in this category (may be larger than the 5 items in result).
`data[0].result`	array	Up to 5 matching objects. Player and tournament shapes are below.