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.7.0.

The version row

The version of the data format is always included.

version,1.7.0

The single version line contains the version of the data format. Currently this is 1.6.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.6.0.

The info rows

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

info,balls_per_over,6
info,team,Afghanistan
info,team,Canada
info,gender,male
info,season,2011/12
info,date,2012/03/18
info,event,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
info,player,Afghanistan,Karim Sadiq
info,player,Afghanistan,Shabir Noori
info,player,Afghanistan,Mohammad Shahzad
info,player,Afghanistan,Nawroz Mangal
info,player,Afghanistan,Samiullah Shenwari
info,player,Afghanistan,Mohammad Nabi
info,player,Afghanistan,Gulbadin Naib
info,player,Afghanistan,Mirwais Ashraf
info,player,Afghanistan,Dawlat Zadran
info,player,Afghanistan,Zamir Khan
info,player,Afghanistan,Izatullah Dawlatzai
info,player,Canada,H Patel
info,player,Canada,R Gunasekera
info,player,Canada,Junaid Siddiqui
info,player,Canada,NR Kumar
info,player,Canada,AS Hansra
info,player,Canada,Rizwan Cheema
info,player,Canada,TG Gordon
info,player,Canada,HS Baidwan
info,player,Canada,RA Bhatti
info,player,Canada,H Osinde
info,player,Canada,Zahid Hussain
info,registry,people,AS Hansra,795df06c
info,registry,people,Dawlat Zadran,1fba2ae3
info,registry,people,GF Labrooy,8e088dbc
info,registry,people,Gulbadin Naib,9f77963a
info,registry,people,H Osinde,2b8b75a0
info,registry,people,H Patel,c4ff0618
info,registry,people,HS Baidwan,7839bf3a
info,registry,people,Izatullah Dawlatzai,f96933f0
info,registry,people,JD Cloete,b0419f8c
info,registry,people,JS Wilson,d7f3b72f
info,registry,people,Junaid Siddiqui,9025e58f
info,registry,people,Karim Sadiq,13e5908b
info,registry,people,Mirwais Ashraf,bdd985f2
info,registry,people,Mohammad Nabi,62af8546
info,registry,people,Mohammad Shahzad,d6dcb0c9
info,registry,people,NR Kumar,b3bad3f2
info,registry,people,Nawroz Mangal,0503ae22
info,registry,people,R Gunasekera,9b6ad88a
info,registry,people,RA Bhatti,113880da
info,registry,people,Rizwan Cheema,3a026eb4
info,registry,people,S Asnani,b04524bc
info,registry,people,Samiullah Shenwari,61646132
info,registry,people,Shabir Noori,5e71fa21
info,registry,people,TG Gordon,9cbbe35b
info,registry,people,Zahid Hussain,1e5708ac
info,registry,people,Zamir Khan,21d46f15

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

A match where Mohammad Shahzad played for Afghanistan.

info,player,Afghanistan,Mohammad Shahzad

An entry for the person Mohammad Shahzad in the registry.

info,registry,people,Mohammad Shahzad,d6dcb0c9

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. 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
balls_per_over integer (required) The number of balls expected per over, generally 6.
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.
event string The event 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 event 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, 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).
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.
player string (required) This row will appear once for every player who played in the match. Each entry will include the team the player played for, followed by name of the player.
registry string (required) This row will appear for each person involved in the game (whether a player or official), and will consist of name of the person, followed by the stable unique identifier used for that person (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.
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.
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_uncontested string 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.
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.

Changelog

Version 1.7.0

Version 1.6.0

Version 1.5.0