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|wta}/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

Shared objects in this response (defined once in Reusable response schemas): Player.

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.
`data[].player`	object	Player object (id, name, countryAcr and the other player fields shown).
`data[].player.countryAcr`	string	Three-letter country code (IOC style), e.g. ESP.
`data[].player.country`	object	Player's country: { name, acronym }.
`data[].player.country.name`	string	Country name.
`data[].player.country.acronym`	string	Three-letter country code.
`page`	number	Current page number (1-based).
`limit`	number	Items per page.

Doubles Rankings

GET/tennis/v2/{atp|wta}/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. When omitted, the endpoint's own default applies (100 on most list endpoints; some use 50 or 500), and the response's `pageSize` shows the value used. 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

Shared objects in this response (defined once in Reusable response schemas): Player.

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.
`data[].player.id`	number	Player ID.
`data[].player.name`	string	Display name.
`data[].player.birthday`	string	Date of birth (ISO-8601), or null when unknown.
`data[].player.countryAcr`	string	Three-letter country code (IOC style), e.g. ESP.
`data[].player.country`	object	Player's country: { name, acronym }.
`data[].player.country.name`	string	Country name.
`data[].player.country.acronym`	string	Three-letter country code.
`page`	number	Current page number (1-based).
`limit`	number	Items per page.

Race Rankings (Year-to-Date)

GET/tennis/v2/{atp|wta}/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'

Response Properties

Shared objects in this response (defined once in Reusable response schemas): Player.

Field	Type	Description
`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[].racePosition`	number	Position in the Race (year-to-date) standings.
`data[].racePoints`	number	Race points accumulated this season.
`data[].player`	object	Player object (id, name, countryAcr and the other player fields shown).
`data[].player.id`	number	Player ID.
`data[].player.name`	string	Display name.
`data[].player.birthday`	string	Date of birth (ISO-8601), or null when unknown.
`data[].player.countryAcr`	string	Three-letter country code (IOC style), e.g. ESP.
`data[].player.country`	object	Player's country: { name, acronym }.
`data[].player.country.name`	string	Country name.
`data[].player.country.acronym`	string	Three-letter country code.
`page`	number	Current page number (1-based).
`pageNo`	number	Current page number (1-based); same value as page.
`pageSize`	number	Items per page; same value as limit.
`limit`	number	Items per page.
`hasNextPage`	boolean	true when another page exists after this one.

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|wta}/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);

Response Properties

Shared objects in this response (defined once in Reusable response schemas): Player.

Field	Type	Description
`[].id`	string	Ranking row ID (one player's entry in this ranking week; numeric string).
`[].date`	string	Ranking week date (ISO-8601 UTC).
`[].point`	number	Ranking points (this endpoint returns point only; same value as rankingPoints elsewhere).
`[].position`	number	Ranking position.
`[].player.id`	integer	Player ID (same as on the core ranking feed and player profiles).
`[].player.name`	string	Player display name.
`[].player.countryAcr`	string	Three-letter country code.
`[]`	object	One item of the response; its fields are listed below.
`[].player`	object	Player object (id, name, countryAcr and the other player fields shown).

Top 500 Formatted Names

GET/tennis/v2/ranking/{atp|wta}/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}.
`[]`	object	One item of the response; its fields are listed below.

Ranking Filter Options

GET/tennis/v2/ranking/{atp|wta}/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'

Response Properties

Field	Type	Description
`countries`	array	Country filter options: name and acronym.
`surfaces`	array	Court-surface filter options: id and name.
`date`	array	Available ranking week dates (ISO-8601 UTC), newest first. Pass one as date=DD.MM.YYYY to the rankings-by-date route.
`countries[].name`	string	Country name.
`countries[].acronym`	string	Three-letter country code.
`surfaces[].id`	number	Court-surface ID.
`surfaces[].name`	string	Court-surface name.

Player Ranking History

GET/tennis/v2/ranking/{atp|wta}/player/{player_id}/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	string	Player: numeric ID or display name. Example: `47275` or `Jannik Sinner`. IDs come from Rankings (`player.id`), Fixtures (`player1Id`) or the core player list. A name shared by several players returns `400` listing their IDs.

Query Parameter

Parameter	Required	Type	Description
`months`	No	integer	How many months of history to return (default 3, max 240). Ignored when `startDate` is set. Example: `months=3`.
`startDate`	No	string	Start of the range, `YYYY-MM-DD`. Example: `startDate=2020-01-01`.
`endDate`	No	string	End of the range, `YYYY-MM-DD` (default: latest). Other query parameters return `400`. Example: `endDate=2026-10-01`.

Example Request: CURL

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

Response Properties

Shared objects in this response (defined once in Reusable response schemas): Player.

Field	Type	Description
`player`	object	Player object (id, name, countryAcr and the other player fields shown).
`player.name`	string	Display name.
`player.countryAcr`	string	Three-letter country code (IOC style), e.g. ESP.
`change`	number	Positions gained (+) or lost (−) between the first and the last snapshot in history; null when there is no history.
`history`	array	Ranking snapshots in date order.
`history[]`	object	One item of `history`; its fields are listed below.
`history[].date`	string	Ranking date (ISO-8601).
`history[].position`	number	Ranking position on that date.
`history[].pts`	number	Ranking points on that date.

Rankings by Group and Date

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

This example uses atp. Use wtafor the women's dataset.Returns a ranking snapshot for a tour, group, and date. date (DD.MM.YYYY or YYYY-MM-DD) and group are required. Rankings are published weekly: any date returns the latest snapshot on or before it (each row's date shows which one). Response is a JSON array — not wrapped in data — so it has no totalPages or hasNextPage: ask for the next page with page=N+1 and stop when a page returns fewer rows than limit (an empty array past the end).

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, DD.MM.YYYY or YYYY-MM-DD (both accepted). Required together with group. Example: date=14.09.2026 or date=2026-09-14
`countryAcr`	No	string	3-letter country code. Example: `countryAcr=ESP`.
`page`	No	integer	Page number, starting at 1. pageNo is accepted as an alias on every route. Example: page=1
`limit`	No	integer	Results per page. pageSize is accepted as an alias on every route. 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

Shared objects in this response (defined once in Reusable response schemas): Player.

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.
`[]`	object	One item of the response; its fields are listed below.
`[].player.id`	number	Player ID.
`[].player.name`	string	Display name.
`[].player.countryAcr`	string	Three-letter country code (IOC style), e.g. ESP.

ℹ️

Tip

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