python-espncricinfo

A Python client for ESPNcricinfo match, series, season, team and player data.

Description

Match pages are loaded with Playwright (WebKit), because ESPN's CDN refuses plain HTTP clients; player, series, season and team records come from ESPN's core JSON API. A Match needs only a match_id; Match.get_recent_matches() and Series(...).matches list them.

Disclaimer: This library is not intended for commercial use and neither it nor its creator has any affiliation with ESPNCricInfo. The LICENSE for this library applies only to the code, not to the data.

Installation

uv add python-espncricinfo

Or with pip:

pip install python-espncricinfo

After installation, install the Playwright WebKit browser (required for fetching match data):

uv run playwright install webkit

Recent matches

Summary().matches lists the matches on ESPNcricinfo's results page. Pass a date to look back; ESPN returns about two weeks of matches ending on that day.

>>> from espncricinfo.match import Match
>>> refs = Match.get_recent_matches(date="2026-02-28")
>>> len(refs)
195
>>> refs[0]
MatchRef(series_id=1523975, match_id=1523981)
>>> series_id, match_id = refs[0]  # MatchRefs unpack like tuples

For one day only, Match.get_matches_on("2026-10-20") keeps the matches played that day, multi-day matches included on each of their days. Summary(date=...) wraps the same call; its result is in .matches.

A single match

A match needs only its match ID, the number in a match page URL. Passing the series ID too (Match(1478914, 1478874), or MatchRef.to_match()) skips a redirect. Loading a match starts a headless WebKit browser.

>>> m = Match(1478914)
>>> m.description
'IND Women v AUS Women'
>>> m.match_class
'WT20I'
>>> m.result
'IND Women won by 17 runs'
>>> m.batting_scorecard[0][0]["name"], m.batting_scorecard[0][0]["runs"]
('S Mandhana', 82)
>>> m.bowling_scorecard[0][0]["name"], m.bowling_scorecard[0][0]["wickets"]
('D Brown', 0)

To work through every match of a format, list a year's match IDs from Statsguru (1 Test, 2 ODI, 3 T20I, 8/9/10 the women's formats) and load each one. Each load starts a browser, so a year of Tests takes a minute or two:

>>> ids = Match.get_match_ids(2023, 1)
>>> len(ids)
34
>>> Match(ids[0]).description
'New Zealand v Pakistan'

batting_scorecard and bowling_scorecard hold one list per innings and one dict per player. over_by_over gives runs and wickets for every over, and each m.innings entry has fours and sixes.

m.ground loads the ground record (Ground in espncricinfo.grounds): name, city, country, capacity.

Players

The player ID is the number at the end of a player's profile URL.

>>> from espncricinfo.player import Player
>>> p = Player(277916)
>>> p.full_name
'Ajinkya Madhukar Rahane'
>>> p.get_data(file_name="rahane_tests.csv", match_format=1, data_type="batting")

get_data writes one row per match (85 Tests for Rahane); get_career_summary and get_career_averages write the summary tables from the same Statsguru page.

Series, seasons and teams

>>> from espncricinfo.series import Series
>>> ipl = Series(1449924)
>>> ipl.name
'Indian Premier League'
>>> season = ipl.current_season
>>> season.year, len(season.teams)
(2025, 10)
>>> season.teams[0].name
'Chennai Super Kings'

Seasons that cross New Year, like the Big Bash League's, each have their own series ID. Look one up by the label ESPNcricinfo shows:

>>> bbl = Series(8044)
>>> season = bbl.season("2024/25")  # also 2024, "2024-25" or "2024/2025"
>>> season.label, season.series_id
('2024/25', 1443056)

series.season_objects lists every season and season.match_refs that season's matches. series.matches collects MatchRefs across all seasons (1,254 for the IPL), and series.current_matches keeps those in progress. team.players loads the squad on demand. ESPN's records for some bilateral tours are incomplete, for example listing one team for a two-team series.

Development

Unit tests (no network required — uses recorded fixtures):

uv run pytest

Integration tests (hits live ESPN Cricinfo via Playwright):

uv run pytest --live

Refreshing fixtures (re-records fixtures from live site):

uv run python scripts/refresh_fixtures.py

Integration tests and the fixture refresh need the WebKit browser:

uv run playwright install webkit