API Reference

Head-to-Head (H2H)

The H2H module delivers rivalry records, match histories, per-match statistics, and aggregate comparisons between any two players — or between one player and all their opponents.

Endpoint Summary

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

H2H Info

GET/tennis/v2/{type}/h2h/info/{player1}/{player2}

Returns H2H records broken down by court surface. Each record shows the win count for both players on a specific surface.

Path Parameter

Parameter	Type
`type`Required	string
"atp" or "wta"
`player1`Required	string
First player ID (≥ 1). Non-numeric, zero, or negative IDs return "400 Bad Request"
`player2`Required	string
Second player ID (≥ 1). Non-numeric, zero, or negative IDs return "400 Bad Request"

Example Request: JAVASCRIPT

const response = await fetch("https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/info/68074/47275", {
   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);

Example Response: JSON

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

Response Properties

Parameter	Type	Description
`courtId`	integer	Court surface ID (1=Hard, 2=Clay, 3=Indoor Hard, 5=Grass, etc.).
`court`	string	Court surface name (e.g. `"Hard"`, `"Clay"`, `"I.hard"`, `"Grass"`).
`player1wins`	string	Number of wins for player1 on this surface (as string).
`player2wins`	string	Number of wins for player2 on this surface (as string).

H2H Matches

GET/tennis/v2/type/h2h/matches/player1/player2Returns 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:20340` — filter by specific tournament ID(s) Example: `filter=GameYear:2024,2025;TourRank:1`
`surface` Optional	string	Filter by court surface. Valid values: `hard`, `clay`, `grass`, `carpet`. Invalid values return a `400 Bad Request`.
`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/68074/47275' \
-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",
      "best_of": "3",
      "odd1": "1.45",
      "odd2": "2.80",
      "player1Id": 68074,
      "player2Id": 47275,
      "tournamentId": 8201,
      "roundId": 1,
      "player1": {
        "id": 68074,
        "name": "Carlos Alcaraz",
        "countryAcr": "ESP"
      },
      "player2": {
        "id": 47275,
        "name": "Jannik Sinner",
        "countryAcr": "ITA"
      }
    }
  ],
  "hasNextPage": false
}

Response Properties

Property	Type	Description
`data`	array	Paginated list of historical match records, most recent first.
`hasNextPage`	boolean	`true` if more matches exist beyond the current page.
`id`	string	Match record ID (as string).
`date`	datetime	Match date as ISO 8601 UTC.
`roundId`	integer	Round ID (1 = Final, 2 = SF, 3 = QF, etc.).
`player1Id` / `player2Id`	integer	Player IDs as specified in the request (not necessarily winner/loser order).
`tournamentId`	integer	Foreign key to Tournament table.
`match_winner`	integer	Player ID of the match winner.
`result`	string	Score string, e.g. `"6-4 6-3"`. Set scores space-separated.
`result_type`	string	Match status: `"completed"` for finished matches.
`best_of`	integer \| null	Match format: `3` (best-of-3) or `5` (best-of-5). Grand Slams use 5 for men. `null` when not recorded.
`odd1` / `odd2`	string \| null	Pre-match decimal odds for player1 / player2 respectively. `null` when unavailable.
`player1` / `player2`	object	`id, name, countryAcr`.
`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.

H2H Stats

GET/tennis/v2/type/h2h/stats/player1/player2Returns 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). Non-numeric, zero, or negative IDs return `400 Bad Request`.
`player2` Required	integer	Second player ID (≥ 1). Non-numeric, zero, or negative IDs return `400 Bad Request`.

Query Parameters

Parameter	Type	Description
`surface` Optional	string	Filter by court surface. Valid values: `hard`, `clay`, `grass`, `carpet`. Invalid values return a `400 Bad Request`.

Example Request: CURL

curl -G 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/stats/68074/47275' \
-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": 68074,
      "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.

H2H Filter

GET/tennis/v2/{type}/h2h/filter/{player1Id}/{player2Id}

Returns available filter options for an H2H comparison (surfaces, years, rounds, etc.)

Path Parameter

Parameter	Type
`type`Required	string
"atp" or "wta"
`player1Id`Required	integer
First player ID (≥ 1)
`player2Id`Required	integer
Second player ID (≥ 1)

Example Request: JAVASCRIPT

const response = await fetch("https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/filter/68074/47275", {
   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);

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": 20340,
        "tournament": "French Open - Paris",
        "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.

Parameter	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.

H2H vs All Opponents

GET/tennis/v2/type/h2h/vs-all-stats/playerReturns 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/68074' \
-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`.

Match Stats in Tournament

GET/tennis/v2/type/h2h/match-stats/tournamentId/player1/player2Returns 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 percentagesfirstServe1 / 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/20340/68074/47275' \
-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.