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
sports-skills tennis get_wta_entry_list --tournament_id=901 --year=2025
sports-skills tennis get_wta_player_results --player_id=320760 --year=2025 --limit=10

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 ESPN-backed 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

| Command | Description | |---|---| | get_scoreboard | Live/recent tournament scores for a tour | | get_rankings | ATP or WTA player rankings | | get_calendar | Full season tournament calendar | | get_player_info | Individual tennis player profile | | get_news | Tennis news articles | | get_wta_entry_list | WTA entry list (singles players and doubles teams) for one tournament edition — WTA API | | get_wta_player_results | A WTA player's most recent match results (bounded window), newest first — WTA API |

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

WTA API Commands Use Native WTA IDs

get_wta_entry_list and get_wta_player_results read the public WTA API (api.wtatennis.com), not ESPN:

tournament_id and player_id are the WTA's own numeric ids, positive decimals with no leading zeros (e.g. tournament 901, player 320760). ESPN ids from get_rankings / get_player_info / get_scoreboard do not work here, and there is no id mapping between the two.
get_wta_player_results returns a bounded window of the most recent results (at most limit, optionally within one year), not a career history. There is no total count: has_more only says further matches exist, and history_complete is always false. Never present count as a career or season total.
Results are dated by tournament start date (tournament_start_date), not the day each match was played. Never present it as a match date.
Matches within one tournament keep the provider's order, which is not guaranteed to be playing order. Don't claim exact within-tournament chronology.
winner_code is the provider's raw side code; no win/loss is derived from it. Don't state who won from it.
Both commands are WTA-published snapshots (source.fetched_at, cached up to 10 minutes). Don't call them complete or live. Under SPORTS_SKILLS_REPLAY=replay/fill, source.fetched_at is null and source.served_at is only local serving time — not data freshness.

Workflows

Live Tournament Check

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

Rankings Lookup

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

Season Calendar

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

WTA Entry List

get_wta_entry_list --tournament_id=<wta_id> --year=<year>
Present each event (format: singles/doubles) with seeds and entry types. It is an entry list, not a draw.

WTA Player Form

get_wta_player_results --player_id=<wta_id> --year=<year> --limit=20
Group by tournament; say these are the most recent count matches, and when has_more is true that earlier matches exist but were not fetched.

Examples

Example 1: Live matches User says: "What ATP matches are happening right now?" Actions:

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:

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:

Derive year from currentDate
Call get_calendar(tour="atp", year=<derived_year>)
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.
~~get_match_stats~~ — does not exist. ESPN publishes no per-match statistics for tennis (aces, double faults, break points): scoreboard statistics lists are empty and the per-match stats endpoint returns "No competitor stats found", even for Grand Slam finals. Only set scores are available.

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: get_wta_entry_list / get_wta_player_results rejects the id or returns HTTP 404 Cause: An ESPN id (or a non-numeric value) was passed; these commands take native WTA numeric ids only Solution: Use the WTA's own tournament/player id. Don't substitute ESPN ids

Error: get_wta_player_results --year=... fails with "outside year ... inconclusive" Cause: The WTA API returned matches from other years, so it likely ignored the year filter Solution: Report that the season's results could not be confirmed. Don't retry without year and present those matches as that season

Error: get_wta_entry_list succeeds with count: 0 Cause: The WTA has not published an entry list for that tournament and year, or the id/year pair does not exist Solution: Read the note field and tell the user no entry list is available — don't report an empty field of players

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