NAV

Introduction to the "Ashwin" CSV format

This document details the "Ashwin" CSV data provided by Cricsheet. This was the second CSV version provided, and takes it's nickname from Ashwin Raman who kindly suggested the initial format that I tweaked (in a few minor ways). This is probably the most straightforward data format to use if you're looking to do something with Cricsheet data.

This format now consists of 2 files per match, although you can get all of the ball-by-ball data from just one of the files. The files for a match are named <id>.csv (for the ball-by-ball data), and <id>_info.csv (for the match info), where <id> is the Cricinfo id for the match. The ball-by-ball file contains one row per delivery in the match, while the match info file contains match information such as dates the match was played, the outcome, and lists of the players involved in the match.

This page describes the organisation of the files and attempts to give some idea of the possible contents for each field. Unlike the "original" CSV format these files don't contain different types of rows. Instead the ball-by-ball files contains a single header row, with names for each column, and then each subsequent row details a single delivery, with some information on the match itself duplicated on each delivery row; whereas the match info file contains multiple info rows.

The current version number for the "Ashwin" format is 2.3.0, although this is mostly an internal designation and doesn't appear in the data.

The match info file

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,team_type,international
info,season,2011/12
info,date,2012/03/18
info,match_id,546443
info,match_type,T20
info,match_type_number,234
info,overs,20
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 the 1st innings was declared.

info,declared,1

A match where the 1st and 3rd innings were declared.

info,declared,1
info,declared,3

A match where the 2nd and 3rd innings were forfeited.

info,forfeited,2
info,forfeited,3

A match where the 3rd and 4th innings were super-overs.

info,super_over,3
info,super_over,4

A match with a 2nd innings of 20 overs where the batting team is trying to reach 151 runs to win.

info,target_overs,2,20
info,target_runs2,2,175

A match with a 2nd innings of 50 overs where the batting team is trying to reach 259 runs to win.

info,target_overs,2,50
info,target_runs2,2,259

A weather-affected match where the batting team required 253 by the time the game was called off (after 35.1 overs in the 2nd innings).

info,target_overs,2,35.1
info,target_runs,2,253

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.
declared integer The innings number for an inning that was declared. Each declared innings will have a row of it's own.
eliminator string The team name of the winner of any elimination super-over used to decide a tie in a T20 match.
forfeited integer The innings number for an inning that was forfeited. Each forfeited innings will have a row of it's own.
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_id string (required) The identifier used for the match within Cricsheet. Generally the Cricinfo match id, but not guaranteed to be so.
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.
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.
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.
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 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.
super_over integer The innings number for an inning that was a super-over. Each supper-over innings will have a row of it's own.
target_overs number If the target for an innings is known, then this will contain the number of overs (and deliveries) available, along with a column indicating the innings.
target_runs integer If the target for the match is known, then this will contain the runs required, along with a column indicating the innings.
team string (required) The name of a team which took place in the match. There will be one row for each team involved.
team_type string (required) The type of team playing in the match, either international or club.
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 ball-by-ball file

A delivery with no runs scored, featuring Anderson bowling to Kolhi, with Ashwin at the non-strikers end. It was the first ball of the 47th over in the 4th innings.

1243384,2020/21,2021-02-05,MA Chidambaram Stadium,4,46.1,46.1,India,England,V Kohli,R Ashwin,JM Anderson,0,0,,,,,,,,,,,,,

A delivery where a single was scored, featuring Ecclestone bowling to Devine, with Satterthwaite at the non-strikers end. It was the third ball of the 12th over in the 2nd innings.

1249234,2020/21,2021-02-28,University Oval,2,11.3,11.3,New Zealand,England,SFM Devine,AE Satterthwaite,S Ecclestone,1,0,,,,,,,,,,,,,

A delivery where a wide was bowled, featuring Naveen-ul-Haq bowling to Shumba, with Musakanda at the non-strikers end. It was the second ball of the 7th over in the 2nd innings after another wide on the 1st delivery.

1252060,2020/21,2021-03-20,Sheikh Zayed Stadium,2,6.2,6.1,Zimbabwe,Afghanistan,M Shumba,TK Musakanda,Naveen-ul-Haq,0,1,1,,,,,,,,,,,,

A delivery where a wicket took place, with the batter being dismissed caught by AN Other, featuring Boland bowling to Philippe, with Vince at the non-strikers end. It was the 3rd ball of the 4th over in the 2nd innings.

1226827,2020/21,2021-01-24,Melbourne Cricket Ground,2,2.3,2.3,Sydney Sixers,Hobart Hurricanes,JR Philippe,JM Vince,SM Boland,0,0,,,,,,,caught,JR Philippe,,,AN Other,,

Following a header row, featuring each of the fields shown below as a header, each row of the ball-by-ball file details a single delivery from the match. The fields covered in each row are as follows:

Field Description
match_id string (required) The id for the match. Currently this is the ID as used by ESPNCricinfo.
season string (required) The season during which the match took place, such as 2018, or 2011/12.
start_date string (required) The start date of the match took place, in the format YYYY/MM/DD. Matches with multiple days will only show the first.
venue string The venue in which the game took place, such as Old Trafford. If not provided this will be blank.
innings integer (required) The number of the innings in which the delivery took place.
ball 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).
actual_delivery string (required) The actual delivery number, which takes into account wides and no-balls, meaning that a delivery after one of those will have the same actual_delivery value as the previous delivery.
batting_team string (required) The name of the team which was batting for the delivery.
bowling_team string (required) The name of the team which was bowling for the delivery.
striker string (required) The name of the batter who faced the delivery.
non_striker string (required) The name of the non-striker during the delivery.
bowler string (required) The name of the bowler during the delivery.
runs_off_bat 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.
wides integer The number of wides conceded on the delivery. If no wides were conceded this will be blank.
noballs integer The number of no-balls conceded on the delivery. If no no-balls were conceded this will be blank.
byes integer The number of byes conceded on the delivery. If no byes were conceded this will be blank.
legbyes integer The number of legbyes conceded on the delivery. If no leg-byes were conceded this will be blank.
penalty integer The number of penalty runs conceded on the delivery. If no penalty runs were conceded this will be blank.
non_boundary string If a non-boundary occurred on this delivery then this 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.
wicket_type string If a wicket fell on this delivery then this will be 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. If no dismissals took place this will be an empty string.
player_dismissed string If a wicket fell on this delivery then this will be the name of the dismissed player. If no dismissals took place this will be an empty string.
other_wicket_type string If a second wicket occurs on the delivery (such as due to a player retiring hurt when another wicket falls) this will be the type of the dismissal, 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.
other_player_dismissed string If a second wicket fell on this delivery then this will be the name of the second dismissed player. If no dismissals took place this will be an empty string.
fielder_1 string If we know them this will contain the names of the first fielder who were involved in a dismissal.
fielder_2 string If we know them this will contain the names of the first fielder who were involved in a dismissal. This field will only be populated if a second fielder is involved in a run-out.
fielder_3 string If we know them this will contain the names of the first fielder who were involved in a dismissal. This field will only be populated if a third fielder is involved in a run-out.

Changelog

Version 2.3.0

Version 2.2.0

Version 2.1.0

Version 2.0.0