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)

Cricsheet backend (historical, ODC-BY 1.0)

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.

Cricket Data — API Reference

Two backends. ESPN provides live-ish series data; Cricsheet provides historical ball-by-ball data. They share no IDs except at the match level (Cricsheet match_id = ESPNcricinfo match ID).

ESPN backend

Undocumented public ESPN endpoints — no auth, no API key. URL templates ({seriesId} is a numeric ESPN series ID from get_series, {eventId} a match ID):

• Active series header: https://site.web.api.espn.com/apis/personalized/v2/scoreboard/header?sport=cricket
• Scoreboard: https://site.api.espn.com/apis/site/v2/sports/cricket/{seriesId}/scoreboard
• Summary: https://site.api.espn.com/apis/site/v2/sports/cricket/{seriesId}/summary?event={eventId}
• News: https://site.api.espn.com/apis/site/v2/sports/cricket/{seriesId}/news

Status values are normalized through the shared ESPN_STATUS_MAP (e.g. not_started, live, closed); the raw ESPN status name passes through when unmapped.

get_series

List currently-active cricket series.

• (no params)

Returns:

• series[] — each with series_id, name, abbreviation, is_tournament (bool), event_count, and events[].
• Each event: event_id, name, date, status, summary.
• count.

Use the returned series_id for every other ESPN command. IDs are season-specific — never hardcode.

get_scoreboard

Matches + scores + status for one series.

• series_id (str, required): ESPN series ID. Discover via get_series.
• date (str, optional): YYYYMMDD or YYYY-MM-DD. Defaults to the current window.

Returns:

• series — series_id, name, abbreviation.
• events[] — each with event_id, name, short_name, date, description, status (mapped), status_detail, venue, note, and competitors[].
• Each competitor: team_id, team, abbreviation, home_away, winner (bool), score (e.g. "161/5"), and innings[].
• Each innings linescore: innings (period number), runs, wickets, overs, is_batting (bool), description (e.g. "161/5 (18/20 ov, target 156)").
• count.

get_standings

Points table for a series, extracted from the scoreboard payload.

• series_id (str, required).

Returns:

• series_id.
• standings[] — each with team_id, team, abbreviation, and stats (a dict of stat-name → value, e.g. wins/losses/points/net run rate as published by ESPN).
• count.
• When no table is published (common for bilateral tours): standings: [], count: 0, and a message explaining it.

get_game_summary

Full match detail. Fields are passed through largely as ESPN returns them.

• series_id (str, required).
• event_id (str, required): from get_scoreboard or get_series.

Returns: event_id, series_id, header, game_info, notes[], rosters[], leaders[], matchcards, article.

get_news

News articles for a series.

• series_id (str, required).

Returns: header, articles[] (each with headline, description, published, type, link), count.

Cricsheet backend

Open data from cricsheet.org, distributed as per-competition zipped JSON files plus a player-registry CSV. License: ODC-BY 1.0 — attribution required, so every response includes an attribution field ("Data from Cricsheet (cricsheet.org), ODC-BY 1.0"). Data covers completed matches only and lags live play by roughly a day.

Zip URL template: https://cricsheet.org/downloads/{code}_json.zip. Registry: https://cricsheet.org/register/people.csv.

get_competitions

List supported competition codes.

• (no params)

Returns: competitions[] (each code + name), count, attribution. See references/competitions.md for the full table.

get_matches

Completed matches for a competition, newest first.

• competition (str, required): Cricsheet code (e.g. ipl, tests).
• season (int, optional): start year. Prefix-matched, so 2020 matches Cricsheet's "2020/21".

Returns: competition, matches[], count, attribution, and stale: true if a stale cached copy was served.

• Each match: match_id (= ESPNcricinfo match ID), date, teams[], venue, city, season, match_type, gender, event (tournament name), winner, outcome (raw outcome block).

get_match_deliveries

Ball-by-ball deliveries for one match.

• competition (str, required).
• match_id (str, required): from get_matches.
• innings (int, optional): restrict to one innings (1–4).

Returns: match (same shape as a get_matches entry), innings[], attribution, optional stale.

• Each innings: innings (number), team, deliveries[], count.
• Each delivery: over, ball, batter, bowler, non_striker, runs (raw Cricsheet block, e.g. {batter, extras, total}), and — when present — extras and wickets[].

get_player_stats

Aggregate batting and bowling stats for one player across a competition.

• competition (str, required).
• player (str, required): exact Cricsheet name (resolve with find_player).
• season (int, optional): start year filter.

Returns: player, competition, season, matches, batting, bowling, attribution, optional stale.

• batting: runs, balls, fours, sixes, dismissals, strike_rate, average (null if never dismissed).
• bowling: balls, runs_conceded, wickets, economy (null if no balls bowled), overs (string like "4.2").

Aggregation conventions:

• Batting balls faced exclude wides (no-balls are counted as faced).
• Bowling balls exclude wides and no-balls.
• Bowler concedes batter runs + wides + no-balls — not byes, leg-byes, or penalty runs.
• Wickets are credited to the bowler only for: bowled, caught, lbw, stumped, hit wicket, caught and bowled (run-outs etc. are not credited).
• economy = runs_conceded / (balls / 6).
• Returns an error if the player name matches no match (names must match Cricsheet exactly).

find_player

Search the player registry by case-insensitive name substring (matches both name and unique_name). Returns up to 25 results.

• name (str, required): substring (e.g. kohli).

Returns: players[], count, attribution, optional stale.

• Each player: cricsheet_id (registry identifier), name, unique_name, cricinfo_id (ESPNcricinfo ID — bridges Cricsheet to ESPN match data).

Cache behavior

• ESPN: in-memory cache, TTL ~120s (the active-series header is cached; per-series scoreboards via the shared ESPN request layer).
• Cricsheet: on-disk cache at ~/.cache/sports-skills/cricsheet/ (override base with XDG_CACHE_HOME). Competition zips live 24h; the player registry CSV lives 7 days. Downloads are atomic (.tmp then rename).
• Stale fallback: if a Cricsheet download fails but a previously cached copy exists, that copy is served and the response carries stale: true. If no cached copy exists, the response is an error dict.

Cricket Data — Competitions & Series IDs

Cricsheet competition codes (historical backend)

Use these codes with get_matches, get_match_deliveries, and get_player_stats. Get the live list any time with get_competitions.

Codes are case-insensitive. An unknown code returns an error listing the valid codes.

ESPN series IDs (live-ish backend)

ESPN cricket has no single league: each series/tournament has its own numeric ID, used in the league slot of the URL.

• Always discover IDs with `get_series`. It returns the currently-active series with their numeric IDs.
• IDs are season-specific. A recurring tournament (e.g. IPL) gets a new ID each season — never hardcode an ID across seasons.
• The series_id from get_series is required by get_scoreboard, get_standings, get_game_summary, and get_news.