CSV Documentation¶
- Getting Started
- Naming Convention
- Data Fields
- ID
- VoterID
- ApplicationRequestOtherType
- ApplicationRequestPostmarkDate
- ApplicationRequestProcessedDate
- ApplicationRequestReceivedDate
- ApplicationRequestStatusOtherType
- ApplicationRequestStatusType
- ApplicationRequestType
- ApplicationType
- BallotRejectionOtherType
- BallotRejectionType
- BallotReturnDate
- BallotReturnOtherType
- BallotReturnType
- BallotTransmissionDate
- BallotTransmissionOtherType
- BallotTransmissionType
- BallotType
- ElectionDate
- ElectionName
- JurisdictionId
- JurisdictionIdType
- JurisdictionName
- StateName
- VoterMailingCountry
- VoterType
- WasApplicationRejected
Getting Started¶
If you’re a state or local election official reading this, first, thank you for your work and your interest in the project. The data required to participate in this project is typically found in absentee voter roster files, voter registration databases, or voter history files. Sometimes all three…and maybe others. The standard looks to capture Uniformed and Overseas Citizen Absentee Voting Act (UOCAVA) transactions, such as:
- when a voter requests a ballot;
- when the application is processed;
- to what country the ballot is sent and when;
- why an application/ballot is rejected; and,
- whether a voter is military or overseas citizen.
To make the process of collecting data easier, this project borrows lessons from the Voting Information Project’s (VIP’s) approach to data collection: use a flat file format for data collection and push any transformations downstream.
Naming Convention¶
Due to the many issues around elections data collection and cleanliness, much of the data still requires some form of human oversight. Therefore, having a relatively accessible file naming convention is beneficial. While this is not a hard-and-fast rule, anyone producing data in this standard should use the following naming convention, which borrows from a yet-unreleased version of the Voting Information Project’s documentation.
esbdata-${ELECTION_DATE}-${STATE}[-${LOCAL}].{csv|zip}
An explanation of each of the segments of the file naming convention above are as follows:
${ELECTION_DATE}
- The date of the election in ISO 8601 format.${STATE}
- The full state name (e.g. Alaska, Arkansas, etc…) and not the abbreviation. If there are spaces in the state name, they should be substituted with underscores (e.g. New York -> New_York).${LOCAL}
(optional) - This additional identifier should be used if the file contains data from a specific jurisdiction. As with${STATE}
above, all spaces should be substituted with underscores. For example, if the data contained in the file only covers Maricopa County, AZ for the November 6, 2012 election, the file name would beesbdata-2012-11-06-Arizona-Maricopa_County.csv
.{csv|zip}
- If the file is an uncompressed CSV document, the extension should be.csv
. If the file is zipped, the file extension should end with.zip
.
For a final example, esbdata-2012-11-06-Iowa.zip
denotes Iowa’s data for the Nov 6, 2012 election
that has been compressed.
Data Fields¶
The following fields are possible data points for each transaction that the standard hopes to collect.
ID¶
Data Type: string
This field is required and must be unique.
Unique identifier for the transaction (i.e. not the voter). IDs should remain consistent, regardless of when an export is created.
VoterID¶
Data Type: string
This field is required.
Identifier that uniquely identifies a voter, but is not required to be unique within the dataset. This number must be obfuscated from the original voter identifier in the jurisdiction’s registration database. This field helps analyze how effective each type of transaction is for an individual voter. In addition, if there are questions about a particular voter’s transactions, an organization could provide this identifier back to the jurisdiction to glean more information about the voter’s experience.
ApplicationRequestOtherType¶
Data Type: string
If ApplicationRequestType fails to cover all of the possible request types for a particular voter transaction, this field specifies an alternate method by which the application request was received.
ApplicationRequestPostmarkDate¶
Data Type: date
Specifies the date the request was postmarked. If there is any confusion as to the whether the date the application was recorded was the date on the postmark or the date the application was physically received by the election administration entity, assume postmark and use this field rather than ApplicationRequestReceivedDate.
ApplicationRequestProcessedDate¶
Data Type: date
Specifies the date the request was processed by the local or state election official.
ApplicationRequestReceivedDate¶
Data Type: date
Specifies the date the application request was received by the local or state election official. In mail-only states, this date is the most recent date the voter became an active UOCAVA voter.
ApplicationRequestStatusOtherType¶
Data Type: string
If ApplicationRequestStatusType fails to cover all possible types of Application Request statuses, this field will list an alternate type.
ApplicationRequestStatusType¶
Data Type: array
This field is required.
Specifies the current status of the application. Possible values are duplicate, which denotes that the election official already received an application for the voter, invalid, which means the application was invalid, mismatch-voter-signature, which means the application signature did not match the voter signature on file, missing-ssn, denoting that the Social Security Number was missing from the application, missing-state-id-number, which means the state identifier was required and missing from the application, missing-voter-signature, meaning the voter did not sign the application, pending, which means the application is still being processed, valid, which denotes an accepted application, and other, which is a catch-all for any values that fall outside of the other values. Multiple values are possible for this field.
The value of ApplicationRequestStatusType
must be one of the following:
- duplicate
- invalid
- mismatch-voter-signature
- missing-ssn
- missing-state-id-number
- missing-voter-signature
- pending
- valid
- other
ApplicationRequestType¶
Data Type: string
This field is required.
Specifies the method by which the application request was received. Possible values are email, which signifies the application was received via email; fax, which denotes the application was received by fax; in-person, which means the application was delivered by a person (NB: this does not necessarily signify the voter themselves delivered the application); mail, which signifies the application was received via mail; online, which means the application was submitted via online form or system; phone, which means the request was placed via phone call; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.
The value of ApplicationRequestType
must be one of the following:
- fax
- in-person
- online
- phone
- untracked
- other
ApplicationType¶
Data Type: string
This field is required.
Specifies the type of ballot application request. Possible values are fpca, which means a voter submitted a Federal Postcard Application; fwab, which denotes a voter returned a Federal Write-In Absentee Ballot prior to receiving or requesting a ballot through other means; informal-request, which signifies a voter requested a ballot through a less formal process, such as a letter or phone call; nvra, which means a voter used a National Voter Registration (Act) form; state-application, which denotes a state form used for ballot requests; and untracked, which means the type of application is not tracked.
The value of ApplicationType
must be one of the following:
- fpca
- fwab
- informal-request
- nvra
- state-application
- untracked
BallotRejectionOtherType¶
Data Type: string
If BallotRejectionType fails to cover all of the possible ways a ballot may be rejected, this field specifies an alternate reason why the reason the ballot was rejected.
BallotRejectionType¶
Data Type: array
Specifies the reason why the ballot was rejected. Possible values are mismatch-voter-signature, which denotes the signature on file did not match the signature on the returned envelope or document; missing-voter-signature, which signifies that the voter signature is missing on the returned documents; not-timely, which means the ballot was received after the required deadline; postmark, which signifies the ballot was postmarked after the required date; rejected, which signifies the ballot was rejected for an unspecified reason; undeliverable, which denotes the ballot was returned as undeliverable to the address where it was sent; untracked, which signifies that this variable is not tracked in the system; voided-spoiled, which means the ballot had to be voided or spoiled either by the administration or the voter; voter-died, which signifies the voter died thereby impacting the ability to count the ballot (NB: this is largely dependent on state law); voter-moved, which signifies the voter moved from their registered address; voter-unregistered, which means the voter is not registered to vote; and, other, which is a catch-all for any values that fall outside of the other values.
The value of BallotRejectionType
must be one of the following:
- mismatch-voter-signature
- missing-voter-signature
- not-timely
- postmark
- rejected
- undeliverable
- untracked
- voided-spoiled
- voter-died
- voter-moved
- voter-unregistered
- other
BallotReturnDate¶
Data Type: date
Specifies the date the voter returned the ballot to the local or state election official.
BallotReturnOtherType¶
Data Type: string
If BallotReturnType fails to cover all of the possible return types for a particular voter transaction, this field specifies an alternate method by which the voter returned the ballot to the local or state election official.
BallotReturnType¶
Data Type: string
Specifies the method by which the voter returned the ballot to the local or state election official. Possible values are email, which signifies the ballot was received via email; fax, which denotes the ballot was received by fax; in-person, which means the ballot was delivered by a person (NB: this does not necessarily signify the voter themselves delivered the ballot); mail, which signifies the ballot was received via mail; online, which means the ballot was submitted via online form or system; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.
The value of BallotReturnType
must be one of the following:
- fax
- in-person
- online
- untracked
- other
BallotTransmissionDate¶
Data Type: date
Specifies the date the local or state election official sent the ballot to the voter.
BallotTransmissionOtherType¶
Data Type: string
If BallotTransmissionType fails to cover all of the possible transmission types for a particular transaction, this field specifies an alternate method in which the local or state election official sent the ballot to the voter.
BallotTransmissionType¶
Data Type: string
Specifies the method in which the ballot was sent to the voter. Possible values are email, which signifies the ballot was transmitted via email; fax, which denotes the ballot was transmitted by fax; in-person, which means the ballot given to a person; mail, which signifies the ballot was transmitted via mail; online, which means the ballot was transmitted via online form or system; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.
The value of BallotTransmissionType
must be one of the following:
- fax
- in-person
- online
- untracked
- other
BallotType¶
Data Type: string
Specifies the type of ballot transferred to the voter. Possible values are absentee, which is a general catch-all for any type of absentee ballot, federal, which denotes the voter only received a ballot that allows voting on federal contests, full, which denotes a ballot with all possible contests in the voter’s assigned precinct; fwab, which specifies a Federal Write-In Absentee Ballot, and provisional, which denotes a provisional ballot; and, untracked, which signifies that this variable is not tracked in the system.
The value of BallotType
must be one of the following:
- absentee
- federal
- full
- fwab
- provisional
- untracked
JurisdictionId¶
Data Type: string
This field is required.
Specifies a unique identifier for the jurisdiction.
JurisdictionIdType¶
Data Type: string
This field is required.
Specifies the type of identifier used to identify the jurisdiction in JurisdictionId. Possible values are local, which dictates the jurisdiction created the identifier, fips, which means the identifier follows the Federal Information Processing Standard (FIPS) code, or ocd-id, which means the identifier follows the Open Civic Data Division Identifier (OCDID) standard.
The value of JurisdictionIdType
must be one of the following:
- ocd-id
- fips
- local
JurisdictionName¶
Data Type: string
This field is required.
Specifies the name of the jurisdiction in which the voter is registered.
StateName¶
Data Type: string
This field is required.
Specifies the name of the state in which the voter is registered.
The value of StateName
must be one of the following:
- Alabama
- Alaska
- American Samoa
- Arizona
- Arkansas
- California
- Colorado
- Connecticut
- Delaware
- District Of Columbia
- Federated States Of Micronesia
- Florida
- Georgia
- Guam
- Hawaii
- Idaho
- Illinois
- Indiana
- Iowa
- Kansas
- Kentucky
- Louisiana
- Maine
- Marshall Islands
- Maryland
- Massachusetts
- Michigan
- Minnesota
- Mississippi
- Missouri
- Montana
- Nebraska
- Nevada
- New Hampshire
- New Jersey
- New Mexico
- New York
- North Carolina
- North Dakota
- Northern Mariana Islands
- Ohio
- Oklahoma
- Oregon
- Palau
- Pennsylvania
- Puerto Rico
- Rhode Island
- South Carolina
- South Dakota
- Tennessee
- Texas
- Utah
- Vermont
- Virgin Islands
- Virginia
- Washington
- West Virginia
- Wisconsin
- Wyoming
VoterMailingCountry¶
Data Type: string
Specifies what country to which the ballot was mailed. The country should be a recognized country name according to ISO 3166.
VoterType¶
Data Type: string
Specifies whether the voter is domestic or overseas military (or, if the domestic or overseas designation is unknown, simply whether the voter is military), overseas citizen, or other.
The value of VoterType
must be one of the following:
- domestic-military
- military
- overseas-citizen
- overseas-military
- other
WasApplicationRejected¶
Data Type: boolean
Deprecated. Specifies whether the application request was accepted or rejected.