NAV

Introduction to the "Original" CSV format

This document details the "original" CSV data provided by Cricsheet. It was the first version of CSV data we provided, hence the "original" nickname. The page describes the organisation of the file and attempts to give some idea of the possible contents for each field. Each file has a version, multiple info rows, and multiple ball rows, with the info rows roughly corresponding to the same data in the YAML format, and the ball rows matching the deliveries. It is also possible that there may be some penalty_runs rows, where relevant.

The current version number for the "original" format is 1.4.0.

The version row

The version of the data format is always included.

version,1.4.0

The single version line contains the version of the data format. Currently this is 1.4.0, however will increase if a change is made to the format. The version number follows semantic versioning rules.

Field Description
version string (required) The version of the data format the file contains, in this case 1.4.0.

The info rows

A full real-life example for a match played in 2012.

info,team,Afghanistan
info,team,Canada
info,gender,male
info,season,2011/12
info,date,2012/03/18
info,competition,ICC World Twenty20 Qualifier
info,match_number,37
info,venue,ICC Global Cricket Academy
info,city,Dubai
info,neutralvenue,true
info,toss_winner,Afghanistan
info,toss_decision,bat
info,player_of_match,Samiullah Shenwari
info,umpire,S Asnani
info,umpire,JS Wilson
info,reserve_umpire,JD Cloete
info,match_referee,GF Labrooy
info,winner,Afghanistan
info,winner_runs,41

The dates for a multi-day match.

info,date,2016/09/30
info,date,2016/10/01
info,date,2016/10/02
info,date,2016/10/03

A match decided by the Duckworth-Lewis method. In this case Ireland won on wickets.

info,winner,Ireland
info,winner_wickets,9
info,method,D/L

A match where the result was a draw.

info,outcome,draw

A match where more than 1 player was adjudged player of the match. This example comes from a Test played between Pakistan and Australia at Lord's.

info,player_of_match,SM Katich
info,player_of_match,Salman Butt

A match where a team won by a number of wickets, in this case Kings XI Punjab won by 5 wickets.

info,winner,Kings XI Punjab
info,winner_wickets,5

A match where a team won by an innings and a number of runs, in this case New Zealand won by an innings and 101 runs.

info,winner,New Zealand
info,winner_innings,1
info,winner_runs,101

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. The fields included in the info section will each appear as one or more rows in the data. Some of the fields are required, whereas some are optional. If a field has multiple values, such as team, then each value will appear on a row of it's own. In the example Afghanistan, and Canada both appear on an info,team row of their own.

Field Description
bowl_out string The team name of the winner of any bowl-out used to decide a tie in a T20 match.
city string The city in which the game took place, such as Dubai.
competition string The competition the match was part of, if any.
date string (required) A date on which the match took place. Each day of the match will have a row of it's own. Dates will be in the format YYYY/MM/DD.
eliminator string The team name of the winner of any elimination super-over used to decide a tie in a T20 match.
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_number integer The match number of the series or competition the match was part of, if any.
match_referee string The name of the match referee, if any. If there was more than one then each will appear on it's own row.
method string Any method used to determine the winner where a match has been curtailed for some reason. Currently the only values this will contain are D/L (when a match uses the Duckworth Lewis, and possibly Stern, method), or Awarded (when a match is awarded to a team).
neutral_venue string If provided this indicates that the game was played at a venue neither team would regard as a home ground. The value will be true.
outcome string The outcome of the match if the match was not won by one of the teams. Currently the possible values are draw, no result, or tie.
player_of_match string This row will appear once for every player who was adjudged to be the player of the match. If multiple players won the award there will be one row for each of them.
reserve_umpire string The name of the reserve umpire, if any. If there was more than one then each will appear on it's own row.
season string (required) The season during which the match took place, such as 2018, or 2011/12.
series string The series the match was part of, if any.
team string (required) The name of a team which took place in the match. There will be one row for each team involved.
toss_decision string (required) The decision made by the team winning the toss. This will be either bat or field.
toss_winner string (required) The name of the team which won the toss.
tv_umpire string The name of the tv umpire, if any. If there was more than one then each will appear on it's own row.
umpire string The name of an umpire, if we have it. Each will appear on it's own row.
venue string The venue in which the game took place, such as Old Trafford.
winner string If a team won the match then this will be the name of the winning team.
winner_innings integer If the match was won by an innings (and a number of runs), then this will be 1.
winner_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.
winner_wickets integer If the match was won by a number of wickets, then this will contain the number of wickets.

The penalty_run rows

Penalty runs added before the start of an innings. In this case 6 runs were added before the start of the 2nd innings.

penalty_runs,2,pre,6

Penalty runs added after the end of the innings. In this case 5 runs where added after the end of the 1st innings.

penalty_runs,1,post,5

The penalty_runs rows, if there are any, provide details on any penalty runs applied to an innings either before or after the innings (rather than on a particular delivery). These typically occur when runs are added to an innings due to a slow over-rate in another innings of the match.

penalty_runs rows always consist of 4 columns. The first column in each row is, unsurprisingly, penalty_runs. The full breakdown is:

Position Column Description
1 Field string (required) Always penalty_runs.
2 Innings integer (required) The number of the innings to which the penalty runs apply.
3 Type string (required) When the penalty runs were applied. This will be either pre (for runs added before the start of the innings), or post (for runs added after the innings).
4 Runs integer (required) Number of penalty runs added.

The ball rows

A single simple delivery, with CJ Boyce bowling to SE Gotch, and no runs scored.

ball,2,11.2,Melbourne Stars,SE Gotch,KP Pietersen,CJ Boyce,0,0,,,,,,"",""

A delivery where the Cairns scored a 4 off the bowling of Khaled Mahmud.

ball,1,26.4,New Zealand,CL Cairns,SB Styris,Khaled Mahmud,4,0,,,,,,"",""

A delivery where 1 leg-bye was scored off the bowling of Malinga.

ball,1,18.2,Sunrisers Hyderabad,AJ Finch,DA Warner,SL Malinga,0,1,,,,1,,"",""

A delivery where Nevill was caught off the bowling of Starc.

ball,4,38.3,Australia,PM Nevill,MA Starc,HMRKB Herath,0,0,,,,,,caught,PM Nevill

Each 'ball' row has the following fields:

Position Column Description
1 Field string (required) Always ball.
2 Innings integer (required) The number of the innings in which the delivery took place.
3 Delivery number string (required) An identifier for the delivery (such as 23.5) specifies the particular ball (in that case the 5th ball of the 24th over).
4 Batting team string (required) The name of the team which was batting for the delivery. This will be one of the two teams mentioned in the info,team rows for the match.
5 Batter string (required) The name of the batter who faced the delivery.
6 Non-striker string (required) The name of the non-striker during the delivery.
7 Bowler string (required) The name of the bowler during the delivery.
8 Batter runs integer (required) The total number of runs scored by the batter off the ball. If the batter failed to score this will show 0
9 Total extras integer (required) The total number of runs conceded via extras off the ball. If no extras were conceded this will show 0.
10 Extras - Wides integer The number of wides conceded on the delivery. If no wides were conceded this will be blank.
11 Extras - No-balls integer The number of no-balls conceded on the delivery. If no no-balls were conceded this will be blank.
12 Extras - Byes integer The number of byes conceded on the delivery. If no byes were conceded this will be blank.
13 Extras - Leg-byes integer The number of legbyes conceded on the delivery. If no leg-byes were conceded this will be blank.
14 Extras - Penalty runs integer The number of penalty runs conceded on the delivery. If no penalty runs were conceded this will be blank.
15 Dismissal method string If any wickets fell on this delivery then this value will be each kind of dismissal that took place, separated by commas. Each dismissal 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. If no dismissals took place this will be an empty string.
16 Dismissed players string If any wickets fell on this delivery then this values will be the names of each dismissed player, separated by commas. If no dismissals took place this will be an empty string.