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 such as 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

Developer Guidelines

We require all developers to adhere to the following guidelines:

  • Adhere to the APIs terms of service.
  • By using the API, developers agree to obey any cache-control headers if there is one. Absent of cache-control headers, developers agree to not cache for more than 24 hours for voting locations and contest information and more than 30 days for office holders and districts.
  • Developers using the API should make every effort to ensure all users are met with the same experience. We don't allow holdbacks, A/B testing, or similar experiments.

  • If you need additional quota to enable your use case, you can request a per-project increase in your Developer Console. Provisioning of additional quota is limited and is subject to a maximum allowance.

    Note: The approval process takes 1-2 months.Plan your quota increase requests accordingly. To prepare for 2024 presidential election quota increases,submit quota requests by August.

  • Additional quota for the Civic Info API is only intended to support user-facing use cases. Quota increase requests are not granted for other use cases.

Additional Data 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.

Attribution

Attribution to the Civic Information API is optional. If a developer chooses to attribute to the Civic Information API and to link users to more information on the Civic Information API, we require developers to use one of the following attribution language options and webpage linked below:

  • “Powered by the Civic Information API”
  • “Voting information powered by the Civic Information API”
  • “Ballot information powered by the Civic Information API”
  • “Representative information powered by the Civic Information API”
  • “Learn more”

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.