1. Home
  2. Head To Head

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

GET/tennis/v2/{tour_type}/h2h/info/{player1_id}/{player2_id}
GET/tennis/v2/{tour_type}/h2h/filter/{player1_id}/{player2_id}
GET/tennis/v2/{tour_type}/h2h/matches/{player1_id}/{player2_id}
GET/tennis/v2/{tour_type}/h2h/stats/{player1_id}/{player2_id}
GET/tennis/v2/{tour_type}/h2h/vs-all-stats/{player_id}
GET/tennis/v2/{tour_type}/h2h/match-stats/{tournamentId}/{player1_id}/{player2_id}

Get H2H Info

GET/tennis/v2/{tour_type}/h2h/info/{player1_id}/{player2_id}
Returns H2H records broken down by court surface. Each record shows the win count for both players on a specific surface.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_idYes
First Player ID (≥ 1).
player2_idYes
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/68074/47275' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Matches

GET/tennis/v2/{tour_type}/h2h/matches/{player1_id}/{player2_id}
Returns the full list of past matches between two players with scores and tournament details.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_idYes
First Player ID (≥ 1).
player2_idYes
Second Player ID (≥ 1).

Query Parameter

ParameterRequiredDescription
includeNo
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
filterNo
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
surfaceNo
Filter by surface: acrylic, hard, clay, grass, I.hard, carpet, clay. Example: surface=hard
pageSizeNo
Results per page. Default: 10. Example: pageSize=10.
pageNoNo
Page number, 1-indexed. Default: 1. Example: pageNo=1. Use hasNextPage in the response to check for more pages.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/matches/68074/47275' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Stats

GET/tennis/v2/{tour_type}/h2h/stats/{player1_id}/{player2_id}
Returns aggregated serve and return statistics comparing the two players over all their meetings.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_idYes
First Player ID (≥ 1).
player2_idYes
Second Player ID (≥ 1).

Query Parameter

ParameterRequiredDescription
surfaceNo
Filter by surface: acrylic, hard, clay, grass, I.hard, carpet, clay. Example: surface=hard
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/stats/68074/47275' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Filter

GET/tennis/v2/{tour_type}/h2h/filter/{player1_id}/{player2_id}
Returns available filter options for an H2H comparison (surfaces, years, rounds, etc.)

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_idYes
First Player ID (≥ 1).
player2_idYes
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);

Response Properties

Returns the distinct filter values present in the two players' H2H match history — used to build filter UI panels.

ParameterTypeDescription
roundsarrayDistinct rounds played: each item is roundId, round.
courtsarrayDistinct court surfaces: each item is courtId, court.
tournamentsarrayDistinct tournaments where matches were played: each item is tournamentId, tournament, tournamentDate.
tournamentRanksarrayDistinct tournament tiers: each item is rankId, rank.
gameYearsarray<number>Distinct calendar years in which matches occurred, sorted descending.

Get H2H Player's Vs All Opponents Stats

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

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_idYes
Player ID (≥ 1). Obtain from the Players module.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/vs-all-stats/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Match Stats in Tournament

GET/tennis/v2/{tour_type}/h2h/match-stats/{tournament_id}/{player1_id}/{player2_id}
Returns detailed per-match statistics for the encounter between two players in a specific tournament.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
tournament_idYes
Tournament ID must be numeric value >= 1
player1_idYes
First Player ID (≥ 1).
player2_idYes
Second Player ID (≥ 1).
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/h2h/match-stats/20340/68074/47275' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player Type

GET/tennis/v2/h2h/playerType/{player_id_or_name}
Retrieve the tour type of a player, indicating whether they compete on the ATP or WTA tour.

Path Parameter

ParameterRequiredDescription
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/playerType/Novak Djokovic' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Profile Data

GET/tennis/v2/h2h/profile/{tour_type}/{player1_id_or_name}/{player2_id_or_name}/{limit}
Retrieve comprehensive profile information for both players in a head-to-head matchup, including rankings, career records, recent form, playing style, season performance, titles, prize money, and surface-specific head-to-head results.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
limitYes
"true" to limit recent matches, "false" for full history

Query Parameter

ParameterRequiredDescription
includeAllYes
Include all historical data. Example: includeAll=false
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/atp/Novak Djokovic/Jannik Sinner/false' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Surface Breakdown

GET/tennis/v2/h2h/surfaceBreakdown/{tour_type}/{player_id_or_name}
Retrieve the head-to-head win/loss breakdown between two players across different court surfaces, including hard, indoor hard, clay, grass, and overall career totals.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/surfaceBreakdown/atp/Novak%20Djokovic' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Statistics

GET/tennis/v2/h2h/stats/{tour_type}/{player1_id_or_name}/{player2_id_or_name}
Retrieve comprehensive head-to-head statistics between two players, including match record, serving and returning performance, break point efficiency, tiebreak results, deciding-set records, first-set trends, tournament-level performance, and surface-specific head-to-head results.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.

Query Parameter

ParameterRequiredDescription
yearNo
Filter to a specific year. Example: year=2026
surfaceNo
Filter by surface: acrylic, hard, clay, grass, I.hard, carpet, clay. Example: surface=hard
tournamentNo
Filter by tournament name. Example: tournament=EFG%20Swiss%20Open%20-%20Gstaad
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/stats/atp/Novak%20Djokovic/Jannik%20Sinner?surface=hard&year=2024' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Filters

GET/tennis/v2/h2h/filters/{player1_id_or_name}/{player2_id_or_name}/{tour_type}
Retrieve all available filter options for head-to-head comparisons, including court surfaces, tournament rounds, competition levels, tournaments, and seasons. Use these values to build valid filter queries for H2H endpoints.

Path Parameter

ParameterRequiredDescription
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
tour_typeYes
Tour category. Allowed values: atp, wta.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/filters/Novak Djokovic/Jannik Sinner/atp' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Upcoming Event

GET/tennis/v2/h2h/upcoming/{tour_type}/{player1_id_or_name}/{player2_id_or_name}
Retrieve the next scheduled match between two players, including match date and time, tournament, round, court surface, player details, and other available event information.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/upcoming/atp/Novak Djokovic/Jannik Sinner' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player's Recent Matches

GET/tennis/v2/h2h/recent/{tour_type}/{player_id_or_name}
Retrieve a player's recent head-to-head matches against a specific opponent, including match results, tournament details, round, court surface, score, and match date.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/recent/atp/Novak Djokovic' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player Vs Player Recent Event

GET/tennis/v2/h2h/player-vs-player/recent-event/{tour_type}/{player1_id_or_name}/{player2_id_or_name}
Retrieve the most recent or upcoming event between two players, including match details, tournament information, player status, recent form, career earnings, and other available head-to-head event data.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/player-vs-player/recent-event/atp/Lorenzo Sonego/Joel Schwaerzler' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player's Recent Stats

GET/tennis/v2/h2h/recent-stats/{tour_type}/{player_id_or_name}
Retrieve a player's recent performance statistics against a specific opponent, including serving and return metrics, break point efficiency, season performance, deciding-set record, and career win/loss records by court surface.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/recent-stats/atp/Carlos Alcaraz' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Breakdown

GET/tennis/v2/h2h/breakdown/{tour_type}/{player_id_or_name}
Retrieve a comprehensive statistical breakdown for a player in head-to-head analysis, including career achievements, tournament performance, surface records, serving and return statistics, match outcomes, tiebreaks, deciding sets, opponent ranking metrics, and year-to-date performance.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/breakdown/Carlos Alcaraz' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Filters Vs

GET/tennis/v2/h2h/filters/{player1_id_or_name}/{player2_id_or_name}/{tour_type}/vs
Retrieve all available filter options for head-to-head player comparisons, including court surfaces, tournament rounds, competition levels, tournaments, and seasons. Use these values to build valid filter queries for player-vs-player H2H endpoints.

Path Parameter

ParameterRequiredDescription
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
tour_typeYes
Tour category. Allowed values: atp, wta.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/filters/Novak Djokovic/Carlos Alcaraz/atp/vs' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player's Last Match Played

GET/tennis/v2/h2h/filters/{tour_type}/{player_id_or_name}
Retrieve a player's most recently completed match against a specific opponent, including the match result, score, tournament, round, and match duration.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/last-match-played/atp/Carlos Alcaraz' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Player's Rivalries

GET/tennis/v2/h2h/rivalries/{tour_type}/{player_id_or_name}
Retrieve a player's biggest head-to-head rivalries, including each opponent's name, head-to-head win/loss record, and total matches played against that opponent.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player_id_or_nameYes
Can be either the player's name or numeric player ID.

Query Parameter

ParameterRequiredDescription
includeAllNo
Include all historical data. Example: includeAll=false
limitNo
Number of rivalries to return (default: 10). Example: limit=10
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/rivalries/atp/Novak Djokovic' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Current Event Stats

GET/tennis/v2/h2h/current/{tour_type}/{player1_id_or_name}/{player2_id_or_name}
Retrieve a player's current head-to-head performance statistics, including recent form, serving efficiency, break point performance, service holds, tiebreak record, match duration, total points won, and average opponent ranking.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/current/atp/Francesco Passaro/Martin Krumich' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H History

GET/tennis/v2/h2h/history/{tour_type}/{player1_id_or_name}/{player2_id_or_name}
Returns a full history of past matches played between two players

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.
player1_id_or_nameYes
Can be either the player's name or numeric player ID.
player2_id_or_nameYes
Can be either the player's name or numeric player ID.

Query Parameter

ParameterRequiredDescription
surfaceNo
Filter by surface: acrylic, hard, clay, grass, I.hard, carpet, clay. Example: surface=hard
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/h2h/history/atp/Novak Djokovic/Carlos Alcaraz?surface=hard' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Get H2H Interesting Matchup

GET/tennis/v2/interesting-h2h/{tour_type}
Retrieves the most interesting potential head-to-head matchups based on the current potential fixtures. Each result includes both players, their career head-to-head record, and the tour where the matchup could occur.

Path Parameter

ParameterRequiredDescription
tour_typeYes
Tour category. Allowed values: atp, wta.

Query Parameter

ParameterRequiredDescription
includeAllNo
Include all historical data. Example: includeAll=false
topNo
Maximum number of top potential matchups to return. Example: top=10
pageNo
Page number (default: 1). Example: page=1
limitNo
Number of rivalries to return (default: 10). Example: limit=10
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/interesting-h2h/atp' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'