National ID Elections Data Specification

This document contains a specification for the data necessary for Google to provide polling location and candidate information for National ID-based elections. This document is a draft specification intended primarily to solicit feedback and may change in the future.

Tables

The following set of tables should be provided as separate tab-separated value (TSV) files. Each file should start with a single header line listing the fields for that table. Optional header fields do not need to be included if there is no data for the corresponding field. The subsequent lines in the file contain the data rows with fields in the same order as those specified in the header row.

The files should be named appropriately and bundled inside of a zip archive. The files should be named: voters.tsv, votingGroups.tsv, districts.tsv, pollingLocations.tsv, candidates.tsv, offices.tsv.

Unless noted otherwise, each field indicated in this specification is a string. TSV files do not require escaping for commas or special characters other than tabs. As tabs are not appropriate for any of the fields in any of the tables, we explicitly disallow them from being in a field.

* is used to indicate a required field in the table
** is used to indicate a required field that is also a primary key for that table (two rows cannot have the same value for this field)
^Æ indicates a field that must be internationalized.

Internationalization

In order to ensure that data is presented in the correct language some fields in the header row need to include a locale specification. As some countries have more than one language data may need to be provided in more than one language. For such countries columns may be repeated with a different locale appended to the end of the column name and separated with a dash, e.g. PartyAffiliation-en.

To construct locales refer to the Google APIs page on Identifiers for Languages, Countries, Currencies, and Time Zones. These specifications rely on Best Current Practices 47 - Tags for Identifying Languages (BCP 47). See Appendix A of BCP 47 for examples of language tags.

Table 1 - Voter Table (Required)

NationalVoterId**, VoterGroupId

A row in the voter table represents a single voter. Each voter in the country has a national ID or Voter ID, this is stored in the NationalVoterId field. VoterGroupId indicates which voting group this voter belongs to.

Notes: In countries where no logical voting group exists, the VoterGroupId can be a repeat of the the NationalVoterId in which case the voting group table (Table 2) will directly assign voters to district ids and polling location ids.

Table 2 - Voting Group Table (Required)

VoterGroupId**, PollingLocationId*, ProvinceDistrictId,
CountyDistrictId, LocalityDistrictId

A row in this table identifies a voting group, where that group votes (via PollingLocationId), and which district(s) this voting group belongs to. Each voting group is uniquely identified by a VoterGroupId. Multiple district Ids may be specified since a given voting group may vote for different officials at different levels of government. For example, in the US one might vote for a governor at the state level, a county executive at the county level, and a mayor at a city level.

Notes: Every individual in a voting group should be voting on the same contests and at the same polling location. A voting group should be split up into multiple voting groups if this is not the case.

Table 3 - District Table (Required)

DistrictId**, AuthorityName*, LocalElectionOfficialName*,
LocalElectionOfficialPhone*, LocalElectionUrl*,
LocalElectionOfficialEmail, LocalElectionOfficialAddress

Each row in the district table contains data a voting district including local election official information. The authority name field should include the name of the district if appropriate, e.g. District of Columbia.

Table 4 - Polling Location (Required)

PollingLocationId**, Address*^Æ, Latitude, Longitude,
HoursOfOperation^Æ, AdditionalDirections^Æ,
ContactInfo^Æ

Each polling location is represented by a row in the polling location table. The address field should contain a string with the fully specified address for the polling location. Addresses may be used to provide map links so addresses that map accurately on geo web sites are ideal. In cases where a mappable address is not possible, the information will be provided to the user as text. Latitude and Longitude are optional fields containing the geodetic latitude and longitude. Providing latitudes and longitudes provides valuable information for error checking polling location results.

The AdditionalDirections field is optional and may contain directions necessary for finding a polling place, e.g. within the building specified by the address. The ContactInfo field should contain information necessary to contact officials responsible for this polling location.

Table 5 - Candidate Table (Required)

CandidateId**, CandidateName*^Æ,
PartyAffiliation^Æ, OfficeId*, Url,
CampaignAddress^Æ, Photo, Phone, TwitterHandle,
FacebookUsername, Email, YoutubeChannel

Each row in the candidate table represents a candidate. CandidateId uniquely identifies a candidate. The office field contains the name of the office this candidate is running for. Other fields in this table provide information about the candidate.

Table 6 - Office Table

OfficeId**, DistrictId*, Name^Æ, Term^Æ,
Description^Æ

Each office has a row in this table uniquely identified by an office Id. The name and description of the office is also included. The DistrictId field must specify one of the District Ids listed in the ProvinceDistrictId, CountyDistrictId, or LocalityDistrictId fields in the Voting Group table. For offices that are voted on by all voters, ALL should be used as the District Id.

Samples

Sample Polling Location Data File Headers

File: voters.tsv
Header:

NationalVoterId        VoterGroupId

File: votingGroups.tsv
Header:

VoterGroupId        PollingLocationId

File: pollingLocations.tsv
Header:

PollingLocationId        Address        HoursOfOperation

Sample Multi-Language File Header

If a country had multiple languages the header for each file may have additional fields indicating the language/locale of the data included in that field. Only fields that are marked internationalizable, i.e. with the ^Æ marker, in the table descriptions above should have locale appended.

File: pollingLocations.tsv
Header:

PollingLocationId        Address        HoursOfOperation-en        HoursOfOperation-fr

This simple example shows the hours of operation field in English and French.