Introduction to the JSON format
This document details the JSON data provided by Cricsheet. It describes the organisation of the file and attempts to give some idea of the possible contents for each field.
The current version number for the JSON format is 1.1.0, but you can also see the changes that have happened over time in the changelog.
The meta
section
"meta": {
"data_version": "1.1.0",
"created": "2020-07-06",
"revision": 1
}
The meta
section contains details related to the data file itself, specifically the version of the data format, the date the file was created, and the revision of the file.
Field | Description |
---|---|
data_version |
string (required) The version of the data format the file contains, in this case 1.0.0. This version number updates when the data format changes, and follows the semantic versioning rules. |
created |
string (required) The date on which the data file was first created. This will be in the format YYYY-MM-DD. |
revision |
integer (required) The revision number for this data version of the file. When first created this will be 1, and it will increment on subsequent revisions. |
The info
section
"info": {
"balls_per_over": 6,
"venue": "Daren Sammy National Cricket Stadium, Gros Islet",
"dates": [
"2016-07-26"
],
"event": {
"name": "Caribbean Premier League",
"match_number": 24
},
"gender": "male",
"teams": [
"St Lucia Zouks",
"Trinbago Knight Riders"
],
"outcome": {
"winner": "Trinbago Knight Riders",
"by": {
"wickets": 3
}
},
"toss": {
"decision": "field",
"winner": "Trinbago Knight Riders"
},
"player_of_match": [
"Umar Akmal"
],
"match_type": "T20",
"overs": 20,
"team_type": "club",
"registry": {
"people": {
"ADS Fletcher": "1bae756b-ce38-4b99-af93-d34c8dadc379",
"AP Devcich": "ed90abe4-c676-4501-b7df-ad80935e8e1b",
"BB McCullum": "b8a55852-72a5-4667-999d-28f845354af9",
"C Munro": "af2c687b-04d1-4fd0-bcc0-61e7fdbe4ef4",
"D Ramdin": "d1523761-c316-4e18-92f7-6e048af72422",
"DE Johnson": "c0babb93-b6a0-43e8-bfe5-00c1a38c3fd3",
"DJ Bravo": "87e562a9-a160-4e25-bbac-5d70c61b754f",
"DJG Sammy": "c03c6200-a23c-43ab-8b77-76b71fae379b",
"Denavon Hayles": "5cbeeb02-fa35-4ee0-8dc8-84873c42044d",
"GD Elliott": "c03449e0-5c0d-480b-901f-c744a56737e5",
"J Charles": "09a9d073-9f18-486a-8d67-1ba665a1bae4",
"JD Cloete": "b0419f8c-68dc-4d18-8727-f51227a9a3be",
"JE Taylor": "4180d897-7347-482a-a1d2-ac51bf262eae",
"K Lesporis": "fb496f7a-d8f3-4c59-8ec8-829647161bb9",
"KK Cooper": "557153ca-f977-4398-a2f0-f47c10b44929",
"KR Mayers": "73c18486-c4e8-4708-830d-0d7b700361d5",
"MEK Hussey": "48fd7349-6426-4791-806b-0644a8d8ae5c",
"NO Miller": "ea3ffd1b-23f2-4490-8796-074cfb5b90ce",
"PA Gustard": "25bcf808-a2d9-4d8b-8bca-37977305221c",
"RR Beaton": "684a56df-eaf3-4191-8887-7f4c7cfe55e2",
"S Shillingford": "d76b0d2d-f791-423b-950f-4a6d022b1db8",
"SP Narine": "9d430b40-abd3-472f-9dc6-45129c0f41ea",
"SR Watson": "4329fbb5-8f2d-4fe8-bddb-6f34c9815a4a",
"Umar Akmal": "fd2bf2a0-1a89-430c-9a7d-f34eaf7b120d",
"WKD Perkins": "1920c721-f06c-45e9-b8a7-f938774f9fc8",
"Zahid Bassarath": "ca6bf044-4d96-4a41-94af-9d6f6c6fc46a"
}
},
"city": "St Lucia",
"officials": {
"match_referees": [
"Denavon Hayles"
],
"tv_umpires": [
"Zahid Bassarath"
],
"umpires": [
"JD Cloete",
"PA Gustard"
]
},
"players": {
"St Lucia Zouks": [
"J Charles",
"ADS Fletcher",
"SR Watson",
"MEK Hussey",
"GD Elliott",
"DJG Sammy",
"KR Mayers",
"DE Johnson",
"S Shillingford",
"K Lesporis",
"JE Taylor"
],
"Trinbago Knight Riders": [
"WKD Perkins",
"BB McCullum",
"C Munro",
"D Ramdin",
"Umar Akmal",
"DJ Bravo",
"AP Devcich",
"SP Narine",
"KK Cooper",
"NO Miller",
"RR Beaton"
]
},
"season": "2016"
}
The info
section contains the information on the actual match, such as when and where it was played, any event it was part of, the type of match etc. Some of the fields are required, whereas some are optional.
Field | Description |
---|---|
balls_per_over |
integer (required) The number of balls expected per over, generally 6. |
bowl_out |
array The balls of any bowl-out used to decide the outcome of the match. If provided this will be an array. More details on the bowl_out field. |
city |
string The city in which the game took place, such as Chennai. |
dates |
array (required) An array of dates on which the match took place. Matches on a single day will still be an array. More details on the dates field. |
event |
object If provided, this will provide information on the event the match is part of. More details on the event field. |
gender |
string (required) The gender of the players who took part on the match. At the moment this value will be either female or male, however these should not be regarded as the only possible options. |
match_type |
string (required) The type of match this data file refers to. Currently the possible values are Test, ODI, T20, IT20 (International T20), ODM (One-day match) or MDM (multi-day match). |
match_type_number |
integer If provided, the number of this particular match type, for example the 2404th Test match. |
missing |
array Details on any data regarded as missing from the match. If provided this will be an array of strings, or objects containing more detailed information. More details on the missing field. |
officials |
object If this field appears then it contain details on the officials involved in the match, both their roles and names. Only roles we know about are provided, if any. More details on the officials field. |
outcome |
object (required) The outcome of the match. It contains information such as which team won the match, whether the game was a draw, tie, or no result, and any margin of victory. More details on the outcome field. |
overs |
integer The number of overs for this type of match, if appropriate. For T20s, this will be 20, and for ODIs/ODMs this will be 50. |
player_of_match |
array If this field appears then it will be an array of the names of any players who were adjudged to be the player of the match. |
players |
object (required) A list of players officially involved in the match for each team. More details on the players field. |
registry |
object (required) Mappings of names to ids, currently used for mapping the names of people involved in the match to unique identifiers for those people. More details on the registry field. |
season |
string (required) The season during which the match took place, such as 2018, or 2011/12. |
supersubs |
object (required) Any supersubs used by each team in the match. More details on the supersubs field. |
team_type |
string (required) The type of team playing in the match, either international or club. |
teams |
array (required) The names of the teams who played in the match. |
toss |
object (required) The winner, and decision, from the toss. More details on the toss field. |
venue |
string The venue in which the game took place, such as Old Trafford. |
bowl_out
A bowl-out with 3 hits and 3 misses.
"bowl_out": [
{
"bowler": "V Sehwag",
"outcome": "hit"
},
{
"bowler": "Yasir Arafat",
"outcome": "miss"
},
{
"bowler": "Harbhajan Singh",
"outcome": "hit"
},
{
"bowler": "Umar Gul",
"outcome": "miss"
},
{
"bowler": "RV Uthappa",
"outcome": "hit"
},
{
"bowler": "Shahid Afridi",
"outcome": "miss"
}
]
An array containing an entry for each delivery attempted in the bowl-out.
Field | Description |
---|---|
bowler | string (required) The name of the bowler who bowled the ball. |
outcome | string (required) The outcome of the bowl-out ball, either hit, or miss. |
dates
A match played on a single day, such as an ODI.
"dates": [
"2016-07-26"
]
A match played on multiple days, such as a Test match.
"dates": [
"2018-03-01",
"2018-03-02",
"2018-03-03",
"2018-03-04",
"2018-03-05"
]
dates
is always an array, regardless of the number of days on which the match took place. Each date will be in the format YYYY-MM-DD
.
event
The 3rd match of a series between the West Indies and South Africa.
"event": {
"match_number": 3,
"name": "West Indies Women in South Africa T20I Series"
}
The 24th match in the Caribbean Premier League.
"event": {
"name": "Caribbean Premier League",
"match_number": 24
}
A T20 Blast match within a group.
"event": {
"group": "North",
"name": "NatWest T20 Blast"
}
A match in group C, the 8th of the ICC World Twenty20.
"event": {
"group": "C",
"match_number": 8,
"name": "ICC World Twenty20"
}
Match 18 of the World T20 played in Group 1 of the Super 10 stage.
"event": {
"group": 1,
"match_number": 18,
"name": "World T20",
"stage": "Super 10"
}
The event
is an object which contains information such as the name of the event, the match number within it, and any group or stage the match took place at.
Field | Description |
---|---|
name | string (required) The name of the event the match took place in. |
match_number | integer The match number of the match. This might indicate that it was the 3rd match of a series, or the 19th match of a competition. |
group | string The group the match was part of, if any, for example 1, C, or North. |
stage | string The stage of the event at which the match took place, for example Final. |
missing
A player of the match is expected, but we don't know who it was.
"missing": [
"player_of_match"
]
The umpires for the match are unknown.
"missing": [
"umpires"
]
Reviews are possible, however we haven't been able to determine their existence and/or details.
"missing": [
"reviews"
]
Both fielding and batting powerplay details are missing from both innings.
"missing": [
{
"powerplays": {
"1": [
"fielding",
"batting"
],
"2": [
"fielding",
"batting"
]
}
}
]
Details on the batting powerplay are missing from the 1st innings.
"missing": [
{
"powerplays": {
"1": [
"batting"
]
}
}
]
An example with multiple missing fields.
"missing": [
"player_of_match",
{
"powerplays": {
"1": [
"batting"
],
"2": [
"batting"
]
}
},
"reviews"
]
The missing
field contains an array that provides details on information that is known to be missing from the match data. As shown in the examples it can contain either string or object entries, as many as are needed. If a string is provided it will currently be one of player_of_match, umpires, or reviews; if an object is provided it will contain a single powerplays key with an object detailing innings and any powerplays that are missing in those innings. If powerplays are included each will be one of mandatory, batting, or fielding.
officials
The officials for a match between Sri Lanka and Australia in 2017.
"officials": {
"match_referees": [
"JJ Crowe"
],
"reserve_umpires": [
"MW Graham-Smith"
],
"tv_umpires": [
"P Wilson"
],
"umpires": [
"SD Fry",
"SJ Nogajski"
]
}
The data for this field is an object where the keys for the entries are the roles we have details for, while the value will be a list of the names of the relevant officials. The currently supported roles are: match_referees, reserve_umpires, tv_umpires, and umpires.
Field | Description |
---|---|
match_referees | array If this field appears then it will be an array of the names of any match referees who officiated in the match. |
reserve_umpires | array If this field appears then it will be an array of the names of any reserve umpires who officiated in the match. |
tv_umpires | array If this field appears then it will be an array of the names of any tv umpires who officiated in the match. |
umpires | array If this field appears then it will be an array of the names of any umpires who officiated in the match. |
outcome
A match where Trinbago Knight Riders won by a number of wickets.
"outcome": {
"winner": "Trinbago Knight Riders",
"by": {
"wickets": 3
}
}
A match where Australia won by a number of runs.
"outcome": {
"winner": "Australia",
"by": {
"runs": 118
}
}
A match where England won by an innings and a number of runs.
"outcome": {
"winner": "England",
"by": {
"innings": 1,
"runs": 209
}
}
A match that ended in a tie, with Kings XI Punjab winning the super over.
"outcome": {
"result": "tie",
"eliminator": "Kings XI Punjab"
}
A match that ended in with no result.
"outcome": {
"result": "no result"
}
A match won by Hong Kong, by a number of runs, under the Duckworth Lewis method.
"outcome": {
"winner": "Hong Kong",
"by": {
"runs": 30
},
"method": "D/L"
}
A match that ended in a tie, with New Zealand winning the bowl out.
outcome:
bowl_out: New Zealand
result: tie
The outcome
is an object which contains information such as which team won the match, whether the game was a draw, tie, or no result, and any margin of victory.
Field | Description |
---|---|
by |
object Information on how much the winning team, if there was one, won by. More details on the by field. |
bowl_out |
string The team name of the winner of any bowl-out used to decide a tie in a T20 match. |
eliminator |
string The team name of the winner of any elimination super-over used to decide a tie in a T20 match. |
method |
string Any method used to determine the winner where a match has been curtailed for some reason, or decided in an "unusual" manner. Currently the only values this will contain are D/L (when a match uses the Duckworth Lewis, and possibly Stern, method), VJD (when a match uses the Jayadevan system), Awarded (when a match is awarded to a team), 1st innings score (when the team with the highest 1st inning score is determined to have won the match), or Lost fewer wickets (when losing fewer wickets than the opponent determined the winner). |
result |
string The result of the match if the match was not won by one of the teams. Currently the possible values are draw, no result, or tie. |
winner |
string If a team won the match then this will be the name of the winning team. |
by
Information on how much the winning team, if there was one, won by.
Field | Description |
---|---|
innings |
integer If the match was won by an innings and something then this entry will appear with a value of 1. |
runs |
integer If the match was won by a number of runs, or an innings and a number of runs, then this will contain the runs. |
wickets |
integer If the match was won by a number of wickets, then this will contain the number of wickets. |
players
The players involved in a match between Australia and New Zealand.
"players": {
"Australia": [
"M Klinger",
"AJ Finch",
"BR Dunk",
"MC Henriques",
"TM Head",
"AJ Turner",
"JP Faulkner",
"TD Paine",
"PJ Cummins",
"AJ Tye",
"JA Richardson"
],
"Sri Lanka": [
"N Dickwella",
"WU Tharanga",
"EMDY Munaweera",
"BKG Mendis",
"DAS Gunaratne",
"TAM Siriwardana",
"CK Kapugedera",
"S Prasanna",
"KMDN Kulasekara",
"SL Malinga",
"JRMVB Sanjaya"
]
}
The players
section lists, for each team, the players officially involved in the match, including the starting eleven, and any supersubs, concussion substitutes, covid replacements, or other replacements. The section itself is an object containing the names of the teams as the key, and each value being an array of the names of the players for that team.
registry
The players and officials involved in a match.
"registry": {
"people": {
"AJ Finch": "b8d490fd",
"AJ Turner": "ff1e12a0",
"AJ Tye": "7c7d63a2",
"BKG Mendis": "5d1e7582",
"BR Dunk": "272d796e",
"CK Kapugedera": "cfad138c",
"DAS Gunaratne": "770494eb",
"EMDY Munaweera": "5a22d91c",
"JA Richardson": "1ee08e9a",
"JJ Crowe": "2e760301",
"JP Faulkner": "808f425a",
"JRMVB Sanjaya": "530b20e3",
"KMDN Kulasekara": "469ea22b",
"M Klinger": "b970a03f",
"MC Henriques": "32198ae0",
"MW Graham-Smith": "18aca3ce",
"N Dickwella": "45963d9e",
"P Wilson": "68304a36",
"PJ Cummins": "ded9240e",
"S Prasanna": "f78e7113",
"SD Fry": "6b725ed1",
"SJ Nogajski": "9b3f9323",
"SL Malinga": "a12e1d51",
"TAM Siriwardana": "bf7842c9",
"TD Paine": "5748e866",
"TM Head": "12b610c2",
"WU Tharanga": "7ed9fd56"
}
}
The registry
entry contains a single entry (people
) which provides a mapping between the names used for people mentioned in the data file and the stable unique identifier used for those people (regardless of the name the person appeared in the match under). The same person will always have the same identifier across all matches. The identifier is always an 8 character string consisting of digits or the lowercase letters a
to f
.
A name in this section will always be used to refer to the person in the data file, whether as a batter, non-striker, bowler, fielder, official, or in some other capacity.
supersubs
A match where only a single team (Melbourne Stars) used a supersub.
"supersubs": {
"Melbourne Stars": "LR Morris"
}
A match where both teams used a supersub.
"supersubs": {
"Adelaide Strikers": "MW Short",
"Hobart Hurricanes": "M Wright"
}
The data for this field is an object which details any supersubs used by each team in the match. The keys for the entry will be the names of any teams that used a super-sub, while the values will be the names of the super-subs for those teams.
toss
Canterbury won the toss and decided to bat.
"toss": {
"decision": "bat",
"winner": "Canterbury"
}
Adelaide Strikers won the toss and decided to field.
"toss": {
"decision": "field",
"winner": "Adelaide Strikers"
}
Somerset decided to field as the away team in a County Championship match, and thus the toss was uncontested.
"toss": {
"decision": "field",
"uncontested": true,
"winner": "Somerset"
}
The result of the toss before the match.
Field | Description |
---|---|
uncontested |
boolean If this is provided the value will be true. This indicates that the toss was not contested, and that instead it was automatically awarded to the winning team with the specified decision. Generally this is for County Championship matches from 2016 to 2019. |
decision |
string (required) The decision made by the team winning the toss. This will be either bat or field. |
winner |
string (required) The name of the team which won the toss. |
The innings
section
The simple example here shows a small part of both innings of a one-day match. The first innings shows Ireland facing 2 balls, with William Porterfield batting, while the second innings shows 1 ball of the Indian reply.
{
"innings": [
{
"team": "Ireland",
"overs": [
{
"over": 0,
"deliveries": [
{
"batter": "WTS Porterfield",
"bowler": "IK Pathan",
"extras": {
"wides": 1
},
"non_striker": "JP Bray",
"runs": {
"batter": 0,
"extras": 1,
"total": 1
}
},
{
"batter": "WTS Porterfield",
"bowler": "IK Pathan",
"non_striker": "JP Bray",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
}
}
]
}
]
},
{
"team": "India",
"overs": [
{
"over": 0,
"deliveries": [
{
"batter": "G Gambhir",
"bowler": "WB Rankin",
"non_striker": "RG Sharma",
"runs": {
"batter": 4,
"extras": 0,
"total": 4
}
}
]
}
]
}
]
}
The innings
section contains an array of objects, with each entry representing an innings within the game, in the order in which they took place. Each object contains the details of a single innings, such as the team batting, and the deliveries faced within the innings.
Field | Description |
---|---|
team |
string (required) The team which is batting must be specified in the data for the innings. This will be one of the two teams mentioned in the teams section in info for the match. |
overs |
array An array containing an entry for each over in the innings. Each entry is an object containing details of that particular over. There is a separate section covering the details on the over data. This will be provided for all non-forfeited innings. |
absent_hurt |
array If this is provided it will contain an array of the names of players who did not take part in the innings due to being absent hurt. |
penalty_runs |
object If this field is provided it will be a object which details any penalty runs added either before or after the innings. More details on the penalty_runs field. |
declared |
boolean If this is provided the value will be true. This indicates that the innings was declared. |
forfeited |
boolean If this is provided the value will be true. This indicates that the innings was forfeited by the batting team. |
powerplays |
array If this is provided it will be an array of objects containing details on each powerplay in the innings. More details on the powerplays field. |
miscounted_overs |
object If this is provided it will be an object containing details on any miscounted overs in the innings. More details on the miscounted_overs field. |
target |
object If this is provided it will be an object showing the number of overs available, and the target the team batting in the innings is aiming for (for example, 143 runs off 20 overs). More details on the target field. |
super_over |
boolean If this is provided the value will be true. This indicates that the innings consisted of a super-over. |
penalty_runs
Penalty runs added before the start of the innings. In this case the batting team start with 5 runs.
"penalty_runs": {
"pre": 5
}
Penalty runs added after the end of the innings. In this case the batting team has 6 runs added to their total.
"penalty_runs": {
"post": 6
}
Details on any penalty runs applied to an innings either before it begins or after it finishes. Penalty runs applied on particular deliveries will be indicated on the deliveries themselves rather than here.
Field | Description |
---|---|
pre |
integer The number of penalty runs applied to the innings before it begins. |
post |
integer The number of penalty runs applied to the innings after it finishes. |
powerplays
The mandatory powerplay in an innings for a T20 match.
"powerplays": [
{
"from": 0.1,
"to": 5.6,
"type": "mandatory"
}
]
Multiple powerplays, such as when all overs are part of mandatory powerplays.
"powerplays": [
{
"from": 0.1,
"to": 9.6,
"type": "mandatory"
},
{
"from": 10.1,
"to": 39.6,
"type": "mandatory"
},
{
"from": 40.1,
"to": 45.4,
"type": "mandatory"
}
]
The 2 powerplays expected in some forms of ODIs, specifically 1 mandatory to start, and 1 at the batting teams discretion.
"powerplays": [
{
"from": 0.1,
"to": 9.6,
"type": "mandatory"
},
{
"from": 35.1,
"to": 39.6,
"type": "batting"
}
]
Each entry in the powerplays
section consists of a from
, to
, and type
field detailing the deliveries covered by the powerplay, along with it's type.
Field | Description |
---|---|
from |
number (required) The first delivery that forms part of the powerplay, for example 0.1. |
to |
number (required) The final delivery that forms part of the powerplay, for example 9.6. |
type |
string (required) The type of powerplay. This will always be one of batting, fielding, or mandatory. |
miscounted_overs
A single miscounted over with only 5 balls bowled, with AV Jayaprakash as the umpire.
"miscounted_overs": {
"36": {
"balls": 5,
"umpire": "AV Jayaprakash"
}
}
A single miscounted over where the umpire is unknown.
"miscounted_overs": {
"10": {
"balls": 7
}
}
Two miscounted overs in the same innings, by the same umpire, one with too few deliveries, and the other with too many,
"miscounted_overs": {
"35": {
"balls": 7,
"umpire": "Asad Rauf"
},
"39": {
"balls": 5,
"umpire": "Asad Rauf"
}
}
The miscounted_overs
section consists of an object, with each key being the number of an over, and the value the details of the miscount, such as the umpire, and the number of deliveries that actually occurred in the over.
Field | Description |
---|---|
balls |
number (required) The number of deliveries actually bowled in the over. |
umpire |
string If known, the name of the umpire who miscounted the over.. |
target
An innings of 20 overs where the batting team is trying to reach 151 runs to win.
"target": {
"overs": 20,
"runs": 151
}
An innings of 50 overs where the batting team is trying to reach 259 runs to win.
"target": {
"overs": 50,
"runs": 259
}
Details on any target for the batting team in the innings, showing the number of overs available and the number of runs required.
Field | Description |
---|---|
overs |
integer The number of overs available in which to chase the target. |
runs |
integer The number of runs to be chased. |
Over data
The opening over of an innings, featuring 6 simple deliveries.
{
"over": 0,
"deliveries": [
{
"batter": "AJ Strauss",
"bowler": "IK Pathan",
"non_striker": "MJ Prior",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
}
},
{
"batter": "AJ Strauss",
"bowler": "IK Pathan",
"non_striker": "MJ Prior",
"runs": {
"batter": 1,
"extras": 0,
"total": 1
}
},
{
"batter": "MJ Prior",
"bowler": "IK Pathan",
"non_striker": "AJ Strauss",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
}
},
{
"batter": "MJ Prior",
"bowler": "IK Pathan",
"non_striker": "AJ Strauss",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
}
},
{
"batter": "MJ Prior",
"bowler": "IK Pathan",
"non_striker": "AJ Strauss",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
}
},
{
"batter": "MJ Prior",
"bowler": "IK Pathan",
"non_striker": "AJ Strauss",
"runs": {
"batter": 1,
"extras": 0,
"total": 1
}
}
]
}
Field | Description |
---|---|
over |
number (required) The number of the over in the innings. |
deliveries |
array (required) An array containing each delivery in the over. Each entry is an object containing details of that particular delivery. There is a separate section covering the details on the delivery data. |
Delivery data
An example delivery in which Harbhajan Singh bowled to Matt Prior, with Andrew Strauss at the non-striker's end. Prior was out leg-before-wicket.
{
"batter": "MJ Prior",
"bowler": "Harbhajan Singh",
"non_striker": "AJ Strauss",
"runs": {
"batter": 0,
"extras": 0,
"total": 0
},
"wickets": [
{
"kind": "lbw",
"player_out": "MJ Prior"
}
]
}
An example delivery in which Gautam Gambhir bowled to Paul Collingwood, with Kevin Pietersen at the non-striker's end. Gambhir bowled a wide.
{
"batter": "PD Collingwood",
"bowler": "G Gambhir",
"extras": {
"wides": 1
},
"non_striker": "KP Pietersen",
"runs": {
"batter": 0,
"extras": 1,
"total": 1
}
}
Each individual delivery is an object containing the details of the batter, non-striker, and bowler for the delivery, along with any runs scored. If applicable there may also be information on any extra, player replacements, or wickets that occurred on the delivery.
Field | Description |
---|---|
batter |
string (required) The name of the batter who faced the delivery. |
bowler |
string (required) The name of the bowler of the delivery. |
extras |
object The types and number of extras conceded on the delivery, if any. More details on the extras field. |
non_striker |
string (required) The name of the non-striker during the delivery. |
replacements |
object Any player replacements that happened before this delivery took place, for example when a bowler is replaced during an over due to injury. More details on the replacements field. |
review |
object The details of any review that took place during the delivery, including which team took the review, and the outcome. More details on the review field. |
runs |
object (required) The runs scored on the delivery, whether by the batter or as extras. Also covers the possibility that a 4 or 6 was not an actual boundary should, for example if the batsmen ran a 4. More details on the runs field. |
wickets |
array The details of any wickets that took place during the delivery, including the method of dismissal, the name of the dismissed player, and any fielders involved in the dismissal. |
extras
Byes
"extras": {
"byes": 4
}
Leg-byes
"extras": {
"legbyes": 2
}
No-balls
"extras": {
"noballs": 2
}
Penalty runs
"extras": {
"penalty": 5
}
Wides
"extras": {
"wides": 1
}
If extras were conceded on a delivery then this field will indicate how the extras came about. The value of the field will be an object with byes, legbyes, noballs, penalty, and wides as the possible keys, and the associated value for each will be the number of runs from each.
Field | Description |
---|---|
byes |
integer The number of byes conceded on the delivery. |
legbyes |
integer The number of legbyes conceded on the delivery. |
noballs |
integer The number of no-balls conceded on the delivery. |
penalty |
integer The number of penalty runs conceded on the delivery. |
wides |
integer The number of wides conceded on the delivery. |
replacements
Yasir Shah takes over as the bowler due to an injury to the existing bowler.
"replacements": {
"role": [
{
"in": "Yasir Shah",
"reason": "injury",
"role": "bowler"
}
]
}
Sam Whiteman (of Perth Scorchers) leaves the match due to a concussion and is replaced permanently by Cameron Bancroft,
"replacements": {
"match": [
{
"in": "CT Bancroft",
"out": "SM Whiteman",
"reason": "concussion_substitute",
"team": "Perth Scorchers"
}
]
}
This field is an object providing the details of any replacements that happened before this delivery took place. It shows who was substituted in and out, why, and which team it was for, as well as what type of replacement it is, match or role. These different types are grouped together within the replacements section, and it’s possible that a delivery could have both types.
Field | Description |
---|---|
match |
array Match replacements detail players who replace others and take their place in the match. More details on the match field. |
role |
array Role replacements are occasions where a player replaces another as a bowler or batter (but does not take their place in the match). More details on the role field. |
match
James Marshall replaces Jeetan Patel for New Zealand as a supersub.
"replacements": {
"match": [
{
"in": "JAH Marshall",
"out": "JS Patel",
"reason": "supersub",
"team": "New Zealand"
}
]
}
Chris Tremain replaces Daniel Sams for Sydney Thunder as a concussion substitute.
"replacements": {
"match": [
{
"in": "CP Tremain",
"out": "DR Sams",
"team": "Sydney Thunder",
"reason": "concussion_substitute"
}
]
}
Jack Brooks replaces Lewis Gregory for Somerset as a covid replacement.
"replacements": {
"match": [
{
"in": "JA Brooks",
"out": "L Gregory",
"team": "Somerset",
"reason": "covid_replacement"
}
]
}
Graham Clarke replaces Ben Stokes due to Stokes receiving a callup to the national team.
"replacements": {
"match": [
{
"in": "G Clark",
"out": "BA Stokes",
"team": "Durham",
"reason": "national_callup"
}
]
}
Tim Murtagh replaces Ethan Bamber after Murtagh was released from his national commitments with Ireland.
"replacements": {
"match": [
{
"in": "TJ Murtagh",
"out": "ER Bamber",
"team": "Middlesex",
"reason": "national_release"
}
]
}
match
replacements involve one player completely replacing another in a match, such as a occurs when a concussion substitution takes places.
Field | Description |
---|---|
in |
string (required) The name of the player who came in as part of the replacement. If the replacement is a supersub replacement then this value will match the player listed as a supersub for the team. |
out |
string (required) The name of the player who went out as part of the replacement. |
reason |
string (required) The reason for the replacement. This must be one of concussion_substitute, covid_replacement, national_callup, national_release, supersub, or unknown. |
team |
string (required) The name of the team the substitution was for. |
role
Alex Thomson replaces George Scrimshaw as the bowler, after Scrimshaw is excluded for bowling excessive short-pitched deliveries.
"replacements": {
"role": [
{
"in": "AT Thomson",
"out": "GLS Scrimshaw",
"reason": "excluded - excessive short-pitched deliveries",
"role": "bowler"
}
]
}
Rob Taylor replaces Nathan Buck as the bowler, after Buck is excluded for bowling multiple high-pitched deliveries.
"replacements": {
"role": [
{
"in": "RML Taylor",
"out": "NL Buck",
"reason": "excluded - high full pitched balls",
"role": "bowler"
}
]
}
Steve Finn replaces the existing (un-named) bowler who is excluded for having run on the pitch.
"replacements": {
"role": [
{
"in": "ST Finn",
"reason": "excluded - running on the pitch",
"role": "bowler"
}
]
}
George Dockrell comes in as bowler, replacing the injured David Delany.
"replacements": {
"role": [
{
"in": "GH Dockrell",
"out": "DC Delany",
"reason": "injury",
"role": "bowler"
}
]
}
Ravindra Jadeja replaces the (un-named) bowler after it is determined that the existing bowler has bowled too many overs. This actually happened in an ODI between Australia and India in 2012.
"replacements": {
"role": [
{
"in": "RA Jadeja",
"reason": "too many overs",
"role": "bowler"
}
]
}
Charles Perchard replaces Anthony Hawkins-Kay as bowler for an unknown reason.
"replacements": {
"role": [
{
"in": "CW Perchard",
"out": "AW Hawkins-Kay",
"reason": "unknown",
"role": "bowler"
}
]
}
role
replacements involve one player replacing another in a role, such as a bowler being replaced due to being injured.
Field | Description |
---|---|
in |
string (required) The name of the player who came in as part of the replacement. |
out |
string The name of the player who went out as part of the replacement. This may not be provided for a bowler replacement. |
reason |
string (required) The reason for the replacement. This must be one of excluded - excessive short-pitched deliveries, excluded - high full pitched balls, excluded - running on the pitch, injury, too many overs, or unknown. |
role |
string (required) The role of the player being replaced, currently either batter, or bowler. |
review
A review where the request was struck down.
"review": {
"by": "Pakistan",
"umpire": "AG Wharf",
"batter": "DJ Malan",
"decision": "struck down"
}
A review where the request was upheld.
"review": {
"by": "England",
"umpire": "AG Wharf",
"batter": "Imam-ul-Haq",
"decision": "upheld"
}
A review where the request was struck down, due to one of the constituent parts being an umpires call.
"review": {
"by": "Pakistan",
"umpire": "AG Wharf",
"batter": "Saud Shakeel",
"decision": "struck down",
"umpires_call": 1
}
A review where the umpire is unknown.
"review": {
"by": "Australia",
"batter": "MS Dhoni",
"decision": "struck down"
}
Details on any review that took place as part of the delivery.
Field | Description |
---|---|
batter |
string (required) The name of the batter for whom the decision was reviewed. |
by |
string (required) The name of the team that called for the review. |
decision |
string (required) The decision made following the review. This will be one of struck down, or upheld. |
umpire |
string The name of the umpire who's decision was reviewed. |
umpires_call |
boolean If a review was struck down due to it being down to the umpires call this field will be true. |
runs
A delivery where the batter scored 4 runs, and no extras were scored. As
non_boundary
is not specified this was a boundary.
"runs": {
"batter": 4,
"extras": 0,
"total": 4
}
A delivery where the batter didn't score, but some extras occurred.
"runs": {
"batter": 0,
"extras": 1,
"total": 1
}
A delivery where the batter scored 1 runs, and 2 extras occurred.
"runs": {
"batter": 1,
"extras": 2,
"total": 3
}
A delivery where the batter scored 4 runs, but it wasn't a boundary.
"runs": {
"batter": 4,
"extras": 0,
"total": 4,
"non_boundary": true
}
Details on how the runs scored on the delivery should be assigned. Runs scored by the batter, and the total extras conceded, are shown individually along with the total of both. It may also contain a non_boundary
entry to indicate that any 4 or 6 should not be regarded as a boundary.
Field | Description |
---|---|
batsman |
integer (required) The total number of runs scored by the batter off the ball. If the batter failed to score this will show 0. |
extras |
integer (required) The total number of runs conceded via extras off the ball. If no extras were conceded this will show 0. |
non_boundary |
boolean If this is listed against the delivery then the value will be true. This indicates that the 4 or 6 scored was not via an actual boundary, for example it was all run, or overthrows. |
total |
integer (required) The total number of runs scored off this delivery. If no runs were scored from the delivery then this will display 0. |
wickets
Stephen Fleming is out
bowled
.
"wickets": [
{
"kind": "bowled",
"player_out": "SP Fleming"
}
]
MS Dhoni is out
caught
.
"wickets": [
{
"kind": "caught",
"player_out": "MS Dhoni",
"fielders": [
{
"name": "Shoaib Malik"
}
]
}
]
Kevin Pietersen is out
caught and bowled
.
"wickets": [
{
"kind": "caught and bowled",
"player_out": "KP Pietersen"
}
]
Austin Richards is out leg before wicket (
lbw
).
"wickets": [
{
"kind": "lbw",
"player_out": "ACL Richards"
}
]
Paul Collingwood is out
stumped
, by Denesh Ramdin.
"wickets": [
{
"kind": "stumped",
"player_out": "PD Collingwood",
"fielders": [
{
"name": "D Ramdin"
}
]
}
]
Dwayne Smith is
run out
, by Kevin Pietersen and Matt Prior.
"wickets": [
{
"kind": "run out",
"player_out": "DR Smith",
"fielders": [
{
"name": "KP Pietersen"
},
{
"name": "MJ Prior"
}
]
}
]
Sachin Tendulkar is out
retired hurt
.
"wickets": [
{
"kind": "retired hurt",
"player_out": "SR Tendulkar"
}
]
Saurabh Tiwary is out
hit wicket
.
"wickets": [
{
"kind": "hit wicket",
"player_out": "SS Tiwary"
}
]
Diego Lord is out
obstructing the field
.
"wickets": [
{
"kind": "obstructing the field",
"player_out": "DM Lord"
}
]
Zhang Yu Fei is out
handled the ball
.
"wickets": [
{
"player_out": "Zhang Yu Fei",
"kind": "handled the ball"
}
]
Two wickets listed on the same delivery, one played
stumped
, and the other playedretired hurt
.
"wickets": [
{
"kind": "stumped",
"player_out": "Sarfraz Ahmed",
"fielders": [
{
"name": "BJ Haddin"
}
]
},
{
"kind": "retired hurt",
"player_out": "Zulfiqar Babar"
}
]
If a wicket occurs on the delivery then this entry will be an array containing a single entry for each wicket, with details such as which player is out, what type of dismissal it was, and any fielders who were involved. Generally this array will contain a single entry, but in the very unlikely case that a wicket falls and another player retires hurt on the same ball, the array will contain an entry for each wicket. At the moment we only have a single match that meets this criteria, the 1st Test between Pakistan and Australia in 2014 where Sarfaraz Ahmed was stumped, the tea interval was taken, and Zulfiqar Babar retired hurt during it (effectively meaning he had retired on the same delivery).
Field | Description |
---|---|
fielders |
array If we know them this will contain the names of any fielders who were involved in the dismissal. Generally this will be the player (or players) who took a catch, or were involved in a run-out. |
kind |
string (required) The kind of dismissal that took place. This will be one of bowled, caught, caught and bowled, lbw, stumped, run out, retired hurt, hit wicket, obstructing the field, hit the ball twice, handled the ball, or timed out. |
player_out |
string (required) The name of the player who was dismissed. |
Changelog
Version 1.1.0
- Added
uncontested
as a possible field withintoss
ininfo
. - Added
forfeited
as a possible field within eachinnings
.
Version 1.0.0
- Initial JSON version.