Head-to-Head — Tennis API Documentation

Method	Path	Description
GET	`/tennis/v2/{type}/h2h/info/{player1}/{player2}`	H2H summary info
GET	`/tennis/v2/{type}/h2h/filter/{player1}/{player2}`	H2H filter options
GET	`/tennis/v2/{type}/h2h/matches/{player1}/{player2}`	Full match list
GET	`/tennis/v2/{type}/h2h/stats/{player1}/{player2}`	Aggregated H2H stats
GET	`/tennis/v2/{type}/h2h/vs-all-stats/{player}`	Stats vs all opponents
GET	`/tennis/v2/{type}/h2h/match-stats/{tournamentId}/{player1}/{player2}`	Match stats in a tournament

GET /tennis/v2/{type}/h2h/info/{player1}/{player2} Returns the overall head-to-head win/loss summary between two players

Returns a single H2H record from the pre-computed win-totals table. Totals are kept in sync as new match results are added to the archive.

ℹ️

Automatic player-order correction H2H records are stored with a fixed player1/player2 assignment. When you request /h2h/info/A/B but the record is stored as B→A, the API automatically swaps player1AllWins and player2AllWins so the response always aligns with the order you requested.

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`player1` Required	integer	First player ID (≥ 1)
`player2` Required	integer	Second player ID (≥ 1)

Example Request

cURL

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

Example Response

JSON

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

Response Properties

Property	Type	Description
`id`	integer	Internal record ID for this H2H pair in the database.
`player1AllWins`	integer	All-time career wins for player1 against player2 across the entire match archive.
`player2AllWins`	integer	All-time career wins for player2 against player1.
`player1Wins`	integer	Wins by player1 in a recent subset of their meetings (e.g. last 5–10 matches). Use this for "recent form" H2H displays alongside `player1AllWins`.
`player2Wins`	integer	Wins by player2 in the same recent subset.
`player1Id` / `player2Id`	integer	Player IDs as returned from the API (already aligned to your requested order after the swap logic).
`player1` / `player2`	object	Embedded player summary: `{ id, name, countryAcr }`.

GET /tennis/v2/{type}/h2h/matches/{player1}/{player2} Returns the full list of past matches between two players with scores and tournament details

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`player1` Required	integer	First player ID (≥ 1)
`player2` Required	integer	Second 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 statistics). Example: `include=round,tournament.court`
`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 specific tournament ID(s) Example: `filter=GameYear:2024,2025;TourRank:1`
`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/h2h/matches/104925/106421' \
  -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": "2024-11-17T14:00:00.000Z",
      "result": "6-4 6-3",
      "player1Id": 104925,
      "player2Id": 106421,
      "tournamentId": 8201,
      "roundId": 1,
      "player1": { "id": 104925, "name": "Carlos Alcaraz", "countryAcr": "ESP" },
      "player2": { "id": 106421, "name": "Jannik Sinner", "countryAcr": "ITA" }
    }
  ],
  "hasNextPage": false
}

Response Properties

Property	Type	Description
`data`	array	Paginated list of historical match records, most recent first. In each record `player1` is always the winner.
`hasNextPage`	boolean	`true` if more matches exist beyond the current page.
`id`	integer	Match record ID.
`date`	datetime	Match date as ISO 8601 UTC.
`result`	string	Score string, e.g. `"6-4 6-3"`. Set scores space-separated.
`player1Id` / `player2Id`	integer	Player IDs. `player1` = winner, `player2` = loser in historical archive.
`player1` / `player2`	object	`{ id, name, countryAcr }`.
`tournamentId`	integer	Foreign key to Tournament table.
`roundId`	integer	Round ID (1 = Final, 2 = SF, 3 = QF, etc.).
`tournament`	object \| null	Embedded tournament: `{ id, name, courtId, rankId, court, rank }`. Present when loaded via `include`.
`round`	object \| null	`{ id, name }`. Present when `round` is included.

GET /tennis/v2/{type}/h2h/stats/{player1}/{player2} Returns aggregated serve and return statistics comparing the two players over all their meetings

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`player1` Required	integer	First player ID (≥ 1)
`player2` Required	integer	Second player ID (≥ 1)

Example Request

cURL

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

Example Response

JSON

{
  "data": {
    "matchesCount": 13,
    "player1Stats": {
      "id": 104925,
      "statMatchesPlayed": "13",
      "matchesWon": "5",
      "aces": "143",
      "doubleFaults": "38",
      "firstServePercentage": 63,
      "winningOnFirstServePercentage": 72,
      "winningOnSecondServePercentage": 48,
      "breakpointsWonPercentage": 41,
      "bestOfThreeWon": 5,
      "bestOfFiveWon": 0,
      "decidingSetWin": 2,
      "tiebreakWon": 4,
      "setsWon": 18,
      "gamesWon": 152,
      "hard": 3,
      "clay": 2,
      "grass": 0
    },
    "player2Stats": { "..." }
  }
}

Response Properties

The response contains player1Stats and player2Stats objects — both have identical fields. All percentage fields are pre-computed as integer values (0–100).

Property	Type	Description
`matchesCount`	integer	Total number of matches played between the two players in the archive.
`player1Stats.id`	integer	The player ID for player1.
`statMatchesPlayed`	string	Number of matches with stats data available (may differ from `matchesCount` if some matches have no stat records).
`matchesWon`	string	Total matches won in the head-to-head.
`aces`	string	Total aces across all H2H matches.
`doubleFaults`	string	Total double faults across all H2H matches.
`firstServePercentage`	integer	Average first serve in percentage (0–100).
`winningOnFirstServePercentage`	integer	Percentage of points won when the first serve went in.
`winningOnSecondServePercentage`	integer	Percentage of points won on second serve.
`breakpointsWonPercentage`	integer	Break point conversion rate as a percentage.
`bestOfThreeWon` / `bestOfFiveWon`	integer	Number of best-of-3 / best-of-5 matches won in H2H.
`decidingSetWin`	integer	Matches won after winning the final deciding set.
`tiebreakWon`	integer	Total tiebreaks won across all H2H matches.
`setsWon`	integer	Total sets won across all H2H matches.
`gamesWon`	integer	Total games won across all H2H matches.
`hard` / `clay` / `grass` / `iHard`	integer	Number of H2H matches won on each surface type.
`title`	integer	Number of H2H matches won in tournament finals (round 12).
`grandSlam` / `masters`	integer	H2H wins at Grand Slams / Masters 1000 level.
`firstSetWinMatchWin`	integer	Times this player won the first set AND won the match.
`firstSetLoseMatchWin`	integer	Times this player lost the first set but came back to win the match.
`avgTime`	string	Average match duration in `H:MM:SS` format.

GET /tennis/v2/{type}/h2h/filter/{player1}/{player2} Returns available filter options for an H2H comparison (surfaces, years, rounds, etc.)

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`player1` Required	integer	First player ID (≥ 1)
`player2` Required	integer	Second player ID (≥ 1)

Example Request

cURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/filter/104925/106421' \
  -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 present in the two players' H2H match history — used to build filter UI panels.

Property	Type	Description
`rounds`	array	Distinct rounds played: each item is `{ roundId, round }`.
`courts`	array	Distinct court surfaces: each item is `{ courtId, court }`.
`tournaments`	array	Distinct tournaments where matches were played: each item is `{ tournamentId, tournament, tournamentDate }`.
`tournamentRanks`	array	Distinct tournament tiers: each item is `{ rankId, rank }`.
`gameYears`	array<number>	Distinct calendar years in which matches occurred, sorted descending.

GET /tennis/v2/{type}/h2h/vs-all-stats/{player} Returns a player's win/loss record and stats against every opponent they have ever faced

Path Parameters

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

Example Request

cURL

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

Response Properties

Returns { data: { matchesCount, playerStats, opponentStats } }. The structure is identical to H2H Stats except the keys are playerStats (for the requested player) and opponentStats (aggregate across all opponents) instead of player1Stats / player2Stats.

Property	Type	Description
`matchesCount`	integer	Total matches played by this player across the entire historical archive.
`playerStats`	object	Aggregated stats for the requested player across all matches. Same fields as `player1Stats` in H2H Stats.
`opponentStats`	object	Aggregate of all opponents faced — useful for computing career averages against the field. Same field structure as `playerStats`.

GET /tennis/v2/{type}/h2h/match-stats/{tournamentId}/{player1}/{player2} Returns detailed per-match statistics for the encounter between two players in a specific tournament

This endpoint returns data from the Stat entity — the richest data structure in the API. All numeric stat fields follow a fraction pattern: the base field is the count achieved, and the Of-suffixed field is the total opportunities. Divide them to compute a percentage.

✅

Computing percentages firstServe1 / firstServeOf1 × 100 gives the first-serve percentage for player1. All fraction field pairs work this way.

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`tournamentId` Required	integer	Tournament ID (≥ 1)
`player1` Required	integer	First player ID (≥ 1)
`player2` Required	integer	Second player ID (≥ 1)

Example Request

cURL

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

Example Response

JSON

{
  "round": 1,
  "mt": "best_of_5",
  "w_SvGms": "9",
  "aces1": 12,
  "aces2": 4,
  "doubleFaults1": 2,
  "doubleFaults2": 3,
  "firstServe1": 65,
  "firstServeOf1": 90,
  "firstServe2": 58,
  "firstServeOf2": 85,
  "winningOnFirstServe1": 52,
  "winningOnFirstServeOf1": 65,
  "breakPointsConverted1": 3,
  "breakPointsConvertedOf1": 7,
  "winners1": 38,
  "winners2": 22,
  "unforcedErrors1": 18,
  "unforcedErrors2": 31,
  "totalPointsWon1": 112,
  "totalPointsWon2": 89,
  "fastestServe1": 214,
  "fastestServe2": 208
}

Response Properties

All stat fields come in pairs suffixed 1 (player1) and 2 (player2). Fraction fields have a companion Of field as the denominator — divide them to get percentages.

Property	Type	Description
`round`	integer	Round ID for this match (same values as the Round lookup table).
`mt`	string \| null	Match type — `"best_of_3"` or `"best_of_5"`. Grand Slams use best-of-5 for men.
`w_SvGms`	string \| null	Number of service games held by the winner (e.g. `"9"`). Compact summary field.
`aces1` / `aces2`	integer \| null	Total aces served in the match by each player.
`doubleFaults1` / `doubleFaults2`	integer \| null	Total double faults served by each player.
`firstServe1` / `firstServeOf1`	integer \| null	First serves landed in / total first serve attempts. E.g. `65/90` → 72% first-serve percentage.
`winningOnFirstServe1` / `winningOnFirstServeOf1`	integer \| null	Points won on first serve / total first-serve points played.
`winningOnSecondServe1` / `winningOnSecondServeOf1`	integer \| null	Points won on second serve / total second-serve points played.
`fastestServe1` / `fastestServe2`	integer \| null	Fastest serve speed recorded in the match (km/h or mph depending on tournament data source).
`averageFirstServeSpeed1`	integer \| null	Average speed of all first serves.
`averageSecondServeSpeed1`	integer \| null	Average speed of all second serves.
`breakPointsConverted1` / `breakPointsConvertedOf1`	integer \| null	Break points converted / total break point opportunities. Divide for break-point conversion rate.
`rpw1` / `rpwOf1`	integer \| null	Return Points Won — points won while returning (on the opponent's serve) / total return points played.
`netApproaches1` / `netApproachesOf1`	integer \| null	Points won coming to the net / total net approach attempts.
`winners1` / `winners2`	integer \| null	Total outright winners hit (unreturnable shots).
`unforcedErrors1` / `unforcedErrors2`	integer \| null	Total unforced errors made (mistakes not due to opponent pressure).
`totalPointsWon1` / `totalPointsWon2`	integer \| null	Total points won across all games and sets in the match.

Head-to-Head (H2H)

Endpoint Summary

H2H Info

Path Parameters

Example Request

Example Response

Response Properties

H2H Matches

Path Parameters

Query Parameters

Example Request

Example Response

Response Properties

H2H Stats

Path Parameters

Example Request

Example Response

Response Properties

H2H Filter

Path Parameters

Example Request

Example Response

Response Properties

H2H vs All Opponents

Path Parameters

Example Request

Response Properties

Match Stats in Tournament

Path Parameters

Example Request

Example Response

Response Properties