Developer Data Guidelines

Political Geography and Elected Representatives

The Google Civic Information API offers information about political geographic divisions and elected representatives for US addresses from the federal to the local level. At present, we have coverage approaching 100% for state, county, and Congressional districts, and aim to exceed 90% coverage for state legislative districts. Lower levels, such as city and county councils, are served on a best-effort basis and will improve over time.

We expect to have up-to-date information about all elected officials at the federal, state, and county levels, and city officials for the largest city in each US State as well as any city of population greater than 250,000. We aggregate this data from multiple sources and serve the highest-quality available information. If we discover data quality issues, we may stop returning data for particular geographic divisions, elected offices, or elected officials.

Voting Information

The Google Civic Information API returns civic information including polling place, early vote location, local election official contact information and ballot information to users for elections supported by the Voting Information Project.

Data Availability

Please see this chart for expected availability of data for the 2014 US midterm elections. These are estimates, and subject to change based on availability of data from election officials, the Voting Information Project and other sources.

Additional Guidelines

This data is particularly tricky to work with. Please keep the following points in mind.

  • Election officials revise this data often in the last few weeks and even the last few days before the election. It is a good idea to warn users that they should check back before voting.
  • Most official feeds contain street segments, meaning election officials tie a range of addresses to precincts and polling locations. The ranges may or may not have any voters registered at those address. Consequently, for states providing official feeds through the Voting Information Project, an address at which there are no registered voters may return a success.
  • For states not providing an official feed, only addresses at which there is a registered voter will return success.
  • On occasion, we will have multiple sources for the same information. We serve the highest quality information available for local election official contact information and ballot information. There is no way to override this behavior, other than to eliminate non-official sources through the officialSourcesOnly parameter. For polling place information, we always prioritize official data sources over other sources.
  • If we discover data quality issues, we may return no data for a particular electoral district until the issue is resolved.
  • If we don't have data on an address, it doesn't necessarily mean that there is no one registered to vote there. Applications should direct users to their local election officials for complete information.
  • Elections auto expire after their election day. No data will be returned for the election after that point.
  • If you need more quota, please request it from the quotas page on the Developers Console. We try to respond to requests for an increased quota within 24 hours of getting the request.

Status Codes

Calls to voterInfoQuery include a status field that is set to success when an address is accepted. In other cases, an error code will be returned. Common explanations for error codes are given below. Note that information may be returned even if an error code is present.

Status Explanation
success The requested address is recognized by the API as a valid address.
noStreetSegmentFound The API currently has no information about what electoral precinct and/or district this address belongs to. It may be that we are still sourcing/processing new data, or that there are no voters who have registered to vote at this address.
addressUnparseable The requested address is not formatted correctly or cannot be geocoded (i.e. the Google Maps API does not know anything about this address).
noAddressParameter No address was provided.
multipleStreetSegmentsFound The API cannot find information for the specified address, but it has information about nearby addresses. The user should contact their election official for more information.
electionOver The requested election is over. API results for the election are no longer available. Make an electionQuery to find an id for an upcoming election.
electionUnknown The requested election id is invalid. Make an electionQuery to find a valid id.
internalLookupFailure An unspecified error occurred processing the request.