tennis-data

name	tennis-data
description	ATP and WTA tennis data via ESPN public endpoints — tournament scores, season calendars, player rankings, player profiles, and news. Zero config, no API keys. Use when: user asks about tennis scores, match results, tournament draws, ATP/WTA rankings, tennis player info, or tennis news. Don't use when: user asks about other sports — use football-data (soccer), nfl-data (NFL), nba-data (NBA), wnba-data (WNBA), nhl-data (NHL), mlb-data (MLB), golf-data (golf), cfb-data (college football), cbb-data (college basketball), or fastf1 (F1). For betting odds use polymarket or kalshi. For news use sports-news. Don't use for live point-by-point data — scores update after each set/match.
license	MIT
metadata	{"author":"machina-sports","version":"0.1.0"}

Tennis Data (ATP + WTA)

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

Important: Tennis is Not a Team Sport

Tennis data is fundamentally different from team sports (NFL, NBA, etc.):

• 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

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, default to atp for men's tennis or wta for women's tennis. If the user just says "tennis" without specifying, ask which tour or show both by calling the command twice.

Before complex fetches, run the parameter validator: bash scripts/validate_params.sh [args]

For detailed reference data, see the files in the references/ directory.

Workflows

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

Workflow: Rankings Lookup

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

Workflow: Season Calendar

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

Examples

User: "What ATP matches are happening right now?"

1. Call get_scoreboard(tour="atp")
2. Present current tournaments and matches by round

User: "Show me the WTA rankings"

1. Call get_rankings(tour="wta", limit=20)
2. Present rankings with rank, name, points, and trend

User: "When is the French Open this year?"

1. Call get_calendar(tour="atp", year=2026)
2. Search results for "Roland Garros" (the French Open's official name)

Error Handling & Fallbacks

• If get_scoreboard returns no matches, tournaments run specific weeks. Use get_calendar to find when events are scheduled.
• If rankings are empty, rankings update weekly on Mondays. The command auto-retries previous weeks.
• If player profile fails, use get_rankings to verify the player_id.
• Never fabricate match scores or rankings. If data is unavailable, state so.