Advanced API

Rankings & Search

Advanced rankings endpoints provide filtered ranking lists, top-500 name lookups, and full player ranking history. The search module supports full-text search across players and tournaments with optional category filtering.

Rankings

ℹ️

Base path: /tennis/v2/ms-api/ranking/...

Endpoint Summary

Method	Path	Description
GET	`.../ranking/{type}`	Full ranking list with filters
GET	`.../ranking/{type}/top`	Top 10 ranked players
GET	`.../ranking/{type}/filters`	Available ranking filter options
GET	`.../ranking/{type}/top500-names`	Formatted name list for top 500 players
GET	`.../ranking/{type}/player/{playerId}/history`	Ranking history for a specific player

Ranking List

GET /tennis/v2/ms-api/ranking/{type} Returns the full ranking list with optional filters and pagination

Path Parameters

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

Query Parameters

Parameter	Type	Description
`page` Optional	number	Page number (default: 1)
`limit` Optional	number	Results per page (default: 100)
`country` Optional	string	Filter by 3-letter country code, e.g. `ESP`

Example Request

cURL

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

Example Response

JSON

{
  "data": [
    {
      "rank": 1,
      "name": "Jannik Sinner",
      "slug": "sinner-jannik",
      "countryAcr": "ITA",
      "points": 9850,
      "rankChange": 0
    },
    {
      "rank": 2,
      "name": "Carlos Alcaraz",
      "slug": "alcaraz-carlos",
      "countryAcr": "ESP",
      "points": 8855,
      "rankChange": 1
    }
  ],
  "total": 500,
  "page": 1
}

Response Properties

Property	Type	Description
`data`	array	Array of ranking entries
`data[].rank`	integer	Current ranking position
`data[].name`	string	Player display name
`data[].slug`	string	Player slug — use in Profile and H2H endpoints
`data[].countryAcr`	string	3-letter country code
`data[].points`	integer	Current ranking points total
`data[].rankChange`	integer	Rank change vs. last week (`+` = moved up, `-` = moved down, `0` = unchanged)
`total`	integer	Total number of ranked players
`page`	integer	Current page

Top 10 Rankings

GET /tennis/v2/ms-api/ranking/{type}/top Returns the current top 10 ranked players for the specified tour

Example Request

cURL

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

Example Response

JSON

[
  {
    "id": "48460885",
    "date": "2026-06-08T00:00:00.000Z",
    "point": 13500,
    "position": 1,
    "player": {
      "name": "Jannik Sinner",
      "countryAcr": "ITA"
    }
  },
  {
    "id": "48460886",
    "date": "2026-06-08T00:00:00.000Z",
    "point": 9960,
    "position": 2,
    "player": {
      "name": "Carlos Alcaraz",
      "countryAcr": "ESP"
    }
  }
]

Response Properties

Property	Type	Description
`id`	string	Ranking entry ID
`date`	string	Ranking date (ISO 8601)
`point`	number	Ranking points
`position`	number	Ranking position
`player`	object	Player information
`player.name`	string	Player name
`player.countryAcr`	string	Country code

Top 500 Formatted Names

GET /tennis/v2/ms-api/ranking/{type}/top500-names Returns a lightweight name lookup list for the top 500 players — useful for autocomplete or mapping IDs to formatted display names

Example Request

cURL

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

Example Response

JSON

[
  {
    "rank": 1,
    "originalName": "Jannik Sinner",
    "formattedName": "jannik_sinner"
  },
  {
    "rank": 2,
    "originalName": "Carlos Alcaraz",
    "formattedName": "carlos_alcaraz"
  },
  {
    "rank": 3,
    "originalName": "Alexander Zverev",
    "formattedName": "alexander_zverev"
  }
]

Response Properties

Property	Type	Description
`rank`	number	Ranking position
`originalName`	string	Original player name
`formattedName`	string	Formatted name (lowercase with underscores)

Player Ranking History

GET /tennis/v2/ms-api/ranking/{type}/player/{playerId}/history Returns the full weekly ranking history for a specific player by their numeric ID

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`playerId` Required	number	Numeric player ID from the rankings or profile endpoint

Example Request

cURL

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

Example Response

JSON

[
  { "date": "2024-07-15", "rank": 2, "points": 8840 },
  { "date": "2024-07-08", "rank": 3, "points": 7680 },
  { "date": "2024-07-01", "rank": 3, "points": 7680 }
]

Response Properties

Property	Type	Description
`date`	string	Week date of the ranking snapshot in `YYYY-MM-DD`
`rank`	integer	World ranking position in that week
`points`	integer	Ranking points total in that week

Ranking Filters

GET /tennis/v2/ms-api/ranking/{type}/filters Returns available filter options for the ranking list — use these values when querying the ranking endpoint

Path Parameters

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

Example Request

cURL

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

Example Response

JSON

{
  "countries": ["ESP", "ITA", "SRB", "USA"],
  "weeks": ["2025-06-09", "2025-06-02", "2025-05-26"]
}

Response Properties

Property	Type	Description
`countries`	array<string>	3-letter country codes available for filtering
`weeks`	array<string>	Available ranking snapshot dates in `YYYY-MM-DD`

Search

ℹ️

Base path: /tennis/v2/ms-api/search/...

Method	Path	Description
GET	`.../search/{query}`	Full-text search across players and tournaments
GET	`.../search/{query}/{category}`	Full-text search filtered by category

Full-Text Search

GET /tennis/v2/ms-api/search/{query} Searches across all entities (ATP players, WTA players, tournaments) and returns ranked matches

Path Parameters

Parameter	Type	Description
`query` Required	string	Search term, e.g. `djok`, `wimbledon`

Example Request

cURL

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

Example Response

JSON

[
  {
    "name": "Carlos Alcaraz",
    "slug": "alcaraz-carlos",
    "category": "atp",
    "countryAcr": "ESP",
    "currentRank": 3
  }
]

Response Properties

Property	Type	Description
`name`	string	Display name of the matched entity
`slug`	string	Slug to use in Profile, H2H, or Tournament endpoints
`category`	string	Entity type: `"atp"`, `"wta"`, or `"tournament"`
`countryAcr`	string \| null	3-letter country code (players only)
`currentRank`	integer \| null	Current world ranking (players only)

Search by Category

GET /tennis/v2/ms-api/search/{query}/{category} Searches within a specific entity category

Path Parameters

Parameter	Type	Description
`query` Required	string	Search term
`category` Required	string	Entity type: `atp`, `wta`, or `tournament`

Example Request

cURL

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

Example Response

JSON

[
  {
    "name": "Caroline Garcia",
    "slug": "garcia-caroline",
    "category": "wta",
    "countryAcr": "FRA",
    "currentRank": 22
  }
]

Returns the same response shape as the full-text search, but only matching the specified category.