API Reference

Rankings

The Rankings module provides live world rankings for both singles and doubles categories across ATP and WTA tours. Rankings data is updated regularly to reflect the latest tournament results.

Endpoint Summary

Method	Path	Description
GET	`/tennis/v2/{type}/ranking/singles`	Singles world rankings
GET	`/tennis/v2/{type}/ranking/doubles`	Doubles world rankings

How Rankings Work

Rankings are not a separate table. They are served directly from the Player entity, which stores the current ranking snapshot on each player row. The database is updated whenever ATP/WTA publish their official weekly ranking lists.

A separate Rating table stores historical ranking snapshots — one row per player per date — enabling you to reconstruct ranking history or build charts showing how a player's position changed over time.

Source	What it contains	Use case
Player entity	Current ranking: position, points, progress, surface breakdown	Today's live rankings list
Rating entity	Historical snapshot: `date`, `position`, `point` per player	Ranking history charts, "peak ranking" analysis

Singles Rankings

GET /tennis/v2/{type}/ranking/singles Returns the current ATP or WTA singles world rankings, ordered by position

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`

Query Parameters

Parameter	Type	Description
`race` Optional	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` Optional	string	Semicolon-separated filters in `Key:value` format. Available filters: `RankingDate:{YYYY-MM-DD}` — returns the ranking snapshot on or before this date (standard rankings only, not applicable when `race=true`) `PlayerCountry:{USA,GBR}` — filter by 3-letter country acronym (works with both standard and race rankings) Example: `filter=RankingDate:2025-01-06;PlayerCountry:ESP,ITA`
`pageSize` Optional	integer	Results per page. Default: `10` (standard rankings) / `100` (race rankings).
`pageNo` Optional	integer	Page number, 1-indexed. Default: `1`.

Example Request

cURL

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

JavaScript

const res = await fetch(
  'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/ranking/singles',
  { headers: { 'X-RapidAPI-Key': 'YOUR_KEY', 'X-RapidAPI-Host': 'tennis-api-atp-wta-itf.p.rapidapi.com' } }
);
const rankings = await res.json();

Python

import requests
r = requests.get(
  "https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/ranking/singles",
  headers={"X-RapidAPI-Key": "YOUR_KEY", "X-RapidAPI-Host": "tennis-api-atp-wta-itf.p.rapidapi.com"}
)
print(r.json())

Example Response

JSON

[
  {
    "id": 106421,
    "name": "Jannik Sinner",
    "countryAcr": "ITA",
    "currentRank": 1,
    "points": 11330,
    "progress": 0,
    "ch": 1,
    "hardPoints": 6200,
    "ihardPoints": 800,
    "clayPoints": 4330,
    "grassPoints": 0,
    "prize": 28400000
  },
  {
    "id": 100644,
    "name": "Novak Djokovic",
    "countryAcr": "SRB",
    "currentRank": 2,
    "points": 9520,
    "progress": 0,
    "ch": 1
  }
]

Response Properties

Property	Type	Description
`id`	integer	Player ID — use this to fetch full profile, H2H, or fixtures for this player.
`name`	string	Player full name as registered in ATP/WTA records.
`countryAcr`	string	3-letter nationality code (e.g. `ITA`, `SRB`, `ESP`).
`currentRank`	integer	Current singles world ranking position. The response array is sorted ascending by this field (rank 1 first).
`points`	integer	Total ATP/WTA ranking points — the aggregate used to determine `currentRank`.
`progress`	integer	Ranking change since the last official weekly update. Positive = moved up, negative = dropped, `0` = unchanged. Render as up/down arrows in UI.
`ch`	integer \| null	Race Points — year-to-date points for the Race to Turin (ATP) / Race to Fort Worth (WTA). Use `race=true` to get the full race standings sorted by this field.
`hardPoints`	integer \| null	Ranking points earned on outdoor hard court. Sums with other surface points to total `points`.
`ihardPoints`	integer \| null	Points earned on indoor hard court — tracked separately from outdoor hard (e.g. ATP Finals = indoor hard; Australian Open = outdoor hard).
`clayPoints`	integer \| null	Points earned on clay surfaces.
`grassPoints`	integer \| null	Points earned on grass surfaces.
`carpetPoints`	integer \| null	Points earned on carpet (legacy surface — rarely used in modern tennis).
`prize`	integer \| null	Career prize money in USD as an integer (e.g. `28400000` = $28.4M).

Race Rankings (Year-to-Date)

GET /tennis/v2/{type}/ranking/singles?race=true Returns the Race to Turin (ATP) or Race to Fort Worth (WTA) year-to-date standings, sorted by race points descending

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&pageSize=20' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

JavaScript

const res = await fetch(
  'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/ranking/singles?race=true&pageSize=20',
  { headers: { 'X-RapidAPI-Key': 'YOUR_KEY', 'X-RapidAPI-Host': 'tennis-api-atp-wta-itf.p.rapidapi.com' } }
);
const race = await res.json();

Example Response

JSON

{
  "data": [
    {
      "racePosition": 1,
      "racePoints": 3900,
      "player": {
        "id": 106421,
        "name": "Jannik Sinner",
        "countryAcr": "ITA",
        "country": { "name": "Italy" }
      }
    },
    {
      "racePosition": 2,
      "racePoints": 3650,
      "player": {
        "id": 207989,
        "name": "Carlos Alcaraz",
        "countryAcr": "ESP",
        "country": { "name": "Spain" }
      }
    }
  ]
}

Response Properties

Property	Type	Description
`racePosition`	integer	Position in the year-to-date race standings (1 = leading). Calculated from sort order — accounts for pagination offset.
`racePoints`	integer	Year-to-date points earned since January 1. This is the ATP Race to Turin / WTA Race to Fort Worth value.
`player.id`	integer	Player ID — use with other endpoints to fetch profile, H2H, past matches.
`player.name`	string	Player full name.
`player.countryAcr`	string	3-letter nationality code.
`player.country`	object	Country name object.

Doubles Rankings

GET /tennis/v2/{type}/ranking/doubles Returns the current ATP or WTA doubles world rankings, ordered by position

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`

Query Parameters

Parameter	Type	Description
`filter` Optional	string	Semicolon-separated filters in `Key:value` format. Available filters: `PlayerCountry:{USA,GBR}` — filter by 3-letter country acronym Example: `filter=PlayerCountry:ESP,ITA`

Example Request

cURL

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

Example Response

JSON

[
  {
    "id": 105012,
    "name": "Rohan Bopanna",
    "countryAcr": "IND",
    "doublesPosition": 1,
    "doublesPoints": 7820,
    "doublesProgress": 0
  }
]

Response Properties

Property	Type	Description
`id`	integer	Player ID.
`name`	string	Player full name.
`countryAcr`	string	3-letter nationality code.
`doublesPosition`	integer	Current doubles ranking position. The array is sorted ascending by this field.
`doublesPoints`	integer	Total doubles ranking points.
`doublesProgress`	integer	Doubles ranking movement since the last weekly update. Positive = moved up, negative = dropped.

ℹ️

Tip The /tennis/v2/ranking endpoint in the Miscellaneous module returns ranking tier definitions (Grand Slam, Masters 1000, etc.) — not player rankings.