API Reference

Players & Profiles

Core player routes use a numeric ID. Use these for profile, stats, matches, surface, and filters. Extra endpoints at the bottom (career statistics, name search, status, next match, photos) are not replacements for the core routes.

⚠️
Player identity is not the same on every route
  • Core routes under /tennis/v2/{atp|wta}/player/… need a numeric player ID (for example 68074). A display name returns 400.
  • Extra endpoints at the bottom of this page (career statistics, status, next match) accept the display name, URL-encoded (Carlos%20Alcaraz), or the same numeric ID. Hyphenated slugs such as alcaraz-carlos return {"err":"Player not found"}.
  • GET /tennis/v2/search?search=Carlos%20Alcaraz returns names, not IDs. Take numeric IDs from rankings, fixtures, or /tennis/v2/{atp|wta}/player.

Players List

GET/tennis/v2/atp/player?pageSize=10
This example uses atp. Use wtafor the women's dataset.Returns a paginated list of players on the selected tour, including each player's numeric ID, display name, country, and current ranking snapshot.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.

Query Parameter

ParameterRequiredTypeDescription
includeNostring
Comma-separated extra objects to add. Available: country — adds a full country object to each player.
Example: include=country
filterNostring
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
pageSizeNointeger
Results per page. Default: 10. Core maximum: 500 (larger values are reduced). Example: pageSize=10.
pageNoNointeger
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/player?pageSize=10' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
dataarrayThe page of results. An empty array with HTTP 200 means the request was valid and nothing matched that date, filter, or page.
pageNointegerCurrent page, starting at 1. Also returned as page.
pageSizeintegerItems requested for this page. Also returned as limit. Core maximum is 500.
hasNextPagebooleantrue if another page exists. Stop when this is false or data is empty.
idintegerNumeric player ID for core player and fixture routes.
namestringDisplay name. URL-encode this on name-based /profile routes.
countryAcrstring3-letter country code, e.g. ESP.
currentRankintegerCurrent singles ranking position, or null if unranked.
pointsintegerCurrent ranking points, or null if unranked.
progressintegerPlaces gained or lost versus the previous list (negative = dropped).

Player Profile by ID

GET/tennis/v2/atp/player/profile/68074
This example uses atp. Use wtafor the women's dataset.Returns full profile details for one player. Path requires a numeric ID — a display name returns 400.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.

Query Parameter

ParameterRequiredTypeDescription
includeNostring
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/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
dataobjectThe player profile object.
idintegerNumeric player ID.
namestringDisplay name.
birthdaystringDate of birth as ISO-8601.
countryAcrstring3-letter country code.
currentRank / points / progressintegerLatest official ranking snapshot.
playerStatusstringe.g. Active.
informationobjectBio: turnedPro, height, weight, plays, coach, social links.
countryobjectPresent when include contains country: name and acronym.

Player Titles

GET/tennis/v2/atp/player/titles/68074
This example uses atp. Use wtafor the women's dataset.Returns a player's finals record grouped by tournament level (ITF, Challenger, main tour, Masters, Grand Slam and more): titles won and finals lost at each level. For the list of individual finals, use Player Finals by ID. No pagination.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/titles/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
dataarrayOne row per tournament level.
tourRankIdintegerLevel ID (0 = ITF $10K, 1 = Challenger/ITF >$10K, 4 = Grand Slam, …).
tourRankstringLevel name.
titlesWon / titlesLoststringFinals won and lost at that level.

Player Match Stats by ID

GET/tennis/v2/atp/player/match-stats/68074
This example uses atp. Use wtafor the women's dataset.Returns aggregated match statistics for a player (win/loss records, ace counts, break point stats, etc.)

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/match-stats/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Past Matches by ID

GET/tennis/v2/atp/player/past-matches/68074
This example uses atp. Use wtafor the women's dataset.Returns completed match results for a player, most recent first. On these rows player1 is the winner.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.

Query Parameter

ParameterRequiredTypeDescription
includeNostring
Comma-separated extra objects to add. round returns the human-readable tournament round associated with roundId, for example Quarter-Final, Semi-Final or Final (full lookup: GET /tennis/v2/round). Also tournament,tournament.court, tournament.rank, tournament.country,stat (per-match serve & return stats).
Example:include=round,tournament.court,stat
filterNostring
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), requirestournament in include
  • TourRank:{4}rank_id from GET /ranking (Grand Slam is 4). Requirestournament in include
  • GameTour:{20340} — filter by tournament ID(s)
Example: filter=GameYear:2025;GameRound:1,2
pageSizeNointeger
Results per page. Default: 10. Core maximum: 500 (larger values are reduced). Example: pageSize=10.
pageNoNointeger
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/player/past-matches/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
dataarrayThe page of results. An empty array with HTTP 200 means the request was valid and nothing matched that date, filter, or page.
pageNointegerCurrent page, starting at 1. Also returned as page.
pageSizeintegerItems requested for this page. Also returned as limit. Core maximum is 500.
hasNextPagebooleantrue if another page exists. Stop when this is false or data is empty.
idintegerCompleted-match archive ID (not a live event id).
datestringMatch date/time as ISO-8601.
resultstringScore string, e.g. 6-4 6-3.
player1Id / player2IdintegerOn completed matches, player1 is always the winner and player2 the loser.
tournamentId / roundIdintegerEvent edition and round.
odd1 / odd2stringPre-match odds when available; often null on older matches.

Player Surface Summary by ID

GET/tennis/v2/atp/player/surface-summary/68074
This example uses atp. Use wtafor the women's dataset.Returns win/loss records broken down by court surface (hard, clay, grass, carpet, indoor hard)

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/surface-summary/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Performance Breakdown by ID

GET/tennis/v2/atp/player/perf-breakdown/68074
This example uses atp. Use wtafor the women's dataset.Returns granular performance metrics including serve, return, and pressure statistics.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/perf-breakdown/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Returns { data: {...} } with serve, return, pressure, and situational win-rate fields — similar to H2H Stats. The exact keys vary by player. Returns { data: null } if no performance data is available.

Player Finals by ID

GET/tennis/v2/atp/player/finals/68074
This example uses atp. Use wtafor the women's dataset.Returns all finals appearances (won and lost) for a player.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.

Query Parameter

ParameterRequiredTypeDescription
filterNostring
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 ininclude
  • TourRank:{4}rank_id from GET /ranking (Grand Slam is 4). Requires tournament ininclude
  • GameTour:{20340} — filter by tournament ID(s)
Example: filter=GameYear:2024,2025;TourRank:4
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/finals/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

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.

Interesting H2H for Player by ID

GET/tennis/v2/atp/player/intersting-h2h/68074
This example uses atp. Use wtafor the women's dataset.Returns notable head-to-head records for a player (most wins, biggest rivals, etc.)
⚠️
Core path spelling

The core route is spelled intersting-h2h — that is the live path, not a typo in these docs. There is no /interesting-h2h/ alias.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/intersting-h2h/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Filter Options by ID

GET/tennis/v2/atp/player/filter/68074
This example uses atp. Use wtafor the women's dataset.Returns available filter categories and metadata for a player (used to build UI filter panels)

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/filter/68074' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Tournament Record

GET/tennis/v2/atp/player/tournament-record/68074/20340
This example uses atp. Use wtafor the women's dataset.Returns a player's career record at a specific tournament, one entry per year.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesinteger
Player ID (≥ 1). Take it from Rankings (player.id), Fixtures (player1Id), or the core player list. Search returns names, not IDs.
tournament_idYesinteger
Any season ID from that tournament family. All historical editions of the same event are included.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/atp/player/tournament-record/68074/20340' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Extra player endpoints

These are not the same as the core profile, stats, or match routes above. Use them for career statistics, player search by name, status, the next scheduled match, or photos.

Player Career Statistics

GET/tennis/v2/profile/Novak%20Djokovic/statistics
Retrieve a player's comprehensive career statistics, including recent match results, current and highest rankings, performance across tournament categories, overall win/loss record, favorite playing surface, and career titles and finals.

Path Parameter

ParameterRequiredTypeDescription
player_id_or_nameYesstring
URL-encoded display name (Carlos%20Alcaraz) or numeric ID (68074). Hyphenated slugs such as alcaraz-carlos return {"err":"Player not found"}.

Query Parameter

ParameterRequiredTypeDescription
typeNostring
Use with a numeric player ID to choose the ATP or WTA player with that ID: atp or wta. Example: type=wta. Not needed when you pass a player name.
includeAllNoboolean
Include Challenger/ITF and full history where supported. Example: includeAll=true
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/profile/Novak%20Djokovic/statistics' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
recentGamesarrayLast 10 results as w or l (most recent first).
currentRankintegerCurrent singles ranking, or null if unranked.
bestRank.position / bestRank.dateobjectCareer-high rank and the date it was reached.
mainTours / tourFinals / master / grandSlam / cups / futures / challengers / totalobjectWin/loss objects for that category.
favouriteCourtobjectwins, losses, surfaceId, surface.
totalTitles / totalTitlesWon / totalFinalsWonintegerCareer title counts.
GET/tennis/v2/profile/search/Djokovic/atp
This example uses atp. Use wtafor the women's dataset.Search for tennis players by surname and tour type (atp/wta), returning a list of matching player names.

Path Parameter

ParameterRequiredTypeDescription
nameYesstring
Player display name (URL-encoded).
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.

Query Parameter

ParameterRequiredTypeDescription
pageNointeger
Page number on advanced routes, starting at 1. Do not send pageNo here. Example: page=1
limitNointeger
Results per page on advanced routes (use page + limit, not pageNo + pageSize). Default varies by endpoint. Example: limit=10
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/profile/search/Djokovic/atp' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Status

GET/tennis/v2/profile/Novak%20Djokovic/player-status
Retrieve the current status of a tennis player, such as whether they are Active or Inactive.

Path Parameter

ParameterRequiredTypeDescription
player_id_or_nameYesstring
URL-encoded display name (Carlos%20Alcaraz) or numeric ID (68074). Hyphenated slugs such as alcaraz-carlos return {"err":"Player not found"}.

Query Parameter

ParameterRequiredTypeDescription
typeNostring
Use with a numeric player ID to choose the ATP or WTA player with that ID: atp or wta. Example: type=wta. Not needed when you pass a player name.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/profile/Novak%20Djokovic/player-status' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
statusstringCurrent player status, e.g. Active or Inactive.

Player Upcoming Match

GET/tennis/v2/profile/Lucas%20Poullain/upcoming
Returns the player's next scheduled match if one is available.

Path Parameter

ParameterRequiredTypeDescription
player_id_or_nameYesstring
URL-encoded display name (Carlos%20Alcaraz) or numeric ID (68074). Hyphenated slugs such as alcaraz-carlos return {"err":"Player not found"}.

Query Parameter

ParameterRequiredTypeDescription
typeNostring
Use with a numeric player ID to choose the ATP or WTA player with that ID: atp or wta. Example: type=wta. Not needed when you pass a player name.
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/profile/Lucas%20Poullain/upcoming' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Player Image (JPEG)

GET/tennis/v2/ms-api/uploads/Photo/atp/05992.jpg
This example uses atp. Use wtafor the women's dataset.Returns the player photograph as a JPEG. Use the image path from a profile or H2H payload — the file name is the player id padded to five digits (Novak Djokovic is 05992.jpg). HTTP 200 with Content-Type image/jpeg; the body is the image, not JSON.

Path Parameter

ParameterRequiredTypeDescription
atp|wtaYesstring
Dataset to query. atp = men's tennis across all supported levels, including Grand Slams, ATP Tour, Challengers and ITF. wta = women's tennis across all supported levels, including Grand Slams, WTA Tour and ITF. There is no separate itf value.
player_idYesstring
Five-digit player id in the file name. Example: 05992 (id 5992).
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/ms-api/uploads/Photo/atp/05992.jpg' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Successful responses are JPEG bytes (Content-Type: image/jpeg), the same image shown in the RapidAPI Image tab.

Response Properties

FieldTypeDescription
Content-Typestringimage/jpeg
BodybinaryThe photograph. Do not parse this response as JSON.
GET/tennis/v2/profile/team-logo/12
Returns the Davis Cup / Billie Jean King Cup team logo path. Fetch the file from that path on the same host, the same way as player photos.

Path Parameter

ParameterRequiredTypeDescription
team_idYesinteger
Team id. Example: 12
Example Request: CURL
curl --request GET \
	--url 'https://tennis-api-atp-wta-itf.p.rapidapi.com/tennis/v2/profile/team-logo/12' \
	--header 'X-RapidAPI-Host: tennis-api-atp-wta-itf.p.rapidapi.com' \
	--header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY'

Response Properties

FieldTypeDescription
statusstringSUCCESS.
team_logostringLogo path on this host. GET that path to download the image file.