NAV

Introduction to the XML format

This document details the XML 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 XML format is 0.92.

The meta section

<meta>
  <data_version>0.92</data_version>
  <created>2021-03-28</created>
  <revision>1</revision>
</meta>

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 0.91.
created date (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

An example of an info section, from an ODI between New Zealand and Bangladesh.

<info>
  <balls_per_over>6</balls_per_over>
  <city>Wellington</city>
  <dates>
    <date>2021-03-26</date>
  </dates>
  <gender>male</gender>
  <match_type>ODI</match_type>
  <match_type_number>4282</match_type_number>
  <outcome>
    <by>
      <runs>164</runs>
    </by>
    <winner>New Zealand</winner>
  </outcome>
  <overs>50</overs>
  <player_of_match>
    <player_of_match>DP Conway</player_of_match>
  </player_of_match>
  <teams>
    <team>New Zealand</team>
    <team>Bangladesh</team>
  </teams>
  <toss>
    <decision>bat</decision>
    <winner>New Zealand</winner>
  </toss>
  <umpires>
    <umpire>CB Gaffaney</umpire>
    <umpire>WR Knights</umpire>
  </umpires>
  <venue>Basin Reserve</venue>
</info>

The info section contains the information on the actual match, such as when and where it was played, any competition 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 of bowl_out entries. More details on the bowl_out field.
city string The city in which the game took place, such as Wellington.
competition string The competition the match was part of. At the moment this value, if provided, will always be Caribbean Premier League, IPL, NatWest T20 Blast, New Zealand Cricket Women's Twenty20, Pakistan Super League, Super Smash, The Hundred Men's Competition, The Hundred Women's Competition, Vitality Blast, Women's Big Bash League, or Women's T20 Challenge, however these should not be regarded as the only possible options.
dates array (required) An array of date entries for when the match took place. Matches on a single day will still be an array. More details on the dates 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.
lineups associative array (required) A list of players officially involved in the match for each team. More details on the lineups field.
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).
neutral_venue integer If provided this indicates that the game was played at a venue neither team would regard as a home ground. The value will be 1.
outcome associative array (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.
registry associative array (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.
supersubs associative array (required) Any supersubs used by each team in the match. More details on the supersubs field
teams array (required) The names of the teams who played in the match.
toss associative array (required) The winner, and decision, from the toss. More details on the toss field
umpires array If this field appears then it will be an array of the names of any umpires, and there will be at least 2 entries.
venue string The venue in which the game took place, such as Old Trafford.

bowl_out

A bowl-out featuring 4 misses and 3 hits.

<bowl_out>
  <bowl_out>
    <bowler>JE Taylor</bowler>
    <outcome>miss</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>JE Taylor</bowler>
    <outcome>miss</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>SE Bond</bowler>
    <outcome>hit</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>SE Bond</bowler>
    <outcome>hit</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>IDR Bradshaw</bowler>
    <outcome>miss</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>IDR Bradshaw</bowler>
    <outcome>miss</outcome>
  </bowl_out>
  <bowl_out>
    <bowler>SB Styris</bowler>
    <outcome>hit</outcome>
  </bowl_out>
</bowl_out>

The bowl_out section contains an array of individual bowl_out entries 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>
  <date>2021-03-26</date>
</dates>

A match played on multiple days, such as a Test match.

<dates>
  <date>2011-01-02</date>
  <date>2011-01-03</date>
  <date>2011-01-04</date>
  <date>2011-01-05</date>
  <date>2011-01-06</date>
</dates>

dates is always an array, regardless of the number of days on which the match took place. Each entry will be a <date> tag containing the actual date in the format YYYY-MM-DD.

lineups

The players involved in a match between Australia and Sri Lanka.

<lineups>
  <lineup>
    <team>Australia</team>
    <players>
      <player>M Klinger</player>
      <player>AJ Finch</player>
      <player>BR Dunk</player>
      <player>MC Henriques</player>
      <player>TM Head</player>
      <player>AJ Turner</player>
      <player>JP Faulkner</player>
      <player>TD Paine</player>
      <player>PJ Cummins</player>
      <player>AJ Tye</player>
      <player>JA Richardson</player>
    </players>
  </lineup>
  <lineup>
    <team>Sri Lanka</team>
    <players>
      <player>N Dickwella</player>
      <player>WU Tharanga</player>
      <player>EMDY Munaweera</player>
      <player>BKG Mendis</player>
      <player>DAS Gunaratne</player>
      <player>TAM Siriwardana</player>
      <player>CK Kapugedera</player>
      <player>S Prasanna</player>
      <player>KMDN Kulasekara</player>
      <player>SL Malinga</player>
      <player>JRMVB Sanjaya</player>
    </players>
  </lineup>
</lineups>

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 associative array containing the names of the teams as the key, and each value being an array of the names of the players for that team.

Field Description
team string (required) The name of the team the players played for.
players array (required) An array of player entries each of which contains the name of a player.

outcome

A match where India won by a number of wickets.

<outcome>
  <by>
    <wickets>9</wickets>
  </by>
  <winner>Chennai Super Kings</winner>
</outcome>

A match where New Zealand won by a number of runs.

<outcome>
  <by>
    <runs>164</runs>
  </by>
  <winner>New Zealand</winner>
</outcome>

A match where Australia won by an innings and a number of runs.

<outcome>
  <by>
    <innings>1</innings>
    <runs>48</runs>
  </by>
  <winner>Australia</winner>
</outcome>

A match that ended in a tie, with England winning the super over.

<outcome>
  <eliminator>England</eliminator>
  <result>tie</result>
</outcome>

A match that ended in with no result.

<outcome>
  <result>no result</result>
</outcome>

A match won by Hong Kong, by a number of runs, under the Duckworth Lewis method.

<outcome>
  <by>
    <runs>39</runs>
  </by>
  <method>D/L</method>
  <winner>Hong Kong</winner>
</outcome>

A match that ended in a tie, with New Zealand winning the bowl out.

<outcome>
  <bowl_out>New Zealand</bowl_out>
  <result>tie</result>
</outcome>

The outcome entry 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 associative array 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.

registry

The players and officials involved in a match.

<registry>
  <people>
    <person>
      <name>AJ Finch</name>
      <identifier>b8d490fd</identifier>
    </person>
    <person>
      <name>AJ Turner</name>
      <identifier>ff1e12a0</identifier>
    </person>
    <person>
      <name>AJ Tye</name>
      <identifier>7c7d63a2</identifier>
    </person>
    <person>
      <name>BKG Mendis</name>
      <identifier>5d1e7582</identifier>
    </person>
    <person>
      <name>BR Dunk</name>
      <identifier>272d796e</identifier>
    </person>
    <person>
      <name>CK Kapugedera</name>
      <identifier>cfad138c</identifier>
    </person>
    <person>
      <name>DAS Gunaratne</name>
      <identifier>770494eb</identifier>
    </person>
    <person>
      <name>EMDY Munaweera</name>
      <identifier>5a22d91c</identifier>
    </person>
    <person>
      <name>JA Richardson</name>
      <identifier>1ee08e9a</identifier>
    </person>
    <person>
      <name>JJ Crowe</name>
      <identifier>2e760301</identifier>
    </person>
    <person>
      <name>JP Faulkner</name>
      <identifier>808f425a</identifier>
    </person>
    <person>
      <name>JRMVB Sanjaya</name>
      <identifier>530b20e3</identifier>
    </person>
    <person>
      <name>KMDN Kulasekara</name>
      <identifier>469ea22b</identifier>
    </person>
    <person>
      <name>M Klinger</name>
      <identifier>b970a03f</identifier>
    </person>
    <person>
      <name>MC Henriques</name>
      <identifier>32198ae0</identifier>
    </person>
    <person>
      <name>MW Graham-Smith</name>
      <identifier>18aca3ce</identifier>
    </person>
    <person>
      <name>N Dickwella</name>
      <identifier>45963d9e</identifier>
    </person>
    <person>
      <name>P Wilson</name>
      <identifier>68304a36</identifier>
    </person>
    <person>
      <name>PJ Cummins</name>
      <identifier>ded9240e</identifier>
    </person>
    <person>
      <name>S Prasanna</name>
      <identifier>f78e7113</identifier>
    </person>
    <person>
      <name>SD Fry</name>
      <identifier>6b725ed1</identifier>
    </person>
    <person>
      <name>SJ Nogajski</name>
      <identifier>9b3f9323</identifier>
    </person>
    <person>
      <name>SL Malinga</name>
      <identifier>a12e1d51</identifier>
    </person>
    <person>
      <name>TAM Siriwardana</name>
      <identifier>bf7842c9</identifier>
    </person>
    <person>
      <name>TD Paine</name>
      <identifier>5748e866</identifier>
    </person>
    <person>
      <name>TM Head</name>
      <identifier>12b610c2</identifier>
    </person>
    <person>
      <name>WU Tharanga</name>
      <identifier>7ed9fd56</identifier>
    </person>
  </people>
</registry>

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.

Field Description
name integer (required) The name used throughout the data file for the person.
identifier integer (required) The identifier for the person from the Cricsheet Register.

supersubs

A match where only a single team (Australia) used a supersub.

<supersubs>
  <supersub>
    <team>Australia</team>
    <player>JR Hopes</player>
  </supersub>
</supersubs>

A match where both teams used a supersub.

<supersubs>
  <supersub>
    <team>Adelaide Strikers</team>
    <player>MW Short</player>
  </supersub>
  <supersub>
    <team>Hobart Hurricanes</team>
    <player>M Wright</player>
  </supersub>
</supersubs>

The supersubs section contains an array of individual supersub entries , one for each supersub used by each team in the match. Each contains the following fields:

Field Description
team integer If the match was won by an innings and something then this entry will appear with a value of 1.
player 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.

toss

Namibia won the toss and decided to bat.

<toss>
  <decision>bat</decision>
  <winner>Namibia</winner>
</toss>

Netherlands won the toss and decided to field.

<toss>
  <decision>field</decision>
  <winner>Netherlands</winner>
</toss>

Somerset decided to field as the away team in a County Championship match, and thus the toss was uncontested.

<toss>
  <decision>field</decision>
  <uncontested>true</uncontested>
  <winner>Somerset</winner>
</toss>

The result of the toss before the match.

Field Description
decision string (required) The decision made by the team winning the toss. This will be either bat or field.
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.
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>
  <inning>
    <inningsNumber>1</inningsNumber>
    <team>Ireland</team>
    <deliveries>
      <delivery>
        <over>0</over>
        <ball>1</ball>
        <batsman>WTS Porterfield</batsman>
        <bowler>IK Pathan</bowler>
        <extras>
          <wides>1</wides>
        </extras>
        <non_striker>JP Bray</non_striker>
        <runs>
          <batsman>0</batsman>
          <extras>1</extras>
          <total>1</total>
        </runs>
      </delivery>
      <delivery>
        <over>0</over>
        <ball>2</ball>
        <batsman>WTS Porterfield</batsman>
        <bowler>IK Pathan</bowler>
        <non_striker>JP Bray</non_striker>
        <runs>
          <batsman>0</batsman>
          <extras>0</extras>
          <total>0</total>
        </runs>
      </delivery>
    </deliveries>
  </inning>
  <inning>
    <inningsNumber>2</inningsNumber>
    <team>India</team>
    <deliveries>
      <delivery>
        <over>0</over>
        <ball>1</ball>
        <batsman>G Gambhir</batsman>
        <bowler>WB Rankin</bowler>
        <non_striker>RG Sharma</non_striker>
        <runs>
          <batsman>4</batsman>
          <extras>0</extras>
          <total>4</total>
        </runs>
      </delivery>
    </deliveries>
  </inning>
</innings>

The innings section contains one or more inning entries with each entry representing an innings within the game, in the order in which they took place. Each inning entry contains the details of that innings, such as innings number, the team batting, and the deliveries faced within the innings.

Field Description
inningsNumber integer (required) The number of the innings within the match, starting at 1.
team string (required) The name of the team batting during the innings. This will be one of the two teams mentioned in the teams section in info for the match.
penalty_runs associative array If this field is provided it will detail 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.
deliveries array An array containing a delivery entry for each delivery in the innings. There is a separate section covering the details on the delivery data. This will always be provided, unless the inning is forfeited.

penalty_runs

Penalty runs added before the start of the innings. In this case the batting team start with 5 runs.

<penalty_runs>
  <post>5</post>
</penalty_runs>

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</post>
</penalty_runs>

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.

Delivery data

An example delivery (the 2nd in the 8th over of the innings) in which Nadine de Klerk bowled to Nahida Khan, with Umaima Sohail at the non-striker's end. Khan scored a single run but was then run-out going for the 2nd run. The fielders involved in the run-out are not known.

<delivery>
  <over>7</over>
  <ball>2</ball>
  <batsman>Nahida Khan</batsman>
  <bowler>N de Klerk</bowler>
  <non_striker>Umaima Sohail</non_striker>
  <runs>
    <batsman>1</batsman>
    <extras>0</extras>
    <total>1</total>
  </runs>
  <wickets>
    <wicket>
      <kind>run out</kind>
      <player_out>Nahida Khan</player_out>
    </wicket>
  </wickets>
</delivery>

An example delivery (the 1st in the 3rd over of the innings) in which Ross ter Braak bowled to Tim Seifert, with Katene Clarke at the non-striker's end. Ter Braak bowled a wide.

<delivery>
  <over>2</over>
  <ball>1</ball>
  <batsman>TL Seifert</batsman>
  <bowler>RM ter Braak</bowler>
  <extras>
    <wides>1</wides>
  </extras>
  <non_striker>KD Clarke</non_striker>
  <runs>
    <batsman>0</batsman>
    <extras>1</extras>
    <total>1</total>
  </runs>
</delivery>
Field Description
over integer (required) The number of the over, starting with the first over as 0.
ball integer (required) The number of the ball in the over, starting with the first ball as 1.
batsman string (required) The name of the batter who faced the delivery.
bowler string (required) The name of the bowler of the delivery.
extras associative array The types and number of extras conceded on the delivery. More details on the extras field.
non_striker string (required) The name of the non-striker during the delivery.
replacements associative array 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.
runs associative array (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 associative array, or 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. More details on the wicket field.

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>
  <batsman>4</batsman>
  <extras>0</extras>
  <total>4</total>
</runs>

A delivery where the batter didn't score, but some extras occurred.

<runs>
  <batsman>0</batsman>
  <extras>1</extras>
  <total>1</total>
</runs>

A delivery where the batter scored 2 runs, and an extra occurred.

<runs>
  <batsman>2</batsman>
  <extras>1</extras>
  <total>3</total>
</runs>

A delivery where the batter scored 4 runs, but it wasn't a boundary.

<runs>
  <batsman>4</batsman>
  <extras>0</extras>
  <non_boundary>1</non_boundary>
  <total>4</total>
</runs>

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 integer If this is listed against the delivery then the value will be 1. 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.

wicket

Ahmed Shehzad is out bowled.

<wickets>
  <wicket>
    <kind>bowled</kind>
    <player_out>Ahmed Shehzad</player_out>
  </wicket>
</wickets>

Azhar Ali is out caught.

<wickets>
  <wicket>
    <fielders>
      <fielder>AJ Doolan</fielder>
    </fielders>
    <kind>caught</kind>
    <player_out>Azhar Ali</player_out>
  </wicket>
</wickets>

Stuart Broad is out caught and bowled.

<wickets>
  <wicket>
    <kind>caught and bowled</kind>
    <player_out>SCJ Broad</player_out>
  </wicket>
</wickets>

Mohammad Hafeez is out leg before wicket (lbw).

<wickets>
  <wicket>
    <kind>lbw</kind>
    <player_out>Mohammad Hafeez</player_out>
  </wicket>
</wickets>

David Warner is out stumped, by Sarfraz Ahmed.

<wickets>
  <wicket>
    <fielders>
      <fielder>Sarfraz Ahmed</fielder>
    </fielders>
    <kind>stumped</kind>
    <player_out>DA Warner</player_out>
  </wicket>
</wickets>

Alex Doolan is run out, by Rahat Ali.

<wickets>
  <wicket>
    <fielders>
      <fielder>Rahat Ali</fielder>
    </fielders>
    <kind>run out</kind>
    <player_out>AJ Doolan</player_out>
  </wicket>
</wickets>

Salman Butt is out retired hurt.

<wickets>
  <wicket>
    <kind>retired hurt</kind>
    <player_out>Salman Butt</player_out>
  </wicket>
</wickets>

Swapnil Asnodkar is out hit wicket.

<wickets>
  <wicket>
    <kind>hit wicket</kind>
    <player_out>SA Asnodkar</player_out>
  </wicket>
</wickets>

Diego Lord is out obstructing the field.

<wickets>
  <wicket>
    <kind>obstructing the field</kind>
    <player_out>DM Lord</player_out>
  </wicket>
</wickets>

Zhang Yu Fei is out handled the ball.

<wickets>
  <wicket>
    <kind>handled the ball</kind>
    <player_out>Zhang Yu Fei</player_out>
  </wicket>
</wickets>

Two wickets listed on the same delivery, one played stumped, and the other played retired hurt.

<wickets>
  <wicket>
    <fielders>
      <fielder>BJ Haddin</fielder>
    </fielders>
    <kind>stumped</kind>
    <player_out>Sarfraz Ahmed</player_out>
  </wicket>
  <wicket>
    <kind>retired hurt</kind>
    <player_out>Zulfiqar Babar</player_out>
  </wicket>
</wickets>

If a wicket occurs on the delivery then this entry will provide details on the wicket, such as which player is out, what type of dismissal it was, and any fielders who were involved.

In the very unlikely case that a wicket falls and another player retires hurt on the same ball, this will be an array containing 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 an array of fielder entries containing 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.

extras

Byes

<extras>
  <byes>1</byes>
</extras>

Leg-byes

<extras>
  <legbyes>2</legbyes>
</extras>

No-balls

<extras>
  <noballs>1</noballs>
</extras>

Penalty runs

<extras>
  <penalty>5</penalty>
</extras>

Wides

<extras>
  <wides>1</wides>
</extras>

If extras were conceded on a delivery then this entry will indicate how the extras came about. The value of the field will be an associative array 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

Kyle Abbott takes over as the bowler due to an injury to the existing bowler.

<replacements>
  <role>
    <role>
      <in>KJ Abbott</in>
      <reason>injury</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

Sam Whiteman (of Perth Scorchers) leaves the match due to a concussion and is replaced permanently by Cameron Bancroft,

<replacements>
  <match>
    <match>
      <in>CT Bancroft</in>
      <out>SM Whiteman</out>
      <reason>concussion_substitute</reason>
      <team>Perth Scorchers</team>
    </match>
  </match>
</replacements>

The replacements field provides the details of any replacements that happened before the 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. The match section contains individual match entries. 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). The role section contains individual role entries. More details on the role field.

match

James Marshall replaces Jeetan Patel for New Zealand as a supersub.

<replacements>
  <match>
    <match>
      <in>JAH Marshall</in>
      <out>JS Patel</out>
      <reason>supersub</reason>
      <team>New Zealand</team>
    </match>
  </match>
</replacements>

Chris Tremain replaces Daniel Sams for Sydney Thunder as a concussion substitute.

<replacements>
  <match>
    <match>
      <in>CP Tremain</in>
      <out>DR Sams</out>
      <reason>concussion_substitute</reason>
      <team>Sydney Thunder</team>
    </match>
  </match>
</replacements>

Jack Brooks replaces Lewis Gregory for Somerset as a covid replacement.

<replacements>
  <match>
    <match>
      <in>JA Brooks</in>
      <out>L Gregory</out>
      <reason>covid_replacement</reason>
      <team>Somerset</team>
    </match>
  </match>
</replacements>

Graham Clarke replaces Ben Stokes due to Stokes receiving a callup to the national team.

<replacements>
  <match>
    <match>
      <in>G Clark</in>
      <out>BA Stokes</out>
      <reason>national_callup</reason>
      <team>Durham</team>
    </match>
  </match>
</replacements>

Tim Murtagh replaces Ethan Bamber after Murtagh was released from his national commitments with Ireland.

<replacements>
  <match>
    <match>
      <in>TJ Murtagh</in>
      <out>ER Bamber</out>
      <reason>national_release</reason>
      <team>Middlesex</team>
    </match>
  </match>
</replacements>

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>
    <role>
      <in>AT Thomson</in>
      <out>GLS Scrimshaw</out>
      <reason>excluded - excessive short-pitched deliveries</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

Rob Taylor replaces Nathan Buck as the bowler, after Buck is excluded for bowling multiple high-pitched deliveries.

<replacements>
  <role>
    <role>
      <in>RML Taylor</in>
      <out>NL Buck</out>
      <reason>excluded - high full pitched balls</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

Steve Finn replaces the existing (un-named) bowler who is excluded for having run on the pitch.

<replacements>
  <role>
    <role>
      <in>ST Finn</in>
      <reason>excluded - running on the pitch</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

<replacements>
  <role>
    <role>
      <in>ST Finn</in>
      <reason>excluded - running on the pitch</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

George Dockrell comes in as bowler, replacing the injured David Delany.

<replacements>
  <role>
    <role>
      <in>GH Dockrell</in>
      <out>DC Delany</out>
      <reason>injury</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

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>
    <role>
      <in>RA Jadeja</in>
      <reason>too many overs</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

Charles Perchard replaces Anthony Hawkins-Kay as bowler for an unknown reason.

<replacements>
  <role>
    <role>
      <in>CW Perchard</in>
      <out>AW Hawkins-Kay</out>
      <reason>unknown</reason>
      <role>bowler</role>
    </role>
  </role>
</replacements>

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.

Changelog

Version 0.92

Version 0.91