machina-sports/cricket-data

Cricket Data (ESPN + Cricsheet)

Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes. See references/competitions.md for the Cricsheet competition codes.

Quick Start

Prefer the CLI — it avoids Python import path issues. There are two backends: ESPN (live-ish) and Cricsheet (historical).

# ESPN backend (live-ish) — discover series first, then use its numeric ID
sports-skills cricket get_series
sports-skills cricket get_scoreboard --series_id=8048
sports-skills cricket get_standings --series_id=8048
sports-skills cricket get_game_summary --series_id=8048 --event_id=1535465
sports-skills cricket get_news --series_id=8048

# Cricsheet backend (historical, completed matches) — uses letter codes
sports-skills cricket get_competitions
sports-skills cricket get_matches --competition=ipl --season=2026
sports-skills cricket get_match_deliveries --competition=ipl --match_id=1473508
sports-skills cricket get_player_stats --competition=ipl --player="V Kohli"
sports-skills cricket find_player --name=kohli

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• ESPN series IDs are per-series, not per-league. Always discover them with get_series first. IDs change every season for recurring tournaments (e.g. each IPL season has a different ID). Never hardcode them — the 8048 in the examples is illustrative, not permanent.
• Two ID spaces. get_series returns ESPN IDs (live, numeric, e.g. 8048). get_competitions returns Cricsheet codes (historical, letter codes, e.g. ipl). They are unrelated except at the match level: a Cricsheet match_id equals the ESPNcricinfo match ID, so it bridges the two backends.
• Cricsheet covers completed matches only (~1-day lag after a match finishes). For anything live or upcoming, use the ESPN commands (get_scoreboard, get_series).
• get_player_stats requires the exact Cricsheet name spelling (e.g. "V Kohli", not "Virat Kohli"). Resolve the spelling with find_player first.
• No ICC rankings — there is no free source (v1 limitation). Series standings come from get_standings, which is empty for most bilateral tours (only league/group tournaments publish a points table).
• First Cricsheet call per competition per day downloads a zip. Large competitions (Tests, ODIs, IPL) are tens of MB. Zips are cached 24h at ~/.cache/sports-skills/cricsheet/; later calls in the same day are fast.

Agents can run scripts/validate_params.sh to pre-validate --competition, --series_id, and --date before querying.

Commands

ESPN backend (live-ish)

| Command | Required params | Description | |---|---|---| | get_series | — | List currently-active cricket series with ESPN series IDs and live events | | get_scoreboard | series_id (opt date) | Matches + scores + status for a series | | get_standings | series_id | Points table for a series (empty for most bilateral tours) | | get_game_summary | series_id, event_id | Match detail: rosters, leaders, matchcards, venue info | | get_news | series_id | News articles for a series |

Cricsheet backend (historical, ODC-BY 1.0)

| Command | Required params | Description | |---|---|---| | get_competitions | — | List Cricsheet competition codes | | get_matches | competition (opt season) | Completed matches for a competition, newest first | | get_match_deliveries | competition, match_id (opt innings) | Ball-by-ball deliveries for a completed match | | get_player_stats | competition, player (opt season) | Aggregate batting + bowling stats for a player | | find_player | name | Search Cricsheet player registry; returns ESPNcricinfo ID mappings |

Dates accept YYYYMMDD or YYYY-MM-DD. season is the start year (e.g. 2020 matches Cricsheet's "2020/21"). See references/api-reference.md for full parameter lists and return shapes.

Workflows

Live / recent series check

1. get_series → pick the series and note its series_id.
2. get_scoreboard --series_id=<id> → present matches by status and score.
3. For one match's detail: get_game_summary --series_id=<id> --event_id=<id>.

Points table (league tournaments)

1. get_series → find the tournament's series_id.
2. get_standings --series_id=<id>. If empty, it is a bilateral tour with no published table.

Historical player stats

1. find_player --name=<substring> → confirm the exact name spelling.
2. get_player_stats --competition=<code> --player="<exact name>" (optionally --season).

Ball-by-ball history

1. get_matches --competition=<code> [--season=<year>] → find the match_id.
2. get_match_deliveries --competition=<code> --match_id=<id> [--innings=N].

Cricket news

Cricket news is series-scoped — there is no global feed.

1. get_series → pick the relevant series and note its series_id.
2. get_news --series_id=<id> → present the articles.

Commands that DO NOT exist — never call these

• ~~get_player~~ / ~~get_player_info~~ — do not exist. Use find_player to resolve a name, then get_player_stats for career numbers.
• ~~get_match~~ — does not exist. Use get_matches (historical list) or get_game_summary (one ESPN match's detail).
• ~~get_rankings~~ — does not exist. There is no free ICC rankings source (v1 limitation).
• ~~get_teams~~ / ~~get_team_roster~~ — do not exist. Rosters come inside get_game_summary.
• ~~get_play_by_play~~ — does not exist. Use get_match_deliveries for ball-by-ball data on completed matches.

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

Attribution

Cricsheet data is licensed ODC-BY 1.0. Every Cricsheet response includes an attribution field ("Data from Cricsheet (cricsheet.org), ODC-BY 1.0"). Preserve this attribution string when republishing the data.