API Reference

Reference Data & Search

Countries, court surfaces, round types, tournament ranking tiers, and full-text search across players and tournaments. Resolve IDs here, then use them on Upcoming Matches, Profiles, 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.
`data`	array	Response payload: the list or object documented in the rows below.
`data[]`	object	One item of `data`; its fields are listed below.

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.
`data`	array	Response payload: the list or object documented in the rows below.
`data[]`	object	One item of `data`; its fields are listed below.

Rounds

GET/tennis/v2/round

Returns every round code (round_id and its label). The same IDs appear as roundId on fixtures, results, draws and live rows.

Labels are short codes (1/4 = quarterfinal, 1/2 = semifinal, Q1 = qualifying round 1). IDs are codes, not an order. The full meaning of every value is in the table below the example.

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'

All round values

roundId	Label returned	Stage	Meaning
`0`	`Pre-q`	Qualifying	Pre-qualifying round (before qualifying round 1).
`1`	`Q1`	Qualifying	Qualifying round 1. When a qualifying draw has only one round (e.g. some WTA 125 and ITF events), Q1 is also the last qualifying round.
`2`	`Q2`	Qualifying	Qualifying round 2.
`3`	`Q3`	Qualifying	Qualifying round 3 (the final qualifying round at most tour events).
`22`	`Q4`	Qualifying	Qualifying round 4 (older ITF events with large qualifying draws).
`25`	`Q5`	Qualifying	Qualifying round 5 (older ITF events).
`24`	`QF`	Qualifying	Legacy label found only in old ITF data. Not the main-draw quarterfinal — that is 9 (1/4).
`4`	`First`	Main draw	Main-draw first round (e.g. R128 at a Grand Slam, R32 at a 250 event).
`5`	`Second`	Main draw	Main-draw second round.
`6`	`Third`	Main draw	Main-draw third round.
`7`	`Fourth`	Main draw	Main-draw fourth round (round of 16 at a Grand Slam).
`9`	`1/4`	Main draw	Quarterfinal.
`10`	`1/2`	Main draw	Semifinal.
`12`	`Final`	Main draw	Main-draw final. Only the tournament final uses 12; the last qualifying match is Q1–Q3.
`8`	`Robin`	Team / special	Round-robin group match (e.g. Tour Finals, Laver Cup, United Cup).
`11`	`Bronze`	Team / special	Bronze-medal match (Olympics).
`13`	`Rubber 1`	Team / special	Team competition (Davis Cup / Billie Jean King Cup): rubber 1 of the tie.
`14`	`Rubber 2`	Team / special	Team competition: rubber 2 of the tie.
`15`	`Rubber 3`	Team / special	Team competition: rubber 3 of the tie.
`16`	`Rubber 4`	Team / special	Team competition: rubber 4 of the tie.
`17`	`Rubber 5`	Team / special	Team competition: rubber 5 of the tie.
`21`	`ER`	Other	Reserved code; not used by any match in the current data.
`23`	`CR`	Other	Reserved code; not used by any match in the current data.
`20`	`N/A`	Other	Round not specified.
`-1`	`N/A`	Other	Round not specified.

Response Properties

Field	Type	Description
`data[].round_id`	integer	Round code; the same value as `roundId` on fixtures, results, draws and live rows. Not an ordering (Final is `12`, quarterfinal `9`). See the table below.
`data[].round_name`	string	Short label exactly as returned, e.g. `Q1`, `First`, `1/4`, `1/2`, `Final`, `Robin`, `Rubber 1`.
`data`	array	Response payload: the list or object documented in the rows below.
`data[]`	object	One item of `data`; its fields are listed below.

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.
`data`	array	Response payload: the list or object documented in the rows below.
`data[]`	object	One item of `data`; its fields are listed below.

Global Search (Players & Tournaments)

GET/tennis/v2/search

Search players and tournaments by name across men's and women's tennis.

What search returns

Partial, case-insensitive name match across men's and women's 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. Example: `Carlos Alcaraz`. 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=Indian' \
	--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. Players: id (player ID, as in rankings and profiles), name, birthday, countryAcr. Tournaments: id, name, countryAcr.
`data`	array	Response payload: the list or object documented in the rows below.
`data[]`	object	One item of `data`; its fields are listed below.
`data[].result[].id`	number	Live event ID.
`data[].result[].name`	string	Name of the matching player or tournament.
`data[].result[].birthday`	string	Player date of birth (players only).
`data[].result[].countryAcr`	string	Country code (players only).