Players endpoints

Profiles, search, career statistics, match logs and recent form.

/tennis/players · List & Filter Players
/tennis/players/batch · Fetch Many Players by ID
/tennis/players/search · Player Autocomplete Search
/tennis/players/{player_id} · Get Player Biographical Profile
/tennis/players/{player_id}/form · Player Recent Form
/tennis/players/{player_id}/matches · Player Match Log
/tennis/players/{player_id}/stats · Get Player Detailed Career Statistics

GET/tennis/players

List & Filter Players

Retrieves a paginated list of tennis players matching search and filter criteria.

Parameter	In	Type	Description
q	query	string	Player name search query
tour	query	string	Tour: ATP or WTA
ioc	query	string	3-letter country IOC code
hand	query	string	Hand: R, L, A, U
is_active	query	boolean	Active status
sort_by	query	string	Sort field: rank (default, ranked players first) \| full_name \| last_name \| dobdefault rank
order	query	string	Sort order: asc or descdefault asc
page	query	integer	Page number (1-indexed)min 1 · default 1
page_size	query	integer	Items per page (max 100)min 1 · max 100 · default 20
limit	query	integer	Alias for page_sizemin 1 · max 100

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players?page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "wta_214544",
      "tour": "WTA",
      "first_name": "Aryna",
      "last_name": "Sabalenka",
      "full_name": "Aryna Sabalenka",
      "ioc": "BLR",
      "country_code": "BLR",
      "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/7/7d/Aryna_Sabalenka_Trophy_US_Open_2024_%28cropped%29.jpg?utm_source=commons.wikimedia.org&utm_campaign=index&utm_content=original",
      "portrait_attribution": "Ocoudis derivative work: Kacir",
      "portrait_license": "CC0",
      "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Aryna_Sabalenka_Trophy_US_Open_2024_(cropped).jpg",
      "country_name": "Belarus",
      "nationality": "Belarus",
      "hand": "R",
      "backhand": null,
      "dob": "1998-05-05",
      "height_cm": 182,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 1,
      "career_high_date": null,
      "current_rank": 2,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Aryna Sabalenka"
    },
    {
      "id": "atp_207989",
      "tour": "ATP",
      "first_name": "Carlos",
      "last_name": "Alcaraz",
      "full_name": "Carlos Alcaraz",
      "ioc": "ESP",
      "country_code": "ESP",
      "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Carlos_Alcaraz_Roland_Garros_2025_%28cropped%29.jpg?utm_source=commons.wikimedia.org&utm_campaign=index&utm_content=original",
      "portrait_attribution": "Like tears in rain derivative work: Kacir",
      "portrait_license": "CC BY-SA 4.0",
      "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Carlos_Alcaraz_Roland_Garros_2025_(cropped).jpg",
      "country_name": "Spain",
      "nationality": "Spain",
      "hand": "R",
      "backhand": null,
      "dob": "2003-05-05",
      "height_cm": 183,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 1,
      "career_high_date": null,
      "current_rank": 3,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Carlos Alcaraz"
    }
  ],
  "total": 139027,
  "page": 1,
  "page_size": 2,
  "total_pages": 69514,
  "has_next": true,
  "has_prev": false
}

GET/tennis/players/batch

Fetch Many Players by ID

One call for a roster. Rows use the same shape as /players; ids that do not resolve are listed in `missing` rather than silently dropped.

Parameter	In	Type	Description
ids*	query	string	Comma-separated player ids, at most 50 (e.g. atp_207989,wta_211768)

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/batch?ids=atp_206173,atp_207989"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "atp_206173",
      "tour": "ATP",
      "first_name": "Jannik",
      "last_name": "Sinner",
      "full_name": "Jannik Sinner",
      "ioc": "ITA",
      "country_code": "ITA",
      "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/4/48/Jannik_Sinner_US_Open_2025_%28cropped%29.jpg",
      "portrait_attribution": "The White House derivative work: Kacir",
      "portrait_license": "Public domain",
      "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Jannik_Sinner_US_Open_2025_(cropped).jpg",
      "country_name": "Italy",
      "nationality": "Italy",
      "hand": "R",
      "backhand": null,
      "dob": "2001-08-16",
      "height_cm": 191,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 1,
      "career_high_date": null,
      "current_rank": 1,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Jannik Sinner"
    },
    {
      "id": "atp_207989",
      "tour": "ATP",
      "first_name": "Carlos",
      "last_name": "Alcaraz",
      "full_name": "Carlos Alcaraz",
      "ioc": "ESP",
      "country_code": "ESP",
      "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Carlos_Alcaraz_Roland_Garros_2025_%28cropped%29.jpg?utm_source=commons.wikimedia.org&utm_campaign=index&utm_content=original",
      "portrait_attribution": "Like tears in rain derivative work: Kacir",
      "portrait_license": "CC BY-SA 4.0",
      "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Carlos_Alcaraz_Roland_Garros_2025_(cropped).jpg",
      "country_name": "Spain",
      "nationality": "Spain",
      "hand": "R",
      "backhand": null,
      "dob": "2003-05-05",
      "height_cm": 183,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 1,
      "career_high_date": null,
      "current_rank": 3,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Carlos Alcaraz"
    }
  ],
  "total": 2,
  "missing": []
}

GET/tennis/players/search

Player Autocomplete Search

Fast prefix search for player autocomplete dropdowns.

Parameter	In	Type	Description
q*	query	string	Prefix search term (min 2 characters)
tour	query	string	Optional tour filter (ATP/WTA)
limit	query	integer	Max results limitmin 1 · max 500 · default 10
page_size	query	integer	Alias for limit, matching the paginated routesmin 1 · max 500

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/search?q=sinner"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "atp_206173",
      "tour": "ATP",
      "first_name": "Jannik",
      "last_name": "Sinner",
      "full_name": "Jannik Sinner",
      "ioc": "ITA",
      "country_code": "ITA",
      "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/4/48/Jannik_Sinner_US_Open_2025_%28cropped%29.jpg",
      "portrait_attribution": "The White House derivative work: Kacir",
      "portrait_license": "Public domain",
      "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Jannik_Sinner_US_Open_2025_(cropped).jpg",
      "country_name": "Italy",
      "nationality": "Italy",
      "hand": "R",
      "backhand": null,
      "dob": "2001-08-16",
      "height_cm": 191,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 1,
      "career_high_date": null,
      "current_rank": 1,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Jannik Sinner"
    },
    {
      "id": "atp_101441",
      "tour": "ATP",
      "first_name": "Martin",
      "last_name": "Sinner",
      "full_name": "Martin Sinner",
      "ioc": "GER",
      "country_code": "GER",
      "portrait_url": null,
      "country_name": "Germany",
      "nationality": "Germany",
      "hand": "R",
      "backhand": null,
      "dob": "1968-02-07",
      "height_cm": 180,
      "weight_kg": null,
      "turned_pro": null,
      "career_high_rank": 42,
      "career_high_date": null,
      "current_rank": 947,
      "titles_count": null,
      "grand_slam_titles": null,
      "is_active": true,
      "name": "Martin Sinner"
    }
  ],
  "total": 10,
  "page": 1,
  "page_size": 10,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}

GET/tennis/players/{player_id}

Get Player Biographical Profile

Retrieves full biographical profile and career summary for a specific player.

Parameter	In	Type	Description
player_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/atp_206173"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "id": "atp_206173",
  "tour": "ATP",
  "first_name": "Jannik",
  "last_name": "Sinner",
  "full_name": "Jannik Sinner",
  "ioc": "ITA",
  "country_code": "ITA",
  "portrait_url": "https://upload.wikimedia.org/wikipedia/commons/4/48/Jannik_Sinner_US_Open_2025_%28cropped%29.jpg",
  "portrait_attribution": "The White House derivative work: Kacir",
  "portrait_license": "Public domain",
  "portrait_source_url": "https://commons.wikimedia.org/wiki/File:Jannik_Sinner_US_Open_2025_(cropped).jpg",
  "country_name": "Italy",
  "nationality": "Italy",
  "hand": "R",
  "backhand": null,
  "dob": "2001-08-16",
  "age": 25,
  "height_cm": 191,
  "weight_kg": null,
  "turned_pro": null,
  "career_high_rank": 1,
  "career_high_date": "2024-06-10",
  "weeks_at_no_1": 74,
  "current_rank": 1,
  "current_rank_points": 11000,
  "career_summary": {
    "matches_played": 565,
    "matches_won": 437,
    "matches_lost": 128,
    "win_percentage": 77.35,
    "titles_count": 36,
    "grand_slam_titles": 5,
    "masters_titles": null,
    "finals_reached": null,
    "prize_money_usd": null
  },
  "surface_breakdown": {
    "hard": {
      "matches": 365,
      "won": 291,
      "lost": 74,
      "win_pct": 79.7,
      "titles": 28
    },
    "clay": {
      "matches": 150,
      "won": 108,
      "lost": 42,
      "win_pct": 72,
      "titles": 5
    },
    "grass": {
      "matches": 50,
      "won": 38,
      "lost": 12,
      "win_pct": 76,
      "titles": 3
    },
    "carpet": {
      "matches": 0,
      "won": 0,
      "lost": 0,
      "win_pct": 0,
      "titles": 0
    }
  },
  "is_active": true,
  "name": "Jannik Sinner"
}

GET/tennis/players/{player_id}/form

Player Recent Form

Parameter	In	Type	Description
player_id*	path	string
limit	query	integer	min 1 · max 50 · default 10
surface	query	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/atp_206173/form"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "player_id": "atp_206173",
  "sample_size": 10,
  "wins": 9,
  "losses": 1,
  "win_pct": 90,
  "surface_filter": null,
  "ranking": {
    "current": 1,
    "movement": 0,
    "as_of": "2026-09-28"
  },
  "matches": [
    {
      "match_id": "s365_2026_4764920",
      "date": "2026-07-12",
      "result": "W",
      "opponent_id": "atp_100644",
      "opponent_rank": 3,
      "score": "6-7 7-6 6-3 6-4",
      "surface": "Grass",
      "tournament_id": "atp_2026_540",
      "id": "s365_2026_4764920",
      "starts_at": "2026-07-12T00:00:00+00:00"
    },
    {
      "match_id": "s365_2026_4762041",
      "date": "2026-07-10",
      "result": "W",
      "opponent_id": "atp_104925",
      "opponent_rank": 7,
      "score": "6-4 6-4 6-4",
      "surface": "Grass",
      "tournament_id": "atp_2026_540",
      "id": "s365_2026_4762041",
      "starts_at": "2026-07-10T00:00:00+00:00"
    }
  ],
  "id": "atp_206173"
}

GET/tennis/players/{player_id}/matches

Player Match Log

All matches for one player, newest first — profile match logs in one call.

Parameter	In	Type	Description
player_id*	path	string
year	query	integer
surface	query	string
level	query	string
opponent_id	query	string
date_start	query	string
date_end	query	string
page	query	integer	min 1 · default 1
page_size	query	integer	min 1 · max 500 · default 20

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/atp_206173/matches"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "s365_2026_4764920",
      "tournament_id": "atp_2026_540",
      "tournament_name": "Wimbledon",
      "level": "G",
      "category": "grand_slam",
      "year": 2026,
      "match_date": "2026-07-12",
      "tour": "ATP",
      "surface": "Grass",
      "round": "F",
      "round_name": "Final",
      "best_of": 5,
      "score": "6-7 7-6 6-3 6-4",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_206173",
      "loser_id": "atp_100644",
      "winner": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "rank": 1,
        "is_winner": true
      },
      "loser": {
        "id": "atp_100644",
        "name": "Alexander Zverev",
        "ioc": "GER",
        "seed": "2",
        "rank": 3,
        "is_winner": false
      },
      "player1": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "rank": 1,
        "is_winner": true
      },
      "player2": {
        "id": "atp_100644",
        "name": "Alexander Zverev",
        "ioc": "GER",
        "seed": "2",
        "rank": 3,
        "is_winner": false
      },
      "name": "Wimbledon",
      "starts_at": "2026-07-12T00:00:00+00:00"
    },
    {
      "id": "s365_2026_4762041",
      "tournament_id": "atp_2026_540",
      "tournament_name": "Wimbledon",
      "level": "G",
      "category": "grand_slam",
      "year": 2026,
      "match_date": "2026-07-10",
      "tour": "ATP",
      "surface": "Grass",
      "round": "SF",
      "round_name": "Semi-Finals",
      "best_of": 5,
      "score": "6-4 6-4 6-4",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_206173",
      "loser_id": "atp_104925",
      "winner": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "rank": 1,
        "is_winner": true
      },
      "loser": {
        "id": "atp_104925",
        "name": "Novak Djokovic",
        "ioc": "SRB",
        "seed": "7",
        "rank": 7,
        "is_winner": false
      },
      "player1": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "rank": 1,
        "is_winner": true
      },
      "player2": {
        "id": "atp_104925",
        "name": "Novak Djokovic",
        "ioc": "SRB",
        "seed": "7",
        "rank": 7,
        "is_winner": false
      },
      "name": "Wimbledon",
      "starts_at": "2026-07-10T00:00:00+00:00"
    }
  ],
  "total": 565,
  "page": 1,
  "page_size": 20,
  "total_pages": 29,
  "has_next": true,
  "has_prev": false
}

GET/tennis/players/{player_id}/stats

Get Player Detailed Career Statistics

Retrieves deep career metrics: surface breakdown, serving metrics, and return records.

Parameter	In	Type	Description
player_id*	path	string
surface	query	string	Court surface: Hard, Clay, Grass, Carpet
level	query	string	Tournament level tier: G, M, A, F, D, C
year_from	query	integer	Filter matches from year
year_to	query	integer	Filter matches up to year

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/players/atp_206173/stats"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "player_id": "atp_206173",
  "player_name": "Jannik Sinner",
  "filters": {
    "surface": null,
    "level": null,
    "year_from": null,
    "year_to": null
  },
  "career_summary": {
    "matches_played": 565,
    "matches_won": 437,
    "matches_lost": 128,
    "win_percentage": 77.35,
    "titles_count": 36,
    "grand_slam_titles": 5,
    "masters_titles": null,
    "finals_reached": null,
    "prize_money_usd": null
  },
  "surface_breakdown": {
    "hard": {
      "matches": 365,
      "won": 291,
      "lost": 74,
      "win_pct": 79.7,
      "titles": 28
    },
    "clay": {
      "matches": 150,
      "won": 108,
      "lost": 42,
      "win_pct": 72,
      "titles": 5
    },
    "grass": {
      "matches": 50,
      "won": 38,
      "lost": 12,
      "win_pct": 76,
      "titles": 3
    },
    "carpet": {
      "matches": 0,
      "won": 0,
      "lost": 0,
      "win_pct": 0,
      "titles": 0
    }
  },
  "serving_stats": {
    "total_aces": 3016,
    "total_double_faults": 1002,
    "aces_per_match": null,
    "first_serve_in_pct": 60.2,
    "first_serve_points_won_pct": 75.5,
    "second_serve_points_won_pct": null,
    "service_games_played": null,
    "service_games_won_pct": null,
    "break_points_faced": null,
    "break_points_saved_pct": 66.3
  },
  "return_stats": null,
  "clutch_and_situational": null,
  "grand_slam_breakdown": null,
  "id": "atp_206173",
  "name": "Jannik Sinner"
}