API Reference

Rankings

Use the core lists for current official singles, doubles, and race rankings. Extra endpoints below cover dated snapshots, ranking history, and formatted names — not a second current ranking list.

⚠️

Dated rankings need date + group

/tennis/v2/ranking/atp without query params returns Needs date in query params!. Use ?date=14.09.2026&group=singles&page=1&limit=10. YYYY-MM-DD is rejected. There is no /ranking/atp/{date} path. Core pagination uses pageNo/pageSize; advanced uses page/limit.

Which ranking endpoint to use

Core ranking endpoints return the current published list — position, points, and movement for each player. Dated snapshot endpoints return a snapshot for a specific date, which you can use to chart how a player's position changed over time.

Endpoint family	What it contains	Use case
Core `/{atp\|wta}/ranking/singles`	Current ranking: position, points, weekly movement	Today's world rankings
Dated snapshot `/ranking/{atp\|wta}`	Historical snapshot for `date` + `group`	Ranking history, dated cut-offs

Endpoint Summary

GET/tennis/v2/{atp|wta}/ranking/singles

GET/tennis/v2/{atp|wta}/ranking/doubles

GET/tennis/v2/{atp|wta}/ranking/singles?race=true

GET/tennis/v2/ranking/{atp|wta}/top500-names

GET/tennis/v2/ranking/{atp|wta}/filters

GET/tennis/v2/ranking/{atp|wta}/player/{player_id}/history

GET/tennis/v2/ranking/{atp|wta}

Singles Rankings

GET/tennis/v2/atp/ranking/singles

This example uses atp. Use wtafor the women's dataset.Returns the current ATP or WTA singles world rankings, ordered by position.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Query Parameter

Parameter	Required	Type	Description
`race`	No	string	Set to `true` to return the Race to Turin / Race to Fort Worth standings instead of the standard 52-week rankings. Results are sorted by year-to-date race points (`racePoints`) descending. Supports `filter=PlayerCountry` and pagination. Example: `race=true`
`filter`	No	string	Semicolon-separated filters in `Key:value` format. Available filters: `RankingDate:YYYY-MM-DD` — snapshot on or before this date (standard rankings only, not with `race=true`) `PlayerCountry:USA,GBR` — 3-letter country codes (works with standard and race) Example: `filter=RankingDate:2025-01-06;PlayerCountry:ESP,ITA`
`pageSize`	No	integer	Results per page. Default: `10` (standard rankings) / `100` (race rankings).
`pageNo`	No	integer	Page number, 1-indexed. Default: `1`. Example: pageNo=1. Use `hasNextPage` in the response to check for more pages.

Example Request: CURL

curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/ranking/singles' \
	--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`	array	The page of results. An empty array with HTTP 200 means the request was valid and nothing matched that date, filter, or page.
`pageNo`	integer	Current page, starting at 1. Also returned as page.
`pageSize`	integer	Items requested for this page. Also returned as limit. Core maximum is 500.
`hasNextPage`	boolean	true if another page exists. Stop when this is false or data is empty.
`id`	integer	Snapshot row ID for this ranking entry.
`date`	string	List date as ISO-8601.
`position`	integer	Rank position on that list.
`rankingPoints / point`	integer	Points used to order this list. Both keys are present.
`player.id`	integer	Numeric player ID — use this on core /player/profile/{id}.
`player.name`	string	Display name — URL-encode this on advanced profile routes.

Doubles Rankings

GET/tennis/v2/atp/ranking/doubles

This example uses atp. Use wtafor the women's dataset.Returns the current ATP or WTA doubles world rankings, ordered by position. Same pagination envelope as singles.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Query Parameter

Parameter	Required	Type	Description
`filter`	No	string	Semicolon-separated filters. Available: `PlayerCountry:USA,GBR` (3-letter codes). Example: `filter=PlayerCountry:ESP,ITA`
`pageSize`	No	integer	Results per page. Default: `10`. Core maximum: `500` (larger values are reduced). Example: pageSize=10.
`pageNo`	No	integer	Page number, 1-indexed. Default: `1`. Example: pageNo=1. Use `hasNextPage` in the response to check for more pages.

Example Request: CURL

curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/ranking/doubles' \
	--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`	array	The page of results. An empty array with HTTP 200 means the request was valid and nothing matched that date, filter, or page.
`pageNo`	integer	Current page, starting at 1. Also returned as page.
`pageSize`	integer	Items requested for this page. Also returned as limit. Core maximum is 500.
`hasNextPage`	boolean	true if another page exists. Stop when this is false or data is empty.
`position`	integer	Doubles rank position.
`pts`	integer	Doubles ranking points.
`wk`	integer	Places moved this week.
`player`	object	id, name, countryAcr — use player.id on core player routes.

Race Rankings (Year-to-Date)

GET/tennis/v2/atp/ranking/singles?race=true

This example uses atp. Use wtafor the women's dataset.Returns the Race to Turin (ATP) or Race to Fort Worth (WTA) year-to-date standings, sorted by race points descending.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Query Parameter

Parameter	Required	Type	Description
`race`	Yes	string	Set to `true` to return the Race to Turin / Race to Fort Worth standings instead of the standard 52-week rankings. Results are sorted by year-to-date race points (`racePoints`) descending. Supports `filter=PlayerCountry` and pagination. Example: `race=true`

Add race=true to the singles ranking endpoint to switch from the standard 52-week rolling rankings to the year-to-date race standings. Only players with race points > 0 are returned.

Example Request: CURL

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

Extra ranking endpoints

These are not a second current ranking list. Use them for a quick top 10, formatted names, dated snapshots, and ranking history.

Top 10 Rankings

GET/tennis/v2/ranking/atp/top

This example uses atp. Use wtafor the women's dataset.Retrieve the latest Top 10 ATP or WTA rankings, including player names, rankings, ranking points, country codes, and the official ranking date.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Example Request: JAVASCRIPT

const response = await fetch("https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ranking/atp/top", {
   method: "GET",
   headers: {
      "X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
      "X-RapidAPI-Host": "tennis-api-atp-wta-itf.p.rapidapi.com",
   },
});

const result = await response.json();
console.log(result);

Top 500 Formatted Names

GET/tennis/v2/ranking/atp/top500-names

This example uses atp. Use wtafor the women's dataset.Returns ranking names with a display-safe formattedName. Use formattedName on name-based profile routes when the original name has punctuation.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Example Request: CURL

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

Response Properties

Field	Type	Description
`(root)`	array	A JSON array (not wrapped in data).
`rank`	integer	Current ranking position.
`originalName`	string	Display name as returned on other routes.
`formattedName`	string	URL-encode this for /tennis/v2/profile/{name}.

Ranking Filter Options

GET/tennis/v2/ranking/atp/filters

This example uses atp. Use wtafor the women's dataset.Retrieve all available filter options for ranking queries, including tours, ranking types, countries, ranking dates, and other supported filter values. Use these values to build valid requests for ranking endpoints.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Example Request: CURL

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

Player Ranking History

GET/tennis/v2/ranking/atp/player/5992/history

This example uses atp. Use wtafor the women's dataset.Retrieve a player's ranking history over time, including ranking positions, ranking points, movement since the previous ranking, and historical ranking dates.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.
`player_id`	Yes	integer	Player ID (≥ 1). Take it from Rankings (`player.id`), Fixtures (`player1Id`), or the core player list. Search returns names, not IDs.

Query Parameter

Parameter	Required	Type	Description
`months`	No	integer	How many months of history to return. Example: `months=3`.

Example Request: CURL

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

Rankings by Group and Date

GET/tennis/v2/ranking/atp?date=14.09.2026&group=singles&page=1&limit=10

This example uses atp. Use wtafor the women's dataset.Returns a ranking snapshot for a tour, group, and date. date (DD.MM.YYYY) and group are required. Response is a JSON array — not wrapped in data.

Path Parameter

Parameter	Required	Type	Description
`atp\|wta`	Yes	string	Dataset to query. `atp` = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. `wta` = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate `itf` value.

Query Parameter

Parameter	Required	Type	Description
`group`	Yes	string	Filter by group. Enum("singles", "doubles", "race", "surface", "prize"). Required on full rankings. Example: group=singles
`date`	Yes	string	Ranking snapshot date in DD.MM.YYYY format (not YYYY-MM-DD). Required together with group. Example: date=14.09.2026
`countryAcr`	No	string	3-letter country code. Example: `countryAcr=ESP`.
`page`	No	integer	Page number on advanced routes, starting at 1. Do not send pageNo here. Example: page=1
`limit`	No	integer	Results per page on advanced routes (use page + limit, not pageNo + pageSize). Default varies by endpoint. Example: limit=10

Example Request: CURL

curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ranking/atp?date=14.09.2026&group=singles&page=1&limit=10' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

Field	Type	Description
`(root)`	array	A JSON array of ranking rows (not wrapped in data).
`position`	integer	Rank position on the requested date and group.
`pts`	integer	Points for that group (singles, doubles, etc.).
`wk / wkPts / yr`	integer	Weekly movement, points change this week, and year-to-date points when provided.
`date`	string	Snapshot date as ISO-8601.
`player`	object	Player record: id, name, countryAcr, and ranking-related fields.

ℹ️

Tip

The /tennis/v2/ranking endpoint in Reference Data returns ranking tier definitions (Grand Slam, Masters 1000, etc.) — not player rankings.