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
File: voters.tsv
Header:
NationalVoterId VoterGroupId
File: votingGroups.tsv
Header:
VoterGroupId PollingLocationId
File: pollingLocations.tsv
Header:
PollingLocationId Address HoursOfOperation
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-06-26 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-06-26 UTC."],[[["\u003cp\u003eThis document outlines a draft specification for providing polling location and candidate data to Google for elections using National IDs.\u003c/p\u003e\n"],["\u003cp\u003eThe data should be provided in six separate TSV (tab-separated value) files: voters.tsv, votingGroups.tsv, districts.tsv, pollingLocations.tsv, candidates.tsv, and offices.tsv.\u003c/p\u003e\n"],["\u003cp\u003eRequired fields are marked with *, primary keys with **, and fields requiring internationalization with ^Æ^.\u003c/p\u003e\n"],["\u003cp\u003eInternationalization is achieved by appending locale specifications to the field names, enabling data in multiple languages.\u003c/p\u003e\n"],["\u003cp\u003eSample file headers are provided to demonstrate the structure and format of the data files.\u003c/p\u003e\n"]]],[],null,["# National ID Elections Data Specification\n\nThis document contains a specification for the data necessary for\nGoogle to provide polling location and candidate information for\nNational ID-based elections. This document is a draft specification\nintended primarily to solicit feedback and may change in the future.\n\nTables\n------\n\n\nThe following set of tables should be provided as separate\n[tab-separated\nvalue](http://en.wikipedia.org/wiki/Tab-separated_values) (TSV) files. Each file should start with a single\nheader line listing the fields for that table. Optional header fields\ndo not need to be included if there is no data for the corresponding\nfield. The subsequent lines in the file contain the data rows with\nfields in the same order as those specified in the header row.\n\n\nThe files should be named appropriately and bundled inside of a zip\narchive. The files should be named: voters.tsv, votingGroups.tsv,\ndistricts.tsv, pollingLocations.tsv, candidates.tsv, offices.tsv.\n\nUnless noted otherwise, each field indicated in this specification is\na string. TSV files do not require escaping for commas or special\ncharacters other than tabs. As tabs are not appropriate for any of\nthe fields in any of the tables, we explicitly disallow them from\nbeing in a field.\n\n\n\\* is used to indicate a required field in the table \n\n\\*\\* is used to indicate a required field that is also a primary key for\nthat table (two rows cannot have the same value for this field) \n\n^Æ^ indicates a field that must be internationalized. \n\nInternationalization\n--------------------\n\nIn order to ensure that data is presented in the correct language\nsome fields in the header row need to include a locale specification.\nAs some countries have more than one language data may need to be\nprovided in more than one language. For such countries columns may be\nrepeated with a different locale appended to the end of the column\nname and separated with a dash, e.g. PartyAffiliation-en.\n\nTo construct locales refer to the Google APIs page on\n[Identifiers for Languages, Countries, Currencies, and Time Zones](http://code.google.com/apis/identifiers/index.html).\nThese specifications rely on\n[Best Current Practices 47 -\nTags for Identifying Languages](http://tools.ietf.org/html/bcp47) (BCP 47).\nSee [Appendix\nA](http://tools.ietf.org/html/bcp47#appendix-A) of BCP 47 for examples of language tags.\n\n### Table 1 - Voter Table (Required)\n\n`NationalVoterId**, VoterGroupId`\n\nA row in the voter table represents a single voter. Each voter in\nthe country has a national ID or Voter ID, this is stored in the\nNationalVoterId field. VoterGroupId indicates which voting group this\nvoter belongs to.\n\n\nNotes: In countries where no logical voting group exists, the\nVoterGroupId can be a repeat of the the NationalVoterId in which case\nthe voting group table (Table 2) will directly assign voters to\ndistrict ids and polling location ids.\n\n### Table 2 - Voting Group Table (Required)\n\n`VoterGroupId**, PollingLocationId*, ProvinceDistrictId,\nCountyDistrictId, LocalityDistrictId`\n\nA row in this table identifies a voting group, where that group\nvotes (via PollingLocationId), and which district(s) this voting group\nbelongs to. Each voting group is uniquely identified by a\nVoterGroupId. Multiple district Ids may be specified since a given\nvoting group may vote for different officials at different levels of\ngovernment. For example, in the US one might vote for a governor at\nthe state level, a county executive at the county level, and a mayor\nat a city level.\n\nNotes: Every individual in a voting group should be\nvoting on the same contests and at the same polling location. A\nvoting group should be split up into multiple voting groups if this is\nnot the case.\n\n### Table 3 - District Table (Required)\n\n`DistrictId**, AuthorityName*, LocalElectionOfficialName*,\nLocalElectionOfficialPhone*, LocalElectionUrl*,\nLocalElectionOfficialEmail, LocalElectionOfficialAddress`\n\n\nEach row in the district table contains data a voting district\nincluding local election official information. The authority name\nfield should include the name of the district if appropriate,\ne.g. District of Columbia.\n\n### Table 4 - Polling Location (Required)\n\n`PollingLocationId**, Address*`^Æ^`, Latitude, Longitude,\nHoursOfOperation`^Æ^`, AdditionalDirections`^Æ^`,\nContactInfo`^Æ^\n\n\nEach polling location is represented by a row in the polling location\ntable. The address field should contain a string with the fully\nspecified address for the polling location. Addresses may be used to\nprovide map links so addresses that map accurately on geo web sites\nare ideal. In cases where a mappable address is not possible, the\ninformation will be provided to the user as text. Latitude and\nLongitude are optional fields containing the geodetic latitude and\nlongitude. Providing latitudes and longitudes provides valuable\ninformation for error checking polling location results.\n\n\nThe AdditionalDirections field is optional and may contain directions\nnecessary for finding a polling place, e.g. within the building\nspecified by the address. The ContactInfo field should contain\ninformation necessary to contact officials responsible for this\npolling location.\n\n### Table 5 - Candidate Table (Required)\n\n`CandidateId**, CandidateName*`^Æ^`,\nPartyAffiliation`^Æ^`, OfficeId*, Url,\nCampaignAddress`^Æ^`, Photo, Phone, TwitterHandle,\nFacebookUsername, Email, YoutubeChannel`\n\n\nEach row in the candidate table represents a candidate. CandidateId\nuniquely identifies a candidate. The office field contains the name\nof the office this candidate is running for. Other fields in this\ntable provide information about the candidate.\n\n### Table 6 - Office Table\n\n`OfficeId**, DistrictId*, Name`^Æ^`, Term`^Æ^`,\nDescription`^Æ^\n\n\nEach office has a row in this table uniquely identified by an\noffice Id. The name and description of the office is also included.\nThe DistrictId field must specify one of the District Ids listed in\nthe ProvinceDistrictId, CountyDistrictId, or LocalityDistrictId fields\nin the Voting Group table. For offices that are voted on by all\nvoters, ALL should be used as the District Id.\n\nSamples\n-------\n\n### Sample Polling Location Data File Headers\n\n\nFile: voters.tsv \n\nHeader: \n\n```\nNationalVoterId VoterGroupId\n```\n\n\nFile: votingGroups.tsv \n\nHeader: \n\n```\nVoterGroupId PollingLocationId\n```\n\n\nFile: pollingLocations.tsv \n\nHeader: \n\n```\nPollingLocationId Address HoursOfOperation\n```\n\n### Sample Multi-Language File Header\n\n\nIf a country had multiple languages the header for each file may have\nadditional fields indicating the language/locale of the data included\nin that field. Only fields that are marked internationalizable,\ni.e. with the ^Æ^ marker, in the table descriptions above should have\nlocale appended.\n\n\nFile: pollingLocations.tsv \n\nHeader: \n\n```\nPollingLocationId Address HoursOfOperation-en HoursOfOperation-fr\n```\n\nThis simple example shows the hours of operation field in English\nand French."]]