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

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

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.
• 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: 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