CSV Documentation¶
- Getting Started
- Naming Convention
- Data Fields
- Id
- VoterId
- RequestMethod
- RequestOtherMethod
- RequestDate
- RequestStatusType
- RequestStatusReasonType
- RequestReasonOtherType
- RequestType
- BallotRejectionType
- BallotRejectionOtherType
- BallotReceivedDate
- BallotReceivedMethod
- BallotReceivedOtherMethod
- BallotTransmissionDate
- BallotTransmissionMethod
- BallotTransmissionOtherMethod
- BallotType
- ElectionDate
- ElectionName
- JurisdictionId
- JurisdictionIdType
- JurisdictionName
- StateName
- VoterMailingCountry
- VoterType
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.
RequestMethod¶
Data Type: string
This field is required.
Specifies the method by which the request was triggered. Possible values are email; fax; in-person, which means the request was triggered by a person; mail; online, which means the request was submitted via online form or system — through the elections office or other registration agency; 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 RequestMethod
must be one of the following:
- fax
- in-person
- online
- phone
- untracked
- other
RequestOtherMethod¶
Data Type: string
If RequestMethod fails to cover all of the possible request methods for a particular voter transaction, this field specifies an alternate method by which the request was received.
RequestDate¶
Data Type: date
Specifies the date the request was processed by the local or state election official.
RequestStatusType¶
Data Type: string
This field is required.
Specifies the current status of the request. Possible values are accepted, which denotes that the request was successfully processed; cancelled, which signifies that the request has been cancelled by a voter’s direct or indirect action; pending, which signifies that request is still being processed; rejected, which means the request was not successfully processed.
The value of RequestStatusType
must be one of the following:
- accepted
- cancelled
- pending
- rejected
RequestStatusReasonType¶
Data Type: array
This field is required.
If RequestStatusType is rejected, cancelled, or pending, then RequestStatusReasonType specifies the reason the activity was rejected. 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-identification, which means that an unspecified identifier was required and missing from the application; 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; untracked, which means the reason for rejection is not tracked; 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 RequestStatusReasonType
must be one of the following:
- duplicate
- invalid
- mismatch-voter-signature
- missing-identification
- missing-ssn
- missing-state-id-number
- missing-voter-signature
- untracked
- other
RequestReasonOtherType¶
Data Type: string
If RequestStatusReasonType fails to cover all possible types of request reasons, this field will list an alternate type.
RequestType¶
Data Type: string
This field is required.
Specifies the type of request that triggered the change. 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 triggered the activity; and untracked, which means the type of application is not tracked.
The value of RequestType
must be one of the following:
- fpca
- fwab
- informal-request
- nvra
- state-application
- untracked
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
BallotRejectionOtherType¶
Data Type: string
If BallotRejectionType fails to cover all the possible ways a ballot may be rejected, this field specifies an alternate reason why the reason the ballot was rejected.
BallotReceivedDate¶
Data Type: date
Specifies the date the ballot was received by the local or state election official.
BallotReceivedMethod¶
Data Type: string
Specifies the method by which the ballot was received by 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 BallotReceivedMethod
must be one of the following:
- fax
- in-person
- online
- untracked
- other
BallotReceivedOtherMethod¶
Data Type: string
If BallotReceivedMethod 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.
BallotTransmissionDate¶
Data Type: date
Specifies the date the local or state election official sent the ballot to the voter.
BallotTransmissionMethod¶
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 BallotTransmissionMethod
must be one of the following:
- fax
- in-person
- online
- untracked
- other
BallotTransmissionOtherMethod¶
Data Type: string
If BallotTransmissionMethod 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.
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 fips, which means the identifier follows the Federal Information Processing Standard (FIPS) code, local, which dictates the jurisdiction created the identifier, 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:
- fips
- local
- ocd-id
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 simply military if the designation is unknown), a spouse or dependent of a member of the military, or other if the type of voter falls outside the previous designations.
The value of VoterType
must be one of the following:
- domestic-military
- domestic-military-spouse-dependent
- military
- military-spouse-dependent
- overseas-citizen
- overseas-military
- overseas-military-spouse-dependent
- other