Advanced API

H2H Advanced

The H2H Advanced module provides deep head-to-head analytics between two players — including aggregated stats, full historical match records, surface breakdowns, rivalry rankings, upcoming meeting data, and recent event results.

ℹ️

Player name format All {player} path parameters use the player's display name with URL encoding (spaces become %20).
Examples: Novak%20Djokovic, Rafael%20Nadal, Carlos%20Alcaraz

ℹ️

Player Images: Some endpoints return player image paths (e.g., player1Image, player2Image). These can be accessed via the proxy at /tennis/v2/ms-api/uploads/Photo/{type}/{id}.jpg. Example: https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/uploads/Photo/atp/05992.jpg

Endpoint Summary

Method	Path	Description
GET	`.../h2h/profile/{type}/{player1}/{player2}/{limit}`	Combined H2H profile for two players
GET	`.../h2h/stats/{type}/{player1}/{player2}`	Aggregated H2H statistics
GET	`.../h2h/recent-stats/{type}/{player}`	Recent match statistics for one player
GET	`.../h2h/history/{type}/{player1}/{player2}`	Full match history between two players
GET	`.../h2h/current/{type}/{player}/{player2}`	Current event stats between two players
GET	`.../h2h/breakdown/{type}/{player}`	Win/loss breakdown for a player
GET	`.../h2h/surfaceBreakdown/{type}/{player}`	Surface-by-surface breakdown
GET	`.../h2h/recent/{type}/{player}`	Recent matches for a player
GET	`.../h2h/upcoming/{type}/{player1}/{player2}`	Upcoming match between two players
GET	`.../h2h/filters/{player1}/{player2}/{type}/vs`	H2H filter options (vs mode)
GET	`.../h2h/filters/{player1}/{player2}/{type}`	H2H filter options
GET	`.../h2h/player-vs-player/recent-event/{type}/{player1}/{player2}`	Most recent event between two players
GET	`.../h2h/rivalries/{type}/{player}`	Top rivalries for a player
GET	`.../h2h/last-match-played/{type}/{player}`	Last match played by a player
GET	`.../h2h/sport/{sportId}/data/{siteType}/transformed`	Transformed sport event data
GET	`.../h2h/playerType/{player}`	Determine if player is ATP or WTA

H2H Profile

GET /tennis/v2/ms-api/h2h/profile/{type}/{player1}/{player2}/{limit} Returns combined profiles and H2H summary for two players

Path Parameters

Parameter	Type	Description
`type` Required	string	`atp` or `wta`
`player1` Required	string	First player display name (URL-encoded)
`player2` Required	string	Second player display name (URL-encoded)
`limit` Required	boolean	`true` to limit recent matches, `false` for full history

Query Parameters

Parameter	Type	Description
`includeAll` Optional	boolean	Include all historical data

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/profile/atp/Novak%20Djokovic/Carlos%20Alcaraz/false' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "player1": {
    "id": 5992,
    "name": "Novak Djokovic",
    "playerStatus": "Active",
    "country": "Serbia",
    "contryAcr": "SRB",
    "playerStat": {
      "maintourWin": 29,
      "maintourLose": 8,
      "finalsWin": 6,
      "finalsLose": 2,
      "masterWin": 40,
      "masterLose": 20,
      "slamWin": 24,
      "slamLose": 14,
      "cupsWin": 11,
      "cupsLose": 4,
      "futuresWin": 2,
      "futuresLose": 0,
      "challengersWin": 3,
      "challengersLose": 0,
      "totalWins": 1274,
      "totalLose": 261
    },
    "image": "/tennis/api2/uploads/Photo/atp/05992.jpg",
    "image_p_name": "/tennis/api2/uploads/Photo/atp_name/novak_djokovic.jpg",
    "birthday": "1987-05-22T00:00:00.000Z",
    "currentRank": 7,
    "plays": "Right-Handed"
  }
}

Response Properties

Property	Type	Description
`player1` / `player2`	object	Profile summary for each player
`player1.id`	number	Player ID
`player1.name`	string	Player name
`player1.playerStatus`	string	Player status (e.g., "Active")
`player1.country`	string	Country name
`player1.contryAcr`	string	Country code
`player1.playerStat`	object	Detailed player statistics
`player1.playerStat.maintourWin`	number	Main tour wins
`player1.playerStat.maintourLose`	number	Main tour losses
`player1.playerStat.totalWins`	number	Total career wins
`player1.playerStat.totalLose`	number	Total career losses
`player1.image`	string	Player image path
`player1.image_p_name`	string	Player image path with name
`player1.birthday`	string	Date of birth (ISO 8601)
`player1.currentRank`	number	Current ranking
`player1.plays`	string	Playing hand

H2H Statistics

GET /tennis/v2/ms-api/h2h/stats/{type}/{player1}/{player2} Aggregated statistics for all matches played between two players

Query Parameters

Parameter	Type	Description
`year` Optional	number	Filter to a specific year
`surface` Optional	string	Filter by surface: `hard`, `clay`, `grass`
`tournament` Optional	string	Filter by tournament name

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/stats/atp/Novak%20Djokovic/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "matchesCount": 10,
  "player1": {
    "name": "Novak Djokovic",
    "matchesWon": 5,
    "acesCount": 44,
    "doubleFaultsCount": 30,
    "avgTime": "3:8:5",
    "firstServe": 769,
    "firstServeOf": 1167,
    "firstServePercentage": 66,
    "winningOnFirstServe": 520,
    "winningOnFirstServeOf": 769,
    "winningOnFirstServePercentage": 68,
    "winningOnSecondServe": 217,
    "winningOnSecondServeOf": 398,
    "winningOnSecondServePercentage": 55
  }
}

Response Properties

Property	Type	Description
`matchesCount`	number	Total matches between the players
`player1` / `player2`	object	Detailed statistics for each player
`player1.name`	string	Player name
`player1.matchesWon`	number	Matches won by this player
`player1.acesCount`	number	Total aces
`player1.doubleFaultsCount`	number	Total double faults
`player1.avgTime`	string	Average match time
`player1.firstServe`	number	First serves made
`player1.firstServeOf`	number	Total serve points
`player1.firstServePercentage`	number	First serve percentage
`player1.winningOnFirstServePercentage`	number	Win percentage on first serve
`player1.winningOnSecondServePercentage`	number	Win percentage on second serve

Match History

GET /tennis/v2/ms-api/h2h/history/{type}/{player1}/{player2} Returns a full list of past matches played between two players

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/history/atp/Novak%20Djokovic/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "singles": [
    {
      "roundId": 12,
      "result": "2-6 6-2 6-3 7-5",
      "date": "2026-02-01T00:00:00.000Z",
      "player1Id": 68074,
      "player2Id": 5992,
      "tournamentId": 21305,
      "draw": 1,
      "best_of"null,
      "player1": {
        "id": 68074,
        "name": "Carlos Alcaraz",
        "countryAcr": "ESP",
        "currentRank": 2
      },
      "player2": {
        "id": 5992,
        "name": "Novak Djokovic",
        "countryAcr": "SRB",
        "currentRank": 7
      }
    }
  ]
}

Response Properties

Property	Type	Description
`singles`	array	Array of singles matches
`singles[].roundId`	number	Round identifier
`singles[].result`	string	Match score/result
`singles[].date`	string	Match date (ISO 8601)
`singles[].player1Id`	number	Player 1 ID
`singles[].player2Id`	number	Player 2 ID
`singles[].tournamentId`	number	Tournament ID
`singles[].draw`	number	Draw type
`singles[].best_of`	number \| null	Best of sets
`singles[].player1`	object	Player 1 information
`singles[].player1.id`	number	Player ID
`singles[].player1.name`	string	Player name
`singles[].player1.countryAcr`	string	Country code
`singles[].player1.currentRank`	number	Current ranking
`singles[].player2`	object	Player 2 information
`singles[].player2.id`	number	Player ID
`singles[].player2.name`	string	Player name
`singles[].player2.countryAcr`	string	Country code
`singles[].player2.currentRank`	number	Current ranking

Recent Matches

GET /tennis/v2/ms-api/h2h/recent/{type}/{player} Returns the most recent matches played by a single player

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/recent/atp/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

[
  {
    "date": "2025-06-08",
    "opponent": "Jannik Sinner",
    "tournament": "Roland Garros",
    "surface": "Clay",
    "result": "W",
    "score": "6-3 6-2 6-4"
  }
]

Response Properties

Property	Type	Description
`date`	string	Match date
`opponent`	string	Opponent display name
`tournament`	string	Tournament name
`surface`	string	Court surface
`result`	string	`"W"` for win, `"L"` for loss
`score`	string	Match score

Recent Stats

GET /tennis/v2/ms-api/h2h/recent-stats/{type}/{player} Returns aggregated serve and return statistics from a player's recent matches

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/recent-stats/atp/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "firstServePct": 68.4,
  "firstServeWonPct": 79.1,
  "secondServeWonPct": 57.3,
  "breakPointsSavedPct": 65.0,
  "returnPointsWonPct": 43.8
}

Response Properties

Property	Type	Description
`firstServePct`	number	First serve in percentage
`firstServeWonPct`	number	Points won on first serve (%)
`secondServeWonPct`	number	Points won on second serve (%)
`breakPointsSavedPct`	number	Break points saved (%)
`returnPointsWonPct`	number	Return points won (%)

Breakdown

GET /tennis/v2/ms-api/h2h/breakdown/{type}/{player} Returns a player's win/loss record broken down by round, level, and opponent category

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/breakdown/atp/Novak%20Djokovic' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

[
  {
    "category": "Finals",
    "wins": 58,
    "losses": 18,
    "winPct": 76.3
  }
]

Response Properties

Property	Type	Description
`category`	string	Breakdown category, e.g. `"Finals"`, `"Semi-Finals"`, `"Top 10"`
`wins`	integer	Matches won in this category
`losses`	integer	Matches lost in this category
`winPct`	number	Win percentage

Surface Breakdown

GET /tennis/v2/ms-api/h2h/surfaceBreakdown/{type}/{player} Returns a player's win/loss record broken down by court surface

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/surfaceBreakdown/atp/Novak%20Djokovic' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

[
  { "surface": "Hard", "wins": 418, "losses": 76, "winPct": 84.6 },
  { "surface": "Clay", "wins": 312, "losses": 55, "winPct": 85.0 },
  { "surface": "Grass", "wins": 174, "losses": 24, "winPct": 87.9 }
]

Response Properties

Property	Type	Description
`surface`	string	`"Hard"`, `"Clay"`, `"Grass"`, or `"Carpet"`
`wins`	integer	Wins on this surface
`losses`	integer	Losses on this surface
`winPct`	number	Win percentage

Upcoming Match

GET /tennis/v2/ms-api/h2h/upcoming/{type}/{player1}/{player2} Returns the next scheduled match between two players if one exists

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/upcoming/atp/Novak%20Djokovic/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "tournament": "Wimbledon",
  "round": "Final",
  "scheduledDate": "2025-07-13",
  "surface": "Grass"
}

Response Properties

Property	Type	Description
`tournament`	string	Tournament name
`round`	string	Scheduled round
`scheduledDate`	string	Date in `YYYY-MM-DD`
`surface`	string	Court surface

Current Event Stats

GET /tennis/v2/ms-api/h2h/current/{type}/{player}/{player2} Returns current event statistics between two players

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/current/atp/Novak%20Djokovic/Carlos%20Alcaraz' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "player1": "Novak Djokovic",
  "player2": "Carlos Alcaraz",
  "currentEvent": "Wimbledon Final",
  "stats": {
    "player1Wins": 3,
    "player2Wins": 5
  }
}

Response Properties

Property	Type	Description
`player1` / `player2`	string	Player display names
`currentEvent`	string	Name of the current event
`stats`	object	Current statistics for both players

Last Match Played

GET /tennis/v2/ms-api/h2h/last-match-played/{type}/{player} Returns the single most recent match played by a player

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/last-match-played/atp/sinner-jannik' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "date": "2025-06-08",
  "opponent": "Carlos Alcaraz",
  "tournament": "Roland Garros",
  "result": "L",
  "score": "3-6 2-6 4-6"
}

Response Properties

Property	Type	Description
`date`	string	Match date
`opponent`	string	Opponent display name
`tournament`	string	Tournament name
`result`	string	`"W"` or `"L"`
`score`	string	Match score

Player Type Lookup

GET /tennis/v2/ms-api/h2h/playerType/{player} Returns whether a player belongs to the ATP or WTA tour — useful before making typed requests

Example Request

cURL

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

Example Response

JSON

{
  "player": "swiatek-iga",
  "type": "wta"
}

Response Properties

Property	Type	Description
`player`	string	The player slug passed in the request
`type`	string	`"atp"` or `"wta"`

Top Rivalries

GET /tennis/v2/ms-api/h2h/rivalries/{type}/{player} Returns the most frequent opponents for a player ranked by number of matches

Query Parameters

Parameter	Type	Description
`limit` Optional	number	Number of rivalries to return (default: `10`)
`includeAll` Optional	boolean	Include all career data (default: `false`)

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/rivalries/atp/Novak%20Djokovic?limit=5' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "player": "Novak Djokovic",
  "rivalries": [
    {
      "opponentName": "Rafael Nadal",
      "playerWins": 31,
      "opponentWins": 29,
      "totalMatches": 60
    },
    {
      "opponentName": "Roger Federer",
      "playerWins": 27,
      "opponentWins": 23,
      "totalMatches": 50
    }
  ]
}

Response Properties

Property	Type	Description
`player`	string	Player name
`rivalries`	array	Array of rivalries
`rivalries[].opponentName`	string	Opponent's display name
`rivalries[].playerWins`	number	Wins by the queried player
`rivalries[].opponentWins`	number	Wins by the opponent
`rivalries[].totalMatches`	number	Total matches between them

H2H Filters

GET /tennis/v2/ms-api/h2h/filters/{player1}/{player2}/{type} Returns available filter options for H2H queries between two players

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/filters/Novak%20Djokovic/Carlos%20Alcaraz/atp' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "surfaces": ["Hard", "Clay", "Grass"],
  "rounds": ["Final", "Semi-Final"],
  "tournaments": ["Wimbledon", "Roland Garros"]
}

Response Properties

Property	Type	Description
`surfaces`	array<string>	Available court surfaces to filter by
`rounds`	array<string>	Available round names
`tournaments`	array<string>	Tournaments where they have played

Recent Event Between Players

GET /tennis/v2/ms-api/h2h/player-vs-player/recent-event/{type}/{player1}/{player2} Returns the most recent event/match between two specific players

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/player-vs-player/recent-event/atp/Novak%20Djokovic/Carlos%20Alcaraz' \
  --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-14",
  "tournament": "Wimbledon",
  "round": "Final",
  "winner": "Carlos Alcaraz",
  "score": "6-2 6-2 7-6"
}

Response Properties

Property	Type	Description
`date`	string	Match date in `YYYY-MM-DD`
`tournament`	string	Tournament name
`round`	string	Round of the match
`winner`	string	Winner display name
`score`	string	Match score

Transformed Sport Data

GET /tennis/v2/ms-api/h2h/sport/{sportId}/data/{siteType}/transformed Returns enriched sport event data with H2H context, suitable for third-party widget integrations

Path Parameters

Parameter	Type	Description
`sportId` Required	string	Sport identifier from the Newsport data provider
`siteType` Required	string	Target site context, e.g. `sgt`, `ms`

Query Parameters

Parameter	Type	Description
`isUpcoming` Optional	string	`Yes` or `No` (default: `No`)
`isSort` Optional	string	`Yes` or `No` (default: `No`)
`page` Optional	number	Page number (default: `1`)
`limit` Optional	number	Results per page, max `200` (default: `50`)
`leagues` Optional	string	Comma-separated league filter
`date` Optional	string	Filter by date in `YYYY-MM-DD` format
`time_range` Optional	string	Unix timestamp range as `start_end`, e.g. `1700000000_1700086400`

Example Request

cURL

curl --request GET \
  --url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/h2h/sport/123/data/sgt/transformed?isUpcoming=Yes&limit=20' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com'

Example Response

JSON

{
  "data": [
    {
      "eventId": "abc123",
      "player1": "Novak Djokovic",
      "player2": "Carlos Alcaraz",
      "h2hWins1": 3,
      "h2hWins2": 5,
      "startTime": 1720000000
    }
  ],
  "total": 48,
  "page": 1
}

Response Properties

Property	Type	Description
`data`	array	Array of enriched event objects
`data[].eventId`	string	External event identifier from the sport data provider
`data[].player1` / `data[].player2`	string	Player display names as matched in the database
`data[].h2hWins1` / `data[].h2hWins2`	integer	All-time H2H win counts for each player
`data[].startTime`	integer	Match start time as a Unix timestamp
`total`	integer	Total events matching the query
`page`	integer	Current page number