Page Summary
-
Applications using the Google Civic Information API must identify themselves with an API key included in each request.
-
There are two types of credentials supported: OAuth 2.0 for private user data requests and API keys for requests that do not require OAuth 2.0.
-
API keys should be restricted to prevent unauthorized usage, with restrictions varying based on the application type (web, backend, Android, iOS).
-
The API provides methods like electionQuery to get election IDs and voterInfoQuery to get voter information based on address and election ID.
This document describes what you need to know to use the Google Civic Information API. You can look at this Civic Info API FAQ that has some basic info about the API as well as frequently asked questions from our user forum. Additionally, you can see examples below for looking up voter information during an election.
Identifying your application to Google
Your application needs to identify itself every time it sends a request to the Google Civic Information API, by including an API key with each request.
Acquiring and using an API key
To acquire an API key:
- Open the Credentials page in the API Console.
- This API supports two types of credentials.
Create whichever credentials are appropriate for your project:
-
OAuth 2.0: Whenever your application requests private user data, it must send an OAuth 2.0 token along with the request. Your application first sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.
Note: Since this API doesn't have any methods that require OAuth 2.0 authorization, you might only need to obtain API keys , which are described below. However, if your application calls other APIs that require user authorization, then you still need OAuth 2.0 credentials.
For more information, see the OAuth 2.0 documentation .
-
API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.
The API supports several types of restrictions on API keys. If the API key that you need doesn't already exist, then create an API key in the Console by clicking Create credentials > API key . You can restrict the key before using it in production by clicking Restrict key and selecting one of the Restrictions .
-
To keep your API keys secure, follow the best practices for securely using API keys .
After you have an API key, your application can append the query parameter key= yourAPIKey
to all request URLs.
The API key is safe for embedding in URLs; it doesn't need any encoding.
API key restrictions
Your API key is unrestricted by default, which is insecure if anyone can either read this key (if placed within a browser, for example) or access the device on which the key is placed. We recommend you place a restriction on this API key to inhibit unauthorized usage.
To add a restriction, click on Restrict keywithin the API key createddialog box. The API keyconfiguration panel will appear:
The type of restriction you select will depend on your application needs:
- Web applications interacting directly with the API (that is, not through any backend or middleware) should add an HTTP referrersrestriction. Note, however, that such applications will expose their API key publicly; prefer using a service account auth scheme instead.
- Backend applications that cannot otherwise support service accounts (for example, embedded devices that do not have a supported language in the client library) should add an IP addressesrestriction to guard against usage from clients at different IP addresses.
- Android applications should add an Android appsrestriction and add your package name and SHA-1 signing-certificate fingerprint.
- iOS applications should add an iOS appsrestriction and add any iOS bundle identifiers to restrict API calls to these iOS bundles.
For testing, you might not want to place any restriction at all. However, it is recommended that you either add a restriction to this key or delete it once you deploy your application to production.
electionQuery example
Here's an example (using API version 'v2') of calling the electionQuery API to obtain a list of valid election IDs, then using the voterInfoQuery API with a voter's registered address to obtain information for a selected election.
Use electionQuery to get a list of valid election Ids:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
electionQuery Response:
{
"kind": "civicinfo#electionsqueryresponse",
"elections": [
{
"id": "2000",
"name": "VIP Test Election",
"electionDay": "2013-06-06"
},
{
"id": "2124",
"name": "Rhode Island 2012 Primary Election",
"electionDay": "2012-09-11"
},
{
"id": "2126",
"name": "Delaware 2012 Primary Election",
"electionDay": "2012-09-11"
}
]
}
voterInfoQuery using curl
Use curl
to send a voterInfoQuery
request for VIP test election ID 2000 and voter at (test) address 340 Main St, Venice, CA 90291.
You can refer to voterInfoQuery response
.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
voterInfoQuery using the Google API Client Library for JavaScript
This example issues the same voterInfoQuery as the previous curl example, but it uses the JavaScript client library . The voterInfoQuery response is the same as the curl example response.
< ! doctype html > < html > < head > < script > /** * Build and execute request to look up voter info for provided address . * @ param { string } address Address for which to fetch voter info . * @ param { function ( Object )} callback Function which takes the * response object as a parameter . */ function lookup ( address , callback ) { /** * Election ID for which to fetch voter info . * @ type { number } */ var electionId = 2000 ; /** * Request object for given parameters . * @ type { gapi . client . HttpRequest } */ var req = gapi . client . request ({ 'path' : '/civicinfo/v2/voterinfo' , 'params' : { 'electionId' : electionId , 'address' : address } }); req . execute ( callback ); } /** * Render results in the DOM . * @ param { Object } response Response object returned by the API . * @ param { Object } rawResponse Raw response from the API . */ function renderResults ( response , rawResponse ) { var el = document . getElementById ( 'results' ); if ( ! response || response . error ) { el . appendChild ( document . createTextNode ( 'Error while trying to fetch polling place' )); return ; } var normalizedAddress = response . normalizedInput . line1 + ' ' + response . normalizedInput . city + ', ' + response . normalizedInput . state + ' ' + response . normalizedInput . zip ; if ( response . pollingLocations . length > 0 ) { var pollingLocation = response . pollingLocations [ 0 ] . address ; var pollingAddress = pollingLocation . locationName + ', ' + pollingLocation . line1 + ' ' + pollingLocation . city + ', ' + pollingLocation . state + ' ' + pollingLocation . zip ; var normEl = document . createElement ( 'strong' ); normEl . appendChild ( document . createTextNode ( 'Polling place for ' + normalizedAddress + ': ' )); el . appendChild ( normEl ); el . appendChild ( document . createTextNode ( pollingAddress )); } else { el . appendChild ( document . createTextNode ( 'Could not find polling place for ' + normalizedAddress )); } } /** * Initialize the API client and make a request . */ function load () { gapi . client . setApiKey ( 'YOUR API KEY GOES HERE' ); lookup ( '1263 Pacific Ave. Kansas City KS' , renderResults ); } < / script > < script src = "https://apis.google.com/js/client.js?onload=load" >< / script > < / head > < body > < div id = "results" >< / div > < / body > < / html >
voterInfoQuery response
{ "kind" : "civicinfo#voterinforesponse" , "status" : "success" , "election" : { "id" : "2000" , "name" : "VIP Test Election" , "electionDay" : "2025-06-06" , "ocdDivisionId" : "ocd-division/country:us" }, "normalizedInput" : { "line1" : "340 Main Street" , "city" : "Venice" , "state" : "CA" , "zip" : "90291" }, "pollingLocations" : [ { "address" : { "locationName" : "WESTMINSTER AVENUE ELEMENTARY SCHOOL" , "line1" : "1010 ABBOT KINNEY BLVD" , "city" : "VENICE" , "state" : "CA" , "zip" : "90291" }, "pollingHours" : "" , "latitude" : 33.9919351 , "longitude" : - 118.4722031 , "startDate" : "2024-03-05" , "endDate" : "2024-03-05" , "sources" : [ { "name" : "Voting Information Project" , "official" : true } ] }, { "address" : { "locationName" : "POP UP VOTE CENTER 5" , "line1" : "12400 IMPERIAL HWY" , "city" : "NORWALK" , "state" : "CA" , "zip" : "90650" }, "latitude" : 33.915989 , "longitude" : - 118.0677283 , "sources" : [ { "name" : "Voting Information Project" , "official" : true } ] } ], "dropOffLocations" : [ { "address" : { "locationName" : "FLEX VOTE CENTER 9" , "line1" : "12400 IMPERIAL HWY" , "city" : "NORWALK" , "state" : "CA" , "zip" : "90650" }, "latitude" : 33.915989 , "longitude" : - 118.0677283 , "sources" : [ { "name" : "Voting Information Project" , "official" : true } ] }, ], "contests" : [ { "type" : "General" , "ballotTitle" : "UNITED STATES REPRESENTATIVE, 36th District" , "district" : { "name" : "36TH US CONGRESSIONAL" , "scope" : "congressional" }, "numberElected" : "1" , "numberVotingFor" : "1" , "ballotPlacement" : "103" , "sources" : [ { "name" : "Voting Information Project" , "official" : true } ], "candidates" : [ { "name" : "ARIANA HAKAMI" , "party" : "Party Preference: Republican" }, { "name" : "CLAIRE RAGGE ANDERSON" , "party" : "Party Preference: None" }, { "name" : "MELISSA TOOMIM" , "party" : "Party Preference: Republican" }, { "name" : "TED W. LIEU" , "party" : "Party Preference: Democratic" } ] }, { "type" : "ballot-measure" , "ballotTitle" : "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA" , "district" : { "name" : "CITY OF LOS ANGELES" , "scope" : "citywide" }, "ballotPlacement" : "116" , "referendumTitle" : "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA" , "referendumText" : "CITY MOBILITY PLAN STREET IMPROVEMENT MEASURES. INITIATIVE ORDINANCE HLA. Shall an ordinance providing that when the City of Los Angeles makes a qualifying improvement to a City-owned street (e.g., a paving project), the City must also install certain street enhancements described in the City's Mobility Plan network of pedestrian, bicycle, transit, and vehicle routes; and requiring the City to provide publicly accessible information regarding street improvements; be adopted?" , "referendumPassageThreshold" : "MAJORITY OF VOTES CAST" , "referendumBallotResponses" : [ "YES" , "NO" ], "sources" : [ { "name" : "Voting Information Project" , "official" : true } ] }, { "type" : "General" , "ballotTitle" : "DISTRICT ATTORNEY" , "district" : { "name" : "LOS ANGELES COUNTY" , "scope" : "countywide" }, "numberElected" : "1" , "numberVotingFor" : "1" , "ballotPlacement" : "129" , "sources" : [ { "name" : "Voting Information Project" , "official" : true } ], "candidates" : [ { "name" : "GEORGE GASCÓN" }, { "name" : "JONATHAN HATAMI" }, { "name" : "NATHAN HOCHMAN" }, { "name" : "DEBRA ARCHULETA" }, { "name" : "JEFF CHEMERINSKY" }, { "name" : "ERIC SIDDALL" }, { "name" : "MARIA RAMIREZ" }, { "name" : "DAN KAPELOVITZ" }, { "name" : "LLOYD \"BOBCAT\" MASSON" }, { "name" : "JOHN MCKINNEY" }, { "name" : "CRAIG J. MITCHELL" }, { "name" : "DAVID S. MILTON" } ] } ], "state" : [ { "name" : "California" , "electionAdministrationBody" : { "name" : "Secretary of State" , "electionInfoUrl" : "https://www.sos.ca.gov/elections/" , "electionRegistrationUrl" : "https://registertovote.ca.gov/?t=s" , "electionRegistrationConfirmationUrl" : "https://voterstatus.sos.ca.gov" , "absenteeVotingInfoUrl" : "https://elections.cdn.sos.ca.gov/vote-by-mail/replacement-application.pdf" , "votingLocationFinderUrl" : "https://voterstatus.sos.ca.gov" , "ballotInfoUrl" : "https://www.sos.ca.gov/elections/ballot-status/wheres-my-ballot/" , "correspondenceAddress" : { "line1" : "1500 11th Street, 5th Floor" , "city" : "Sacramento" , "state" : "California" , "zip" : "95814" } }, "local_jurisdiction" : { "name" : "Los Angeles" , "electionAdministrationBody" : { "name" : "Registrar-Recorder/County Clerk" , "electionInfoUrl" : "http://www.lavote.gov/" , "electionRegistrationUrl" : "http://registertovote.ca.gov/" , "electionRegistrationConfirmationUrl" : "https://lavote.gov/vrstatus/" , "absenteeVotingInfoUrl" : "" , "ballotInfoUrl" : "http://www.lavote.gov/Locator" , "physicalAddress" : { "locationName" : "Registrar-Recorder/County Clerk" , "line1" : "12400 Imperial Highway" , "city" : "Norwalk" , "state" : "CA" , "zip" : "90650" } }, "sources" : [ { "name" : "Voting Information Project" , "official" : true } ] } } ] }
