Players

Method	Path	Description
GET	`/tennis/v2/{type}/player`	List all players
GET	`/tennis/v2/{type}/player/profile/{id}`	Player profile
GET	`/tennis/v2/{type}/player/titles/{id}`	Player titles
GET	`/tennis/v2/{type}/player/filter/{id}`	Player filter categories
GET	`/tennis/v2/{type}/player/match-stats/{id}`	Match statistics
GET	`/tennis/v2/{type}/player/past-matches/{id}`	Past match results
GET	`/tennis/v2/{type}/player/surface-summary/{id}`	Surface performance summary
GET	`/tennis/v2/{type}/player/perf-breakdown/{id}`	Performance breakdown
GET	`/tennis/v2/{type}/player/finals/{id}`	Finals results
GET	`/tennis/v2/{type}/player/intersting-h2h/{id}`	Interesting H2H matchups

GET /tennis/v2/{type}/player Returns a list of all players in the selected tour

The Player entity serves a dual purpose — it is both a profile record and a live ranking snapshot. Fields are updated whenever ATP/WTA publish their official weekly ranking lists.

Path Parameters

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

Query Parameters

Parameter	Type	Description
`include` Optional	string	Comma-separated relations to load. Available: `country` — adds full country object to each player. Example: `include=country`
`filter` Optional	string	Semicolon-separated filters in `Key:value` format. Available filters: `PlayerGroup:singles` \| `doubles` \| `both` `PlayerCountry:{ESP,ITA}` — filter by 3-letter country acronym Example: `filter=PlayerGroup:singles;PlayerCountry:ESP,ITA`
`pageSize` Optional	integer	Results per page. Default: `10`.
`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/player' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

[
  {
    "id": 104925,
    "name": "Carlos Alcaraz",
    "countryAcr": "ESP",
    "currentRank": 3,
    "points": 8855,
    "progress": 0
  },
  {
    "id": 106421,
    "name": "Jannik Sinner",
    "countryAcr": "ITA",
    "currentRank": 1,
    "points": 11330,
    "progress": 0
  }
]

Response Properties

Property	Type	Description
`id`	integer	Unique player identifier. Stable across all endpoints — use this to join fixtures, H2H, and stats.
`name`	string	Full player name as used in official ATP/WTA records.
`countryAcr`	string \| null	3-letter nationality code (e.g. `ESP`, `ITA`). Represents the player's nationality for ranking purposes.
`currentRank`	integer \| null	Current singles world ranking position. `null` for unranked players.
`points`	integer \| null	Total ATP/WTA ranking points — the aggregate used to determine `currentRank`.
`progress`	integer \| null	Ranking change since the last official weekly update. Positive = moved up, negative = dropped, `0` = unchanged.

GET /tennis/v2/{type}/player/profile/{id} Returns full profile details for a single player including ranking, surface breakdown, and extended biographical data

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Query Parameters

Parameter	Type	Description
`include` Optional	string	Comma-separated extras to load. Available: `form` — appends recent form as a `form` array (e.g. `["w","l","w"]`) `ranking` — appends `curRank` and `bestRank` objects with ranking history data `country` — appends a full `country` object (name, acronym, flag) to the player Example: `include=form,ranking,country`

Example Request

cURL

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

Example Response

JSON

{
  "id": 104925,
  "name": "Carlos Alcaraz",
  "birthday": "2003-05-05T00:00:00.000Z",
  "countryAcr": "ESP",
  "height": 185,
  "wikidata_id": "Q105513",
  "currentRank": 3,
  "progress": 0,
  "points": 8855,
  "ch": 1,
  "hardPoints": 4500,
  "hardTournament": 12,
  "ihardPoints": null,
  "ihardTournament": null,
  "clayPoints": 3200,
  "clayTournament": 8,
  "grassPoints": 1155,
  "grassTournament": 3,
  "carpetPoints": null,
  "carterTournament": null,
  "doublesPosition": null,
  "doublesPoints": null,
  "doublesProgress": null,
  "prize": 35200000,
  "itf": null,
  "ep": {
    "turnedPro": "2018",
    "plays": "Right-Handed, Two-Handed Backhand",
    "coach": "Juan Carlos Ferrero",
    "birthplace": "El Palmar, Spain",
    "residence": "Murcia, Spain",
    "weight": "185 lbs. (84 kg)",
    "playerStatus": "Active",
    "twitter": "carlitosalcaraz",
    "instagram": "carlosalcaraz",
    "facebook": null,
    "site": null,
    "page": "https://www.atptour.com/en/players/carlos-alcaraz/a0e2/overview",
    "last_revised": "2025-01-15"
  }
}

Response Properties — Core Player Fields

Property	Type	Description
`id`	integer	Unique player ID. Stable across all endpoints.
`name`	string	Full name as used in official ATP/WTA records.
`birthday`	datetime \| null	Date of birth as ISO 8601 timestamp (time part is always midnight UTC — treat as date-only).
`countryAcr`	string \| null	3-letter nationality code for ranking purposes (e.g. `ESP`, `ITA`).
`height`	integer \| null	Player height in centimetres (e.g. `185` = 6'1").
`wikidata_id`	string \| null	Wikidata entity ID (e.g. `Q105513`). Use to enrich data from wikidata.org — player photos, multi-language Wikipedia links, biographical data.
`currentRank`	integer \| null	Current singles ranking position. `null` for unranked players.
`progress`	integer \| null	Singles ranking change since last weekly update. Positive = moved up, negative = dropped.
`points`	integer \| null	Total singles ranking points.
`ch`	integer \| null	Career High — the best singles ranking this player has ever achieved.
`hardPoints` / `hardTournament`	integer \| null	Ranking points earned on outdoor hard court / number of hard-court tournaments played this cycle.
`ihardPoints` / `ihardTournament`	integer \| null	Points and events on indoor hard court. Tracked separately (e.g. Australian Open = outdoor hard; ATP Finals = indoor hard).
`clayPoints` / `clayTournament`	integer \| null	Points and events on clay.
`grassPoints` / `grassTournament`	integer \| null	Points and events on grass.
`carpetPoints` / `carterTournament`	integer \| null	Points and events on carpet. Note: `carterTournament` is a spelling inconsistency in the database (should be `carpetTournament`).
`doublesPosition`	integer \| null	Current doubles ranking position.
`doublesPoints`	integer \| null	Total doubles ranking points.
`doublesProgress`	integer \| null	Doubles ranking movement since last update.
`prize`	integer \| null	Cumulative career prize money in USD as an integer (e.g. `35200000` = $35.2M).
`itf`	integer \| null	ITF world ranking. Primarily relevant for junior or lower-tier players before achieving an ATP/WTA ranking.

Response Properties — Extended Profile (`ep` object)

The ep field contains biographical and social media data from the Extended Profile table. It may be null if no extended data exists for the player.

Property	Type	Description
`turnedPro`	string	Year the player turned professional (e.g. `"2018"`).
`plays`	string	Playing hand — e.g. `"Right-Handed"`, `"Left-Handed"`, `"Right-Handed, Two-Handed Backhand"`.
`coach`	string	Name of the player's current coach.
`birthplace`	string	City and country of birth (e.g. `"El Palmar, Spain"`).
`residence`	string	Current city of residence.
`weight`	string	Player weight as a formatted string (e.g. `"185 lbs. (84 kg)"`).
`playerStatus`	string	Career status — `"Active"` for active players, `"Inactive"` for retired.
`twitter`	string \| null	Twitter/X handle without the @ prefix. `null` if unavailable.
`instagram`	string \| null	Instagram handle without the @ prefix.
`facebook`	string \| null	Facebook page identifier.
`site`	string \| null	Official personal website URL.
`page`	string \| null	Link to the player's official ATP or WTA profile page.
`last_revised`	string	Date this extended profile record was last updated.

GET /tennis/v2/{type}/player/titles/{id} Returns all tournament titles won by a player

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/titles/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    { "tourRankId": "1", "tourRank": "Grand Slam", "titlesWon": "3", "titlesLost": "1" },
    { "tourRankId": "3", "tourRank": "Masters 1000", "titlesWon": "8", "titlesLost": "4" }
  ]
}

Response Properties

Property	Type	Description
`tourRankId`	string	Tournament tier ID (as a string). Cross-reference with Ranking Tiers.
`tourRank`	string	Name of the tournament tier (e.g. `"Grand Slam"`, `"Masters 1000"`).
`titlesWon`	string	Number of finals won (titles) at this tier level.
`titlesLost`	string	Number of finals lost (runner-up appearances) at this tier level.

GET /tennis/v2/{type}/player/match-stats/{id} Returns aggregated match statistics for a player (win/loss records, ace counts, break point stats, etc.)

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/match-stats/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": {
    "serviceStats": {
      "acesGm": 823,
      "doubleFaultsGm": 245,
      "firstServeGm": 4521,
      "firstServeOfGm": 6102,
      "winningOnFirstServeGm": 3218,
      "winningOnFirstServeOfGm": 4521,
      "winningOnSecondServeGm": 1055,
      "winningOnSecondServeOfGm": 1581
    },
    "rtnStats": {
      "acesGm": 312,
      "doubleFaultsGm": 198,
      "firstServeGm": 3410,
      "firstServeOfGm": 5018,
      "winningOnFirstServeGm": 1820,
      "winningOnFirstServeOfGm": 3410,
      "winningOnSecondServeGm": 780,
      "winningOnSecondServeOfGm": 1250
    },
    "breakPointsServeStats": {
      "breakPointFacedGm": 310,
      "breakPointSavedGm": 187
    },
    "breakPointsRtnStats": {
      "breakPointChanceGm": 298,
      "breakPointWonGm": 142
    }
  }
}

Response Properties

Aggregated career serve/return statistics across all matches with stat records. All Gm-suffixed fields are raw totals (not percentages) — divide firstServeGm / firstServeOfGm × 100 to compute the career first-serve percentage.

Property	Type	Description
`serviceStats.acesGm`	integer \| null	Career total aces served.
`serviceStats.doubleFaultsGm`	integer \| null	Career total double faults served.
`serviceStats.firstServeGm` / `firstServeOfGm`	integer \| null	First serves in / total first serve attempts. Divide for first-serve % (e.g. 4521/6102 = 74%).
`serviceStats.winningOnFirstServeGm` / `winningOnFirstServeOfGm`	integer \| null	Points won on first serve / first-serve points played.
`serviceStats.winningOnSecondServeGm` / `winningOnSecondServeOfGm`	integer \| null	Points won on second serve / second-serve points played.
`rtnStats.*`	integer \| null	Same fields as `serviceStats` but computed from the player's perspective when returning (opponent serving).
`breakPointsServeStats.breakPointFacedGm`	integer \| null	Total break points faced on serve across all matches.
`breakPointsServeStats.breakPointSavedGm`	integer \| null	Break points saved — i.e. `breakPointFacedGm` minus breaks conceded.
`breakPointsRtnStats.breakPointChanceGm`	integer \| null	Total break point opportunities earned while returning.
`breakPointsRtnStats.breakPointWonGm`	integer \| null	Break points converted. Divide by `breakPointChanceGm` for conversion rate.

GET /tennis/v2/{type}/player/past-matches/{id} Returns completed match results for a player, most recent first

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Query Parameters

Parameter	Type	Description
`include` Optional	string	Comma-separated relations to load. Available: `round`, `tournament`, `tournament.court`, `tournament.rank`, `tournament.country`, `stat` (per-match serve & return stats). Example: `include=round,tournament.court,stat`
`filter` Optional	string	Semicolon-separated filters in `Key:value` format. Available filters: `GameYear:{2024,2025}` — filter by year(s) `GameRound:{1,2}` — filter by round ID(s) `GameCourt:{1,2}` — filter by court ID(s), requires `tournament` in `include` `TourRank:{1,2}` — filter by tournament rank ID(s), requires `tournament` in `include` `GameTour:{8871}` — filter by tournament ID(s) Example: `filter=GameYear:2025;GameRound:1,2`
`pageSize` Optional	integer	Results per page. Default: `10`.
`pageNo` Optional	integer	Page number, 1-indexed. Default: `1`. Use `hasNextPage` in the response to check for more pages.

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/past-matches/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    {
      "id": 390145,
      "date": "2025-06-08T00:00:00.000Z",
      "result": "6-3 6-2 6-4",
      "player1Id": 104925,
      "player2Id": 106421,
      "tournamentId": 8871,
      "roundId": 1,
      "player1": { "id": 104925, "name": "Carlos Alcaraz", "countryAcr": "ESP" },
      "player2": { "id": 106421, "name": "Jannik Sinner", "countryAcr": "ITA" },
      "tournament": { "id": 8871, "name": "Roland Garros", "courtId": 2, "rankId": 1 }
    }
  ],
  "hasNextPage": false
}

Response Properties

Property	Type	Description
`data`	array	Paginated list of past match records for this player, most recent first.
`hasNextPage`	boolean	`true` if more results exist. Use `pageNo` query parameter to paginate.
`id`	integer	Match record ID.
`date`	datetime	Match date as ISO 8601 UTC.
`result`	string	Score string (e.g. `"6-3 6-2 6-4"`). Space-separated set scores.
`player1Id` / `player2Id`	integer	`player1` is always the winner in historical archive data.
`player1` / `player2`	object	`{ id, name, countryAcr }`.
`tournamentId`	integer	Foreign key to Tournament table.
`tournament`	object \| null	Embedded tournament: `{ id, name, courtId, rankId, date, countryAcr, court, rank }`.
`roundId`	integer	Round ID (1 = Final, 2 = SF, 3 = QF, etc.).

GET /tennis/v2/{type}/player/surface-summary/{id} Returns win/loss records broken down by court surface (hard, clay, grass, carpet, indoor hard)

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/surface-summary/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    {
      "year": "2025",
      "surfaces": [
        { "courtId": 1, "court": "Hard", "courtWins": "21", "courtLosses": "4" },
        { "courtId": 2, "court": "Clay", "courtWins": "12", "courtLosses": "2" }
      ]
    },
    {
      "year": "2024",
      "surfaces": [ "..." ]
    }
  ]
}

Response Properties

Property	Type	Description
`year`	string	Calendar year (as a string, e.g. `"2025"`). Results sorted most recent year first.
`surfaces`	array	Win/loss breakdown by surface for that year. One entry per surface type the player competed on.
`surfaces[].courtId`	integer	Surface type ID. Cross-reference with Courts lookup.
`surfaces[].court`	string	Surface name: `"Hard"`, `"Clay"`, `"Grass"`, `"Indoor Hard"`, `"Carpet"`.
`surfaces[].courtWins`	string	Matches won on this surface in this year.
`surfaces[].courtLosses`	string	Matches lost on this surface in this year.

GET /tennis/v2/{type}/player/perf-breakdown/{id} Returns granular performance metrics including serve, return, and pressure statistics

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/perf-breakdown/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Response Properties

Returns { data: {...} } where data is a parsed JSON blob stored in the PlayerStat table. The exact field set varies by player and data source. The object typically contains detailed serve/return performance metrics, pressure statistics, and situational win rates — similar in structure to the H2H Stats response. Returns { data: null } if no performance data is available for the player.

GET /tennis/v2/{type}/player/finals/{id} Returns all finals appearances (won and lost) for a player

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Query Parameters

Parameter	Type	Description
`filter` Optional	string	Semicolon-separated filters in `Key:value` format. Available filters: `GameYear:{2024,2025}` — filter by year(s) `GameRound:{1,2}` — filter by round ID(s) `GameCourt:{1,2}` — requires `tournament` in `include` `TourRank:{1,2}` — requires `tournament` in `include` `GameTour:{8871}` — filter by tournament ID(s) Example: `filter=GameYear:2024,2025;TourRank:1`

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/finals/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Response Properties

Returns { data: [...] } — same match record structure as Past Matches. Only final-round matches are included (roundId = 12 for standard events, roundId = 16 for Tour Finals round-robin). Includes tournament prize field and optional country object for the host nation.

GET /tennis/v2/{type}/player/intersting-h2h/{id} Returns notable head-to-head records for a player (most wins, biggest rivals, etc.)

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/intersting-h2h/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    {
      "id": 8802,
      "player1Wins": 5,
      "player2Wins": 8,
      "player1AllWins": 5,
      "player2AllWins": 8,
      "player1Id": 104925,
      "player2Id": 106421,
      "player1": { "id": 104925, "name": "Carlos Alcaraz", "countryAcr": "ESP", "wins": 5 },
      "player2": { "id": 106421, "name": "Jannik Sinner", "countryAcr": "ITA", "wins": 8 }
    }
  ]
}

Response Properties

Returns up to 12 H2H records ranked by total matches played (most contested rivalries first). The requested player always appears as either player1 or player2.

Property	Type	Description
`id`	integer	H2H record ID in the database.
`player1AllWins`	integer	All-time career wins for player1 against player2.
`player2AllWins`	integer	All-time career wins for player2 against player1.
`player1Wins`	integer	Recent-subset wins for player1 (last 5–10 matches).
`player2Wins`	integer	Recent-subset wins for player2.
`player1Id` / `player2Id`	integer	Player IDs for each side of the rivalry.
`player1` / `player2`	object	Embedded player summary: `{ id, name, countryAcr, wins }`. The `wins` field shows that player's all-time win count against the other.

GET /tennis/v2/{type}/player/filter/{id} Returns available filter categories and metadata for a player (used to build UI filter panels)

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`id` Required	integer	Player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/filter/104925' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": {
    "rounds": [
      { "roundId": 1, "round": "Final" },
      { "roundId": 2, "round": "Semi-Final" }
    ],
    "courts": [
      { "courtId": 1, "court": "Hard" },
      { "courtId": 2, "court": "Clay" }
    ],
    "tournaments": [
      { "tournamentId": 8871, "tournament": "Roland Garros", "tournamentDate": "2025-05-26T00:00:00.000Z" }
    ],
    "tournamentRanks": [
      { "rankId": 1, "rank": "Grand Slam" }
    ],
    "gameYears": [ 2025, 2024, 2023 ]
  }
}

Response Properties

Returns the distinct filter values available in this player's match history — typically used to populate filter UI dropdowns.

Property	Type	Description
`rounds`	array	Distinct rounds reached. Each item: `{ roundId, round }`.
`courts`	array	Distinct court surfaces played on. Each item: `{ courtId, court }`.
`tournaments`	array	All tournaments this player has competed in. Each item: `{ tournamentId, tournament, tournamentDate }`.
`tournamentRanks`	array	Distinct tournament tier levels. Each item: `{ rankId, rank }`.
`gameYears`	array<number>	All years in which this player has match records, sorted descending.

Endpoint Summary

List All Players

Path Parameters

Query Parameters

Example Request

Example Response

Response Properties

Player Profile

Path Parameters

Query Parameters

Example Request

Example Response

Response Properties — Core Player Fields

Response Properties — Extended Profile (ep object)

Player Titles

Path Parameters

Example Request

Example Response

Response Properties

Match Statistics

Path Parameters

Example Request

Example Response

Response Properties

Past Matches

Path Parameters

Query Parameters

Example Request

Example Response

Response Properties

Surface Summary

Path Parameters

Example Request

Example Response

Response Properties

Performance Breakdown

Path Parameters

Example Request

Response Properties

Finals

Path Parameters

Query Parameters

Example Request

Response Properties

Interesting H2H

Path Parameters

Example Request

Example Response

Response Properties

Player Filter

Path Parameters

Example Request

Example Response

Response Properties

Response Properties — Extended Profile (`ep` object)