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

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

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.

WTA Entry List

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

WTA Player Form

1. get_wta_player_results --player_id=<wta_id> --year=<year> --limit=20
2. 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:

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)