CricAtlas API Documentation
Ball-by-ball cricket data from Cricsheet, over a read-only JSON API.
- Read-only
- JSON
- No API key
- Cacheable
Overview
A read-only HTTP API for ball-by-ball cricket data. Every request is a GET, every answer is JSON, and there are no keys or accounts.
- Data
- Cricsheet's ball-by-ball records from 2001, for 15 competitions: Tests, ODIs, T20Is, IPL, WPL, BBL, WBBL, CPL, PSL, SA20, ILT20, The Hundred, MLC, LPL and BPL.
- This copy
- Dataset v3, snapshot
5fc42bc763cd, built 2026-10-13. It holds 14,585 matches, 5,852,078 balls and 9,643 players. The snapshot id is the technical name: it is what/statusand/v1/metareport and what keys caches and cursors. - Routes
- Everything is under
/v1./healthand/statuscheck the server, and/openapi.jsondescribes every route. - Licence
- Open Data Commons Attribution License 1.0. Credit Cricsheet when you use the data. Every response has a
Linkheader to the licence and anX-Attributionheader, and data routes add asourceblock. - Developer
- Developed and maintained by Ari Adaikalam. Portfolio ยท Contact
Statistics reflect the matches available in this Cricsheet snapshot and may not represent complete career records or official totals.
Quickstart
Add the address of this server in front of the path, for example curl "$API/v1/players?q=Stokes". The values shown are checked against the API by the tests, so they are what you will see.
Find a player and read their batting
Find a player by name, then use the id. The same filters work on every statistics route. Here they pick one day, the third Test of the 2019 Ashes.
1 Search for the player
A surname finds every player who has it. Choose by name and keep the player_id. Names change, ids do not.
GET /v1/players?q=StokesValues in the response
data[name=BA Stokes].player_id "e087956b"Keep player_id for the next step.
2 Read his batting for that Test
Filters apply first, then the totals are made from what is left. The average is 143 runs over one dismissal. A rate with nothing to divide by is null.
GET /v1/players/e087956b/batting?format=TEST&date_from=2019-08-22&date_to=2019-08-22Values in the response
data.matches 1
data.innings 2
data.not_outs 1
data.runs 143
data.balls_faced 232
data.highest_score 135
data.highest_score_not_out true
data.average 143.0
data.strike_rate 61.643 Split it by opponent
The same totals grouped by the side he faced. There is one group because there was one opponent. key is the stable id and label is the readable name.
GET /v1/players/e087956b/batting/splits?by=opponent&format=TEST&date_from=2019-08-22&date_to=2019-08-22Values in the response
data.by "opponent"
data.groups[0].key "Australia"
data.groups[0].label "Australia"
data.groups[0].runs 143
data.groups[0].matches 1
next_cursor nullMore examples
Find a match and read its scorecard
Find a match and read its scorecard
Search the matches by words, take the id, and read the match and its scorecard.
1 Search for the match
Four words, each part of a name: both teams, the ground and the season. One match comes back. Keep its match_id.
GET /v1/matches?q=England%20Australia%20Headingley%202019Values in the response
data[0].match_id 1152848
data[0].team_1 "England"
data[0].team_2 "Australia"
data[0].venue "Headingley"
data[0].season "2019"
data[0].start_date "2019-08-22"
next_cursor nullKeep match_id for the next step.
2 Read the match
The match with its innings. England won by one wicket. actual_overs is the balls bowled and scorecard_overs is the umpires' count.
GET /v1/matches/1152848Values in the response
data.winner "England"
data.winner_wickets 1
data.format "TEST"
data.innings[3].batting_team "England"
data.innings[3].runs 362
data.innings[3].wickets 9
data.innings[3].actual_overs "125.4"3 Read the scorecard
England's fourth innings, with the batter who won the match. His dismissal is null because he was not out.
GET /v1/matches/1152848/scorecardValues in the response
data.innings[3].total.runs 362
data.innings[3].batting[player=BA Stokes].runs 135
data.innings[3].batting[player=BA Stokes].balls 219
data.innings[3].batting[player=BA Stokes].dismissal nullFind a team and read its record
Find a team and read its record
A team is its name and the gender of the cricket. Records cover this dataset only.
1 Find the team
Use team and gender exactly as listed.
GET /v1/teams?q=England&gender=maleValues in the response
data[team=England].gender "male"
data[team=England].team "England"2 Read its record on the day of the 2019 World Cup final
The final was tied and went to a Super Over. It is a tie for both teams, with England as the eliminator winner. It is not a win, so wins is 0 and decisive_win_percentage is null.
GET /v1/teams/record?team=England&gender=male&format=ODI&date_from=2019-07-14&date_to=2019-07-14Values in the response
data.record.matches 1
data.record.wins 0
data.record.ties 1
data.record.ties_won_eliminator 1
data.record.decisive_win_percentage null
data.coverage.scope "this dataset"
data.coverage.matches 1
data.coverage.first_match "2019-07-14"3 Read a head-to-head
England against Australia in the five Tests of the 2019 Ashes: two wins each and a draw. Swap the teams and wins and losses swap. This one needs the full dataset.
GET /v1/head-to-head?team=England&opponent=Australia&gender=male&format=TEST&date_from=2019-08-01&date_to=2019-09-30Values in the response
data.record.matches 5
data.record.wins 2
data.record.losses 2
data.record.draws 1
data.record.decisive_win_percentage 50.0Needs the full dataset.
Read a long list a page at a time
Read a long list a page at a time
Pass next_cursor back as cursor to read on, and stop when it is null.
1 The first page
Two matches, newest first, and a next_cursor because there are more.
GET /v1/matches?q=England&limit=2Values in the response
next_cursor a signed cursorKeep cursor for the next step.
2 The next page
The cursor continues where the list stopped. Keep the same q and other parameters.
GET /v1/matches?q=England&limit=2&cursor=NEXT_CURSORValues in the response
data the next two matchesWhat a refused request looks like
What a refused request looks like
Every error is a problem document with a status, a plain reason and a request id to quote.
1 A missing required parameter
gender is always required for a team.
GET /v1/teams/record?team=EnglandValues in the response
status 422
title "Invalid parameter"
parameter "gender"2 A match that does not exist
An unknown id is a 404. Any unknown route gives the same answer.
GET /v1/matches/999999999Values in the response
status 404
title "Not found"Coverage
Everything here is about the matches in this dataset. It starts in 2001, because Cricsheet has no ball-by-ball data earlier, and it covers only the 15 competitions above. A player's career, a team's record and a leaderboard are all made from these matches, and none of them is a complete history.
CricAtlas calculates statistics from the matches included in its Cricsheet snapshot. Cricsheet does not provide every cricket match, and some matches are withheld or unavailable. Consequently, runs, wickets, appearances, centuries and other totals may differ from official career statistics. A missing match is absent data, not a zero-performance result. Use /v1/meta to check the snapshot date and version.
Team record and head-to-head responses say so: coverage.scope is this dataset. coverage also gives the number of matches and the dates of the first and last of them, for the whole filtered result and not just the page returned. The dates are null when the result is empty.
IDs and search
Search to find an id, then use the id. Names have several spellings. Ids do not change.
| What | Identified by | Find it with |
|---|---|---|
| Match | match_id, Cricsheet's match number | /v1/matches?q= |
| Player | player_id, Cricsheet's id for the person | /v1/players?q=, any spelling of the name |
| Team | its name and its gender, because men's and women's teams share names | /v1/teams?q= |
| Competition | the Cricsheet code, such as ipl, tests or hnd | /v1/competitions?q= |
| Venue | its name as Cricsheet records it | /v1/venues?q= |
qis a few words separated by spaces. Each word is matched, ignoring case, as a piece of a name, and every word has to match something.England Australia Headingley 2019finds that Test.- Matches search the teams, event, competition code, venue, city and season. Competitions search the event name and code.
- At most 120 characters, 8 different words and 40 characters in a word. A search that finds nothing is an empty list, not an error.
teamwithopponenton/v1/matchesselects a pairing in either order.- A team that changed its name is more than one team. A season is Cricsheet's label, such as
2019or2019/20.
Filters
Statistics routes share these filters: collection, format (TEST, ODI or T20), gender, season, date_from and date_to. Filters apply before anything is counted, so every total and rate is made from the matches that are left.
Dates select matches by start date, both ends included. A match is in or out as a whole. A Test that starts on date_to brings in all its days, and a Test that started before date_from is out even if play carried on inside the range.
- Team routes always need
gender. - An unknown parameter is a 400. A value that is not allowed is a 422.
- Filters combine: every one has to hold.
Pagination
A long list comes one of two ways, and each route is one or the other.
Cursor paging never drops a result. limit sets the page size. When there is more, the response has next_cursor. Pass it back as cursor with the same other parameters, and stop when it is null. A cursor is signed, belongs to one route and one data version, and is refused with a 400 if it was changed or is out of date.
| Cursor-paged route | Default limit | Largest limit |
|---|---|---|
/v1/head-to-head/splits | 100 | 200 |
/v1/matches | 50 | 500 |
/v1/matches/{match_id}/innings/{innings}/balls | 100 | 1000 |
/v1/players/{player_id}/batting/splits | 100 | 200 |
/v1/players/{player_id}/bowling/splits | 100 | 200 |
/v1/players/{player_id}/fielding/splits | 100 | 200 |
/v1/players/{player_id}/matches | 50 | 200 |
/v1/teams/record/splits | 100 | 200 |
Capped lists have a limit and no cursor. They return the first limit results in order, and a longer list is cut. Narrow the request with q or a filter to reach the rest.
| Capped route | Default limit | Largest limit |
|---|---|---|
/v1/leaderboards/batting | 25 | 100 |
/v1/leaderboards/bowling | 25 | 100 |
/v1/players | 25 | 100 |
/v1/teams | 100 | 500 |
/v1/venues | 100 | 500 |
Matches come newest first. Splits and team groups come most matches first, then by key from A to Z. Other routes are short by nature.
Statistics rules
A rate is made from summed numerators and denominators, never from other rates. When there is nothing to divide by, the rate is null, not zero.
- Economy is runs per six balls in every format. A batter's strike rate is runs per 100 balls faced. A bowler's is balls per wicket.
- A highest score or best figure is not additive. A group's is its own best, and the career's is the best of the groups.
- A wide is not a ball faced and a no ball is. Runs charged to a bowler are runs off the bat, wides and no balls. Byes, leg byes and penalty runs are not.
Leaderboards need a sample before they rank a ratio. Any minimum can be set from 1 up, the minimums used come back in the response, and they are judged on the totals of the requested filters. There is no minimum of runs. The defaults are this API's own choice, not an official qualification rule.
| Ranking | min_balls | Other minimum |
|---|---|---|
| Batting average | 500 | min_dismissals 20 |
| Batting strike rate | 500 | none |
| Bowling average and strike rate | 300 | min_wickets 10 |
| Bowling economy | 300 | none |
Leaderboards rank on the unrounded value and show it to two places. A tie goes to more balls, then more matches, then the smaller player id.
Cricket rules
- Super Overs
- A Super Over is a separate pair of innings that settles a tie. The scorecard and the balls of a match include it, and the match's innings list marks it with
is_super_over. Every total that adds up over matches leaves it out: career, season and split statistics, leaderboards, matchups and fielding. A player's match history still records the appearance, withsuper_over. - Results
- A team's record counts each match once as a win, loss, draw, tie or no result, and
matchesis their sum. A win includes Duckworth-Lewis and awarded wins. A tie is neither a win nor a loss. When a Super Over or bowl-out settled it, Cricsheet names an eliminator winner, shown beside the tie asties_won_eliminator,ties_lost_eliminatororties_no_eliminator, and these add up toties. No result includes matches abandoned after play began.decisive_win_percentageis wins over wins plus losses, andnullwhen there are no decisive matches. The 2019 World Cup final, tied at 241 each, is a tie for England and for New Zealand, with England as the eliminator winner. - Dismissals
- A dismissal is any way a batter's innings ended except retired hurt and retired not out. A wicket credited to a bowler is only bowled, caught, caught and bowled, lbw, stumped or hit wicket. A run out or a retirement out is a dismissal and not a bowler's wicket. A delivery with two wickets gives each batter a dismissal.
- Overs
actual_overscounts the legal balls bowled, so 146.1 is 146 overs and one ball.scorecard_oversis the umpires' count, from the over boundaries Cricsheet records, and isnullwhen the source cannot settle it. A set in The Hundred is five balls.- Maidens
- A maiden is an over confirmed complete, bowled whole by one bowler, with no run charged to them. An over shared by two bowlers, an unfinished last over, or one whose listed count the balls contradict is not a maiden.
- Fielding
- Fielding comes from Cricsheet's lists of fielders on each wicket, and the lists are incomplete. About 18 in 100 run outs have no fielder listed. Run out involvements are therefore a floor. A catch is a caught wicket with the player as a named fielder. Caught and bowled has no fielder row, so it is counted apart. A run out involvement goes to every named fielder once and is not a direct hit. A substitute fielder's credits are counted apart. In fielding groups,
matchesis the number of matches with a recorded credit. - Players
- A player is anyone Cricsheet names as one: a batter, bowler, squad member, named fielder, dismissed player, absent-hurt player or replacement.
/v1/players/{id}gives the chosen name and the other spellings (aliases), and/v1/players?q=searches all of them. A known player with no records inside the filters gets a 200 with zero totals andnullrates. Only an unknown id is a 404.
Errors
Every error is a problem document, application/problem+json, with type, title, status, detail, instance and a request_id, and parameter when one parameter is to blame. Errors say nothing about the server and are never cached.
| Status | Meaning | Common cause |
|---|---|---|
| 400 | Bad request | an unknown parameter, a changed or out-of-date cursor, an unknown field name |
| 404 | Not found | an unknown match, player, team or route |
| 405 | Method not allowed | anything but GET or OPTIONS |
| 413 | Request too large | a request body, which this API never takes |
| 422 | Invalid parameter | a value that is not allowed, a missing required parameter, a team given as its own opponent |
| 429 | Too many requests | the rate limit. Retry-After says how many seconds to wait |
| 500 | Server error | a fault. Quote the request_id when you ask about it |
| 503 | Busy | the server is busy or a query was too slow. Narrow it with a filter and retry after Retry-After |
Limits and retries
Each client has a token bucket that refills at 60 tokens a minute and holds at most 20. The client is the address the request comes from, and an IPv6 client is the network made of the first 64 bits of its address. A request costs tokens by how heavy it is, and one that finds too few gets a 429 with Retry-After.
| Cost in tokens | Routes |
|---|---|
| Not counted | /health |
| 1 | /status, /v1/competitions, /v1/matches, /v1/matches/{match_id}, /v1/matches/{match_id}/notes, /v1/matches/{match_id}/powerplays, /v1/matches/{match_id}/replacements, /v1/matches/{match_id}/reviews, /v1/matches/{match_id}/wickets, /v1/meta, /v1/players, /v1/players/{player_id}, /v1/players/{player_id}/batting, /v1/players/{player_id}/batting/seasons, /v1/players/{player_id}/batting/splits, /v1/players/{player_id}/bowling, /v1/players/{player_id}/bowling/seasons, /v1/players/{player_id}/bowling/splits, /v1/players/{player_id}/fielding, /v1/players/{player_id}/fielding/seasons, /v1/players/{player_id}/fielding/splits, /v1/teams, /v1/venues |
| 2 | /v1/matchups, /v1/players/{player_id}/matches |
| 3 | /v1/head-to-head, /v1/head-to-head/splits, /v1/matches/{match_id}/innings/{innings}/balls, /v1/matches/{match_id}/scorecard, /v1/teams/record, /v1/teams/record/splits |
| 5 | /v1/leaderboards/batting, /v1/leaderboards/bowling |
- A response that counts against the limit carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset, unless a shared cache may store it./healthis never counted. - Every answer except one a shared cache may store carries
X-Request-ID. Quote it when you ask about a fault.
When the server is busy
A request that needs the database is admitted before it runs. At most 4 run at once, in three classes. Heavy requests may use at most 2 of the units, and heavy and medium together at most 3, so a light request always has a unit. A request that cannot start waits in a small room for a fixed time, and one that finds the room full is refused at once. A client may have one heavy request running or waiting. These sizes are starting values, not measured capacity.
| Class | Waiting room | Longest wait | Routes |
|---|---|---|---|
| heavy | 4 | 1 s | /v1/leaderboards/batting, /v1/leaderboards/bowling |
| medium | 8 | 1.5 s | /v1/matches/{match_id}/scorecard, /v1/players/{player_id}/batting, /v1/players/{player_id}/bowling, /v1/players/{player_id}/fielding, /v1/players/{player_id}/batting/seasons, /v1/players/{player_id}/bowling/seasons, /v1/players/{player_id}/fielding/seasons, /v1/players/{player_id}/matches, /v1/players/{player_id}/batting/splits, /v1/players/{player_id}/bowling/splits, /v1/players/{player_id}/fielding/splits, /v1/matchups |
| light | 32 | 1.5 s | /v1/competitions, /v1/teams, /v1/venues, /v1/players, /v1/matches, /v1/matches/{match_id}, /v1/matches/{match_id}/innings/{innings}/balls, /v1/matches/{match_id}/powerplays, /v1/matches/{match_id}/reviews, /v1/matches/{match_id}/replacements, /v1/matches/{match_id}/wickets, /v1/matches/{match_id}/notes, /v1/players/{player_id}, /v1/teams/record, /v1/teams/record/splits, /v1/head-to-head, /v1/head-to-head/splits |
Routes that need no database (/health, /status, /v1/meta, /openapi.json, /docs, /docs/assets/docs.css) are not admitted and are served without a query.
| Answer | Meaning | What to do |
|---|---|---|
| 429 problem document | the rate limit, or a second heavy request from one client | wait Retry-After seconds, then retry |
| 503 problem document | the room for the route's class was full, or the wait ran out | wait Retry-After seconds, then retry with a longer pause each time |
503 in plain text (Service Unavailable) | the server's own limit of 100 connections was reached. It has no request_id and none of this API's headers | treat any 503 as a retry and do not rely on a body or header |
- For a 429 or 503, wait at least
Retry-Afterwhen it is given. Otherwise start at 1 second, double the wait each time with a random pause of up to half of it, stop doubling at 30 seconds, give up after a few tries, and never repeat the same request in parallel. - A refused request still costs tokens, so a client that keeps asking a busy server empties its own allowance and then gets a 429.
Caching
Every cacheable successful answer carries an ETag and a Cache-Control header. The ETag is made from the answer and the data version, so it changes when the data does and when anything in the request changes the answer. A different filter, field selection, page or cursor is a different cache entry.
| Kind | Cache-Control | Routes |
|---|---|---|
| match | public, max-age=86400 | a match, its scorecard, its balls and its powerplays, reviews, replacements, wickets and notes |
| computed | public, max-age=3600 | statistics, splits, leaderboards, matchups, team and head-to-head records, match and player histories, searches, and the lists of competitions, teams, venues and players |
| reference | public, max-age=3600 | /v1/meta, /openapi.json and the documentation page and its stylesheet |
| no-store | no-store | /health, /status, and every error and rate limit refusal |
- A cached copy is reused until its time is up, so after the data changes an answer can be up to an hour old, and a match answer up to a day.
- Send the ETag back as
If-None-Match. An unchanged answer is a 304 with no body, and it carries the sameETagandCache-Control. AW/prefix is ignored when comparing, and*is ignored. - Errors, rate limit refusals,
/healthand/statusare never stored:Cache-Control: no-store./healthand/statuscarry noETag. - Behind a shared cache, a cacheable answer carries none of
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Request-IDorX-Response-Time-Ms, because the cache would hand them to the next client. The licenceLinkandX-Attributionstay. A cached answer is not counted against your limit, because the server never sees the request.
Reference
Made from the OpenAPI document at /openapi.json, so it matches the routes. Every route takes GET only.
Common parameters
These query parameters are written the same way on many routes. A route lists the ones it takes under its summary.
| Parameter | Type | Notes |
|---|---|---|
collection | one of tests, odis, t20s, ipl, wpl, bbl, wbb, cpl, psl, sat, ilt, hnd, mlc, lpl, bpl or null | Include only this competition, by its Cricsheet collection code. |
gender | one of male, female or null | |
season | string or null | 1 or more characters, at most 20 characters; Include only this season, as Cricsheet labels it, such as 2019 or 2019/20. |
format | one of TEST, ODI, T20 or null | Include only this format of the game. |
date_from | date or null | Include matches that started on or after this date |
date_to | date or null | Include matches that started on or before this date |
cursor | string or null | at most 400 characters |
Server
Check the server, and read the data version, row counts and licence.
GET /health
Liveness: the process is up
No parameters.
Response fields Health
status stringGET /status
Data age and request counters, nothing about the host
No parameters.
Response fields Status
data_version string
data_built_utc string
snapshot_date string or null
started_utc string
requests integer
client_errors integer
server_errors integer
rate_limited integerGET /v1/meta
The data version, row counts, features and the source and licence
No parameters.
Response fields MetaData
api_version string
data_version string
data_built_utc string
snapshot_date string or null
features Features
tables map of TableInfo
source_url string
licence string
licence_url string
attribution stringLookups
Find ids and names: competitions, teams, venues and players.
GET /v1/competitions
Competitions with their match counts and dates, searchable by name
Also takes collection (common parameters)
| Parameter | Type | Notes |
|---|---|---|
q | string or null | 1 or more characters, at most 120 characters; Keywords, all of which must be part of the event name or the collection code |
Response fields Competition
collection string or null
event string or null
type string or null
format string or null
gender string or null
matches integer
first_match date or null
last_match date or nullGET /v1/players
Search players by any spelling of their name
| Parameter | Type | Notes |
|---|---|---|
q required | string | 2 or more characters, at most 60 characters |
limit | integer | at least 1, at most 100; default 25 |
Response fields PlayerHit
player_id string or null
name string or nullGET /v1/teams
Teams with their match counts, one entry for each team and gender
Also takes collection gender (common parameters)
| Parameter | Type | Notes |
|---|---|---|
q | string or null | 1 or more characters, at most 60 characters |
limit | integer | at least 1, at most 500; default 100 |
Response fields TeamEntry
team string
gender string or null
matches integerGET /v1/venues
Venues with their match counts
Also takes collection (common parameters)
| Parameter | Type | Notes |
|---|---|---|
q | string or null | 1 or more characters, at most 60 characters |
limit | integer | at least 1, at most 500; default 100 |
Response fields VenueEntry
venue string
matches integerMatches
List matches, then read one match, its scorecard, its balls and its notes.
GET /v1/matches
Matches, newest first, filtered, searchable and paged
Also takes collection season format gender date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
event | string or null | 1 or more characters, at most 120 characters |
team | string or null | 1 or more characters, at most 120 characters |
opponent | string or null | 1 or more characters, at most 120 characters; With team: only matches between the two, whichever side each was on |
venue | string or null | 1 or more characters, at most 160 characters |
q | string or null | 1 or more characters, at most 120 characters; Keywords, each of which must be part of a team, event, collection code, venue, city or season |
limit | integer | at least 1, at most 500; default 50 |
Response fields Match
match_id integer or null
season string or null
start_date date or null
gender string or null
event string or null
format string or null
type string or null
venue string or null
match_number integer or null
toss_winner string or null
toss_decision string or null
player_of_match string or null
player_of_match_2 string or null
winner string or null
winner_runs integer or null
winner_wickets integer or null
outcome string or null
team_1 string or null
team_2 string or null
city string or null
end_date date or null
scheduled_overs integer or null
balls_per_over integer or null
match_type_number integer or null
collection string or null
result_method string or null
eliminator string or null
umpire_1 string or null
umpire_2 string or null
tv_umpire string or null
match_referee string or null
won_by_innings true or false or null
cricsheet_created date or null
cricsheet_revision integer or null
cricsheet_data_version string or null
event_group string or null
event_sub_name string or null
event_stage string or nullGET /v1/matches/{match_id}
One match: its details, innings totals, squads and officials
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields MatchDetail
match_id integer or null
season string or null
start_date date or null
gender string or null
event string or null
format string or null
type string or null
venue string or null
match_number integer or null
toss_winner string or null
toss_decision string or null
player_of_match string or null
player_of_match_2 string or null
winner string or null
winner_runs integer or null
winner_wickets integer or null
outcome string or null
team_1 string or null
team_2 string or null
city string or null
end_date date or null
scheduled_overs integer or null
balls_per_over integer or null
match_type_number integer or null
collection string or null
result_method string or null
eliminator string or null
umpire_1 string or null
umpire_2 string or null
tv_umpire string or null
match_referee string or null
won_by_innings true or false or null
cricsheet_created date or null
cricsheet_revision integer or null
cricsheet_data_version string or null
event_group string or null
event_sub_name string or null
event_stage string or null
innings list of InningsSummary
squads map of list of SquadMember
officials list of OfficialGET /v1/matches/{match_id}/innings/{innings}/balls
The balls of an innings, in order, paged
Also takes cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
innings path required | integer | at least 1, at most 8 |
fields | string or null | at most 600 characters |
limit | integer | at least 1, at most 1000; default 100 |
Response fields Ball
match_id integer or null
season string or null
start_date date or null
innings integer or null
delivery_number integer or null
over integer or null
ball_in_over integer or null
scorecard_ball number or null
is_legal_delivery true or false or null
batting_team string or null
bowling_team string or null
striker string or null
striker_id string or null
non_striker string or null
bowler string or null
bowler_id string or null
runs_off_bat integer or null
extras integer or null
wides integer or null
noballs integer or null
byes integer or null
legbyes integer or null
penalty integer or null
wicket_type string or null
player_dismissed string or null
other_wicket_type string or null
other_player_dismissed string or null
wicket integer or null
striker_balls_faced integer or null
total_striker_runs integer or null
player_out_runs integer or null
player_out_balls_faced integer or null
gender string or null
event string or null
format string or null
type string or null
country_striker string or null
batting_style_striker string or null
bowling_style_striker string or null
playing_role_striker string or null
striker_age integer or null
country_bowler string or null
batting_style_bowler string or null
bowling_style_bowler string or null
playing_role_bowler string or null
bowler_age integer or null
fielder_1 string or null
fielder_1_id string or null
fielder_1_substitute true or false or null
non_boundary true or false or nullGET /v1/matches/{match_id}/notes
What the source says about gaps and oddities: missing data, miscounted overs, absent hurt and the match dates
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields Notes
missing_data list of MissingData
miscounted_overs list of MiscountedOver
absent_hurt list of AbsentHurt
dates list of MatchDateGET /v1/matches/{match_id}/powerplays
The powerplays of every innings, with their boundaries as an over, a position and a delivery number
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields Powerplay
innings integer
powerplay_number integer
type string or null
start Boundary
end BoundaryGET /v1/matches/{match_id}/replacements
Players replaced during a match, in order
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields Replacement
innings integer
delivery_number integer
replacement_number integer
over integer or null
ball_in_over integer or null
kind string or null
team string or null
role string or null
player_in string or null
player_in_id string or null
player_out string or null
player_out_id string or null
reason string or nullGET /v1/matches/{match_id}/reviews
The decision reviews of a match, in the order they were made
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields Review
review_number integer
innings integer
delivery_number integer
over integer or null
ball_in_over integer or null
review_by string or null
umpire string or null
umpire_id string or null
batter string or null
batter_id string or null
decision string or null
review_type string or null
umpires_call true or false or nullGET /v1/matches/{match_id}/scorecard
The scorecard: batting, bowling, extras and fall of wickets for every innings
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields Scorecard
match_id integer
balls_per_over integer
innings list of ScorecardInningsGET /v1/matches/{match_id}/wickets
Every wicket of a match with its fielders, retirements included
| Parameter | Type | Notes |
|---|---|---|
match_id path required | integer | at least 1, at most 2147483647 |
Response fields MatchWicket
sequence integer
innings integer
delivery_number integer
wicket_number integer
over integer or null
ball_in_over integer or null
player_dismissed string or null
player_dismissed_id string or null
wicket_type string or null
bowler string or null
bowler_id string or null
credited_to_bowler true or false
fielders list of WicketFielderPlayers
A player's career, season by season and by split, and the matches they played.
GET /v1/players/{player_id}
A player: name, other spellings, teams and ids in other systems
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields PlayerProfile
player_id string
name string or null
aliases list of string
teams list of PlayerTeam
external_ids list of ExternalIdGET /v1/players/{player_id}/batting
A player's career batting, with filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields BattingCareer
player_id string
name string or null
matches integer
innings integer
not_outs integer
runs integer
balls_faced integer
highest_score integer or null
highest_score_not_out true or false or null
average number or null
strike_rate number or null
fifties integer
hundreds integer
ducks integer
fours integer
sixes integerGET /v1/players/{player_id}/batting/seasons
A player's batting season by season, oldest first
Also takes collection format gender date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields BattingSeasons
player_id string
name string or null
seasons list of BattingSeasonGET /v1/players/{player_id}/batting/splits
A player's batting by opponent, venue, competition or format
Also takes collection format gender season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) | |
by required | one of opponent, venue, competition, format | |
limit | integer | at least 1, at most 200; default 100 |
Response fields BattingSplits
player_id string
name string or null
by one of opponent, venue, competition, format
groups list of BattingSplitGET /v1/players/{player_id}/bowling
A player's career bowling, with filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields BowlingCareer
player_id string
name string or null
matches integer
innings integer
balls integer
runs integer
wickets integer
maidens integer
average number or null
economy number or null
strike_rate number or null
best_wickets integer or null
best_runs integer or null
four_wicket_hauls integer
five_wicket_hauls integer
wides integer
noballs integerGET /v1/players/{player_id}/bowling/seasons
A player's bowling season by season, oldest first
Also takes collection format gender date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields BowlingSeasons
player_id string
name string or null
seasons list of BowlingSeasonGET /v1/players/{player_id}/bowling/splits
A player's bowling by opponent, venue, competition or format
Also takes collection format gender season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) | |
by required | one of opponent, venue, competition, format | |
limit | integer | at least 1, at most 200; default 100 |
Response fields BowlingSplits
player_id string
name string or null
by one of opponent, venue, competition, format
groups list of BowlingSplitGET /v1/players/{player_id}/fielding
A player's career fielding, with filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields FieldingCareer
player_id string
name string or null
catches integer
catches_as_fielder integer
caught_and_bowled integer
stumpings integer
run_out_involvements integer
substitute_involvements integerGET /v1/players/{player_id}/fielding/seasons
A player's fielding season by season, oldest first
Also takes collection format gender date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) |
Response fields FieldingSeasons
player_id string
name string or null
seasons list of FieldingSeasonGET /v1/players/{player_id}/fielding/splits
A player's fielding by opponent, venue, competition or format
Also takes collection format gender season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) | |
by required | one of opponent, venue, competition, format | |
limit | integer | at least 1, at most 200; default 100 |
Response fields FieldingSplits
player_id string
name string or null
by one of opponent, venue, competition, format
groups list of FieldingSplitGET /v1/players/{player_id}/matches
The matches a player is connected to, newest first, with what the records say about their part
Also takes collection format gender season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
player_id path required | string (an id) | |
limit | integer | at least 1, at most 200; default 50 |
Response fields PlayerMatch
match_id integer
start_date date or null
season string or null
event string or null
collection string or null
format string or null
gender string or null
venue string or null
city string or null
team_1 string or null
team_2 string or null
winner string or null
outcome string or null
team string or null
in_squad true or false
batted true or false
bowled true or false
fielded true or false
fielded_as_substitute true or false
absent_hurt true or false
replaced_in true or false
replaced_out true or false
super_over true or false
recorded_on_field true or falseLeaderboards
The top players for a batting or bowling statistic.
GET /v1/leaderboards/batting
Batting leaders for a metric, with eligibility and filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
metric required | one of runs, average, strike_rate, hundreds, fifties, fours, sixes, highest_score | |
limit | integer | at least 1, at most 100; default 25 |
min_balls | integer or null | at least 1, at most 1000000 |
min_dismissals | integer or null | at least 1, at most 1000000 |
Response fields BattingLeaderboard
metric string
order one of desc, asc
eligibility BattingEligibility
limit integer
leaders list of BattingLeaderGET /v1/leaderboards/bowling
Bowling leaders for a metric, with eligibility and filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
metric required | one of wickets, maidens, five_wicket_hauls, average, economy, strike_rate, best_figures | |
limit | integer | at least 1, at most 100; default 25 |
min_balls | integer or null | at least 1, at most 1000000 |
min_wickets | integer or null | at least 1, at most 1000000 |
Response fields BowlingLeaderboard
metric string
order one of desc, asc
eligibility BowlingEligibility
limit integer
leaders list of BowlingLeaderMatchups
One batter against one bowler.
GET /v1/matchups
One batter against one bowler, with filters
Also takes collection format gender season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
batter required | string (an id) | |
bowler required | string (an id) |
Response fields Matchup
batter MatchupPlayer
bowler MatchupPlayer
matches integer
innings integer
deliveries integer
balls_faced integer
runs integer
fours integer
sixes integer
strike_rate number or null
dismissals integer
bowler_wickets integer
average number or null
balls_per_dismissal number or null
dismissal_kinds list of DismissalKindTeams and head-to-head
Team results, and one team against another.
GET /v1/head-to-head
One team's record against another, whichever side each was on
Also takes collection format season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
team required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
opponent required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
gender required | one of male, female | The gender of the cricket |
Response fields HeadToHeadData
team string
opponent string
gender one of male, female
record TeamRecord
coverage CoverageGET /v1/head-to-head/splits
A head-to-head record by venue, competition, format or season
Also takes collection format season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
team required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
opponent required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
gender required | one of male, female | The gender of the cricket |
by required | one of venue, competition, format, season | |
limit | integer | at least 1, at most 200; default 100 |
Response fields HeadToHeadSplitsData
team string
opponent string
gender one of male, female
by one of venue, competition, format, season
coverage Coverage
groups list of RecordSplitGET /v1/teams/record
A team's results: wins, losses, draws, ties and no results
Also takes collection format season date_from date_to (common parameters)
| Parameter | Type | Notes |
|---|---|---|
team required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
gender required | one of male, female | The gender of the cricket |
Response fields TeamRecordData
team string
gender one of male, female
record TeamRecord
coverage CoverageGET /v1/teams/record/splits
A team's results by opponent, venue, competition, format or season
Also takes collection format season date_from date_to cursor (common parameters)
| Parameter | Type | Notes |
|---|---|---|
team required | string | 1 or more characters, at most 120 characters; A team name as /v1/teams lists it |
gender required | one of male, female | The gender of the cricket |
by required | one of opponent, venue, competition, format, season | |
limit | integer | at least 1, at most 200; default 100 |
Response fields TeamSplitsData
team string
gender one of male, female
by one of opponent, venue, competition, format, season
coverage Coverage
groups list of RecordSplitDeveloper & Contact
- Name
- Ari Adaikalam
- Portfolio
- ariadaikalam.com
- ariadaikalam1234@gmail.com
Bug reports, data discrepancies and suggestions are welcome. Please email them.
To make a report easy to follow, include the endpoint, the parameters you sent, what you expected and what you got, and the request ID if available: it is in the request_id of an error and in the X-Request-ID header, but a cached successful answer may carry none. Never send passwords, tokens or keys: this API has none, and nobody needs them to look into a report.