Tennis Data

Tennis Data (ATP + WTA)

Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills tennis get_scoreboard --tour=atp
sports-skills tennis get_rankings --tour=wta
sports-skills tennis get_calendar --tour=atp --year=2026

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• The tour parameter is specified (atp or wta) — there is no default.
• Year is derived from the system prompt's currentDate — never hardcoded.

The tour Parameter

Most commands require --tour=atp or --tour=wta:

• ATP: Men's professional tennis tour
• WTA: Women's professional tennis tour

If the user doesn't specify, ask which tour or show both by calling the command twice.

Commands

See references/api-reference.md for full parameter lists and return shapes.

Workflows

Live Tournament Check

1. get_scoreboard --tour=<atp|wta> 2. Present current matches by round. 3. For player info, use get_player_info --player_id=<id>.

Rankings Lookup

1. get_rankings --tour=<atp|wta> --limit=20 2. Present rankings with points and trend.

Season Calendar

1. get_calendar --tour=<atp|wta> --year=<year> 2. Filter for specific tournament.

Examples

Example 1: Live matches User says: "What ATP matches are happening right now?" Actions: 1. Call get_scoreboard(tour="atp") Result: Current tournament matches organized by round with scores and status

Example 2: Women's rankings User says: "Show me the WTA rankings" Actions: 1. Call get_rankings(tour="wta", limit=20) Result: Top 20 WTA players with rank, name, points, and trend

Example 3: Upcoming Grand Slam date User says: "When is the French Open this year?" Actions: 1. Derive year from currentDate 2. Call get_calendar(tour="atp", year=<derived_year>) 3. Search results for "Roland Garros" (the French Open's official name) Result: French Open dates, location (Paris), and surface (clay)

Commands that DO NOT exist — never call these

• ~~get_matches~~ — does not exist. Use get_scoreboard for current match scores.
• ~~get_draw~~ — does not exist. Tournament draw data is not available via this API.
• ~~get_head_to_head~~ — does not exist. Head-to-head records are not available via this API.
• ~~get_standings~~ — does not exist. Tennis uses get_rankings, not standings.

If a command is not listed in the Commands table above, it does not exist.

Troubleshooting

Error: get_scoreboard returns no matches Cause: Tennis tournaments run specific weeks; no tournament may be scheduled this week Solution: Call get_calendar(tour=...) to find when the next event is scheduled

Error: Rankings are empty Cause: Rankings update weekly on Mondays; there may be a brief update window Solution: The command auto-retries previous weeks. If still empty, retry in a few minutes

Error: Player profile fails Cause: Player ID is incorrect Solution: Use get_rankings to find player IDs from the current rankings list, or verify via ESPN tennis URLs

Error: Scores seem delayed or don't update live Cause: Scores update after each set/match is completed, not point-by-point Solution: This is expected behavior. Refresh get_scoreboard periodically for updated set scores

Tennis Data — API Reference

Commands

get_scoreboard

Get live/recent tennis scores for a tour.

• tour (str, required): "atp" or "wta"

Returns current tournament info with matches organized by round including player names, set scores, and match status.

get_rankings

Get ATP or WTA player rankings.

• tour (str, required): "atp" or "wta"
• limit (int, optional): Number of players to return. Defaults to 50.

Returns rankings[] with rank, name, country, ranking points, and trend (movement since last week).

get_calendar

Get full season tournament calendar.

• tour (str, required): "atp" or "wta"
• year (int, optional): Season year. Defaults to current.

Returns tournaments[] with tournament name, dates, location, surface, and prize money. Use this to find when specific tournaments are scheduled.

get_player_info

Get individual tennis player profile.

• player_id (str, required): ESPN athlete ID
• tour (str, optional): "atp" or "wta". Defaults to "atp".

Returns player details: name, nationality, birthplace, height, turned pro year, career titles, and recent match history.

Important: Tennis is Not a Team Sport

• Tournaments, not games: Events are multi-day tournaments containing many matches.
• Individual athletes: Competitors are individual players (singles) or pairs (doubles), not teams.
• Set-based scoring: Scores are per-set game counts (e.g., 6-4, 7-5), not quarters.
• Rankings, not standings: Players have ATP/WTA ranking points, not team records.
• No rosters or team schedules: Tennis has no team-level commands.

The tour Parameter

• ATP: Men's professional tennis tour
• WTA: Women's professional tennis tour

If the user just says "tennis" without specifying a tour, ask which one or show both by calling the command twice.

Notable Tournaments

See references/grand-slams.md for Grand Slam tournament details and references/scoring.md for scoring format reference. See references/player-ids.md for extended player ID list.

Grand Slam Tournaments

Grand Slams are marked with "major": true in the calendar.

Common Player IDs

Tip: Use get_rankings to find current player IDs and rankings.

Reading Match Scores

Tennis scores are reported as set scores. Example response:

{
  "competitors": [
    {"name": "Carlos Alcaraz", "seed": 1, "set_scores": [6, 3, 7], "winner": true},
    {"name": "Novak Djokovic", "seed": 2, "set_scores": [4, 6, 5], "winner": false}
  ],
  "result": "(1) Carlos Alcaraz (ESP) bt (2) Novak Djokovic (SRB) 6-4 3-6 7-5"
}

This means Alcaraz won 6-4, 3-6, 7-5 (won first set, lost second, won third).

Understanding Tournament Draws

The draws array in scoreboard results contains match groupings:

• Men's Singles / Women's Singles: Individual matches
• Men's Doubles / Women's Doubles: Pairs matches

Each match has a round field: "Qualifying 1st Round", "Round 1", "Round of 16", "Quarterfinal", "Semifinal", "Final".