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.
1---2name: cricket-data3description: |4 Cricket data via ESPN public endpoints and Cricsheet open data — live-ish series scoreboards, standings, match summaries and news (ESPN), plus historical ball-by-ball, player stats, and player registry (Cricsheet, ODC-BY 1.0). Zero config, no API keys.56 Use when: user asks about cricket scores, IPL/BBL/PSL/international series, points tables, match details, cricket news, ball-by-ball history, or player career stats.7 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), tennis-data (tennis), golf-data (golf), cfb-data (college football), cbb-data (college basketball), or fastf1 (F1). For betting odds use polymarket or kalshi. For general news use sports-news. Don't use for ICC rankings — no free source exists (v1 limitation).8license: MIT9metadata:10 source: https://skillmd.com/skills/machina-sports/cricket-data11 author: machina-sports12 version: "0.1.0"13---1415# Cricket Data (ESPN + Cricsheet)1617Before writing queries, consult `references/api-reference.md` for endpoints, ID conventions, and data shapes. See `references/competitions.md` for the Cricsheet competition codes.1819## Quick Start2021Prefer the CLI — it avoids Python import path issues. There are two backends: ESPN (live-ish) and Cricsheet (historical).2223```bash24# ESPN backend (live-ish) — discover series first, then use its numeric ID25sports-skills cricket get_series26sports-skills cricket get_scoreboard --series_id=804827sports-skills cricket get_standings --series_id=804828sports-skills cricket get_game_summary --series_id=8048 --event_id=153546529sports-skills cricket get_news --series_id=80483031# Cricsheet backend (historical, completed matches) — uses letter codes32sports-skills cricket get_competitions33sports-skills cricket get_matches --competition=ipl --season=202634sports-skills cricket get_match_deliveries --competition=ipl --match_id=147350835sports-skills cricket get_player_stats --competition=ipl --player="V Kohli"36sports-skills cricket find_player --name=kohli37```3839## CRITICAL: Before Any Query4041CRITICAL: Before calling any data endpoint, verify:4243- **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.44- **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.45- **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`).46- **`get_player_stats` requires the exact Cricsheet name spelling** (e.g. `"V Kohli"`, not `"Virat Kohli"`). Resolve the spelling with `find_player` first.47- **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).48- **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.4950Agents can run `scripts/validate_params.sh` to pre-validate `--competition`, `--series_id`, and `--date` before querying.5152## Commands5354### ESPN backend (live-ish)5556| Command | Required params | Description |57|---|---|---|58| `get_series` | — | List currently-active cricket series with ESPN series IDs and live events |59| `get_scoreboard` | `series_id` (opt `date`) | Matches + scores + status for a series |60| `get_standings` | `series_id` | Points table for a series (empty for most bilateral tours) |61| `get_game_summary` | `series_id`, `event_id` | Match detail: rosters, leaders, matchcards, venue info |62| `get_news` | `series_id` | News articles for a series |6364### Cricsheet backend (historical, ODC-BY 1.0)6566| Command | Required params | Description |67|---|---|---|68| `get_competitions` | — | List Cricsheet competition codes |69| `get_matches` | `competition` (opt `season`) | Completed matches for a competition, newest first |70| `get_match_deliveries` | `competition`, `match_id` (opt `innings`) | Ball-by-ball deliveries for a completed match |71| `get_player_stats` | `competition`, `player` (opt `season`) | Aggregate batting + bowling stats for a player |72| `find_player` | `name` | Search Cricsheet player registry; returns ESPNcricinfo ID mappings |7374Dates 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.7576## Workflows7778### Live / recent series check791. `get_series` → pick the series and note its `series_id`.802. `get_scoreboard --series_id=<id>` → present matches by status and score.813. For one match's detail: `get_game_summary --series_id=<id> --event_id=<id>`.8283### Points table (league tournaments)841. `get_series` → find the tournament's `series_id`.852. `get_standings --series_id=<id>`. If empty, it is a bilateral tour with no published table.8687### Historical player stats881. `find_player --name=<substring>` → confirm the exact `name` spelling.892. `get_player_stats --competition=<code> --player="<exact name>"` (optionally `--season`).9091### Ball-by-ball history921. `get_matches --competition=<code> [--season=<year>]` → find the `match_id`.932. `get_match_deliveries --competition=<code> --match_id=<id> [--innings=N]`.9495### Cricket news96Cricket news is series-scoped — there is no global feed.971. `get_series` → pick the relevant series and note its `series_id`.982. `get_news --series_id=<id>` → present the articles.99100## Commands that DO NOT exist — never call these101102- ~~`get_player`~~ / ~~`get_player_info`~~ — do not exist. Use `find_player` to resolve a name, then `get_player_stats` for career numbers.103- ~~`get_match`~~ — does not exist. Use `get_matches` (historical list) or `get_game_summary` (one ESPN match's detail).104- ~~`get_rankings`~~ — does not exist. There is no free ICC rankings source (v1 limitation).105- ~~`get_teams`~~ / ~~`get_team_roster`~~ — do not exist. Rosters come inside `get_game_summary`.106- ~~`get_play_by_play`~~ — does not exist. Use `get_match_deliveries` for ball-by-ball data on completed matches.107108If a command is not listed in the Commands table above, it does not exist.109110## Attribution111112Cricsheet 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.