NAV

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. Currently the only value this will contain is D/L when a match uses the Duckworth Lewis (and possibly Stern) method.
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

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 - 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 played retired 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

Version 1.0.0