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

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

Points table (league tournaments)

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

Historical player stats

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

Ball-by-ball history

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

Cricket news

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

get_series → pick the relevant series and note its series_id.
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.

cricket-data