Civic Info API Frequently Asked Questions
Last updated: Sep 2016
Frequently Asked Questions and Answers: 2
Q: When will API data be available for the General Election? 2
Q: Will the API provide early vote locations for a given address, or only day of election polling place? If so, would the API return all eligible early vote locations, or only the nearest one? 2
Q: Will “EarlyVotingSites” return both early voting locations and absentee in person locations? 2
Q: Who is currently using the Civic Info API? 2
Q: Is there a quota limits for the Civic Info API? If so, what is the quota. 3
Q: Is there any easy way to try querying the API? 3
Q: Is there a published matrix that shows a mapping between the OCDID search parameter (e.g. country/state/place/cd) and the politician title that falls under (e.g. State Legislative District Upper/sldu equates to State Senate)? 3
Q: Does the API support divisions endpoint search by address? 3
Q: How should I format the OCDID string for the Division search and Representative by Division search? 4
Q: For the elected representatives, there is a list of elected officials and a list of offices. Are they linked together? If so, how? 4
Q: Is the API still supported? Why am I only seeing a few elections available? 5
Q: Does the API provide geocoded coordinates? 5
Google’s Civic Information API (https://developers.google.com/civic-information/) allows developers to build applications that display civic information to their users. For any U.S. residential address, you can look up who represents that address at each elected level of government. During supported elections, you can also look up polling places, early vote location, candidate data, and other election official information.
Our data is based on the political geography of a citizen’s address. There are many U.S. elections throughout the year, election information and the political geography can shift with time. Google assigns a unique election ID for each election and ensures that information associated with a specific ID is accurate for that election.
Query for available elections or voting information by address
Query for elected officials (and/or political geography).
Query for a political geography by name or OCDID
Query explorer:
You can click on any of the available services listed below to try it - e.g. voterInfoQuery
A: The availability of API data may varies by state, and you can find the latest availability on Civic Info API Developer site under "GUIDES => Data Guidelines => Data Availability" (click on this link to view it directly). The chart has details on (roughly) when data will be available for a specific state with regard to Polling location, Early Voting, Ballot, and/or Election Admin info.
A: The API will return early vote locations, and will return all that we can determine are eligible for a voter. We often don't have this information available at the onset of early voting in a state, but try to get it out there as soon as we can.
A: Early vote locations returned in the API correspond to early vote locations where anyone registered to vote at the queried address is eligible to vote early, without an excuse. The actual term used in a state may vary for the these locations.
Civic Info API is free for users who access this information, including third parties who develop apps that provide civic information on their site.
http://gettothepolls.com
A: By default, developers are allowed to make 25,000 requests per day, 2500 requests per 100 seconds and 100 requests per 100 seconds per user. If you need additional quota, please use the Quotas page in the Developers Console for your project to make a request.
A: You can use the “Try it now” link from the developer forum to query the specific data source.
For voter information query, click on Try it now!, input required parameter(s) highlighted in red, and click on the “Execute” button at the bottom. Please see below the “Try it now” query for other functions:
Election Query: link
Representative search - by Address: Try it now!; Representative search - by Division: link
OCD ID(Open Civic Data Identifiers) are predictable and globally unique identifiers to political divisions. It is a standard that can help reconcile civic data from a disparate group of data providers.
The latest master list of OCDIDs in the US can be found on github https://github.com/opencivicdata/ocd-division-ids/blob/master/identifiers/country-us/README.md
A: There is not but you should be able to look at the OCDID repository to see the OCDID and the corresponding district name. https://github.com/opencivicdata/ocd-division-ids/tree/master/identifiers/country-us/census_autogenerated
OCDIDs with the ‘cd:’ prefix are for congressional districts, which map to members of congress. ‘sldu:’ stands for State Legislative District Upper and is therefore equivalent to State Senate (though, in states with multi-member districts, state representatives will be returned with the legislatorLowerBody role). ‘sldl:’ stands for State Legislative District Lower and is therefore equivalent to State House/Assembly. The higher level, ‘state:’ will contain state-level officials like Senators and Governors.
A: Yes. You can use an address in the representativesByAddress query. It works well, with support for lower-level districts for residential addresses. For business addresses, you'll typically only get congressional districts, county, and some cities. You probably wouldn't get state leg districts.
You can specify a lat/lng as well, but accuracy for reverse geocoding will be lower. Also, I'd expect this to perform closer to the business address case where the congressional, county, and some cities are returned.
A:
Division search - you can search any part of the ocdid with “:” escaped (e.g. "country\:us/state\:md/county\:montgomery" or "ocd-division/country\:us/state\:md/county\:montgomery")
Representative by Division search - use the full ocd value and no need to escaping special characters
(e.g. “ocd-division/country:us/state:md/county:montgomery”)
A: Yes, each office object has an ‘officialindices’ array, which links that office to one or more elected officials, based on their ordering in the “officials” array. E.g.
"offices": [
{
"name": "President of the United States",
"divisionId": "ocd-division/country:us",
"levels": [
"country"
],
"roles": [
"headOfState",
"headOfGovernment"
],
"officialIndices": [
0
]
},
...
]
And this indicates that Officials with officialindex [0] in the “officials” object are US President
"officials": [
{
"name": "Barack Obama",
"address": [
{
"line1": "The White House",
"line2": "1600 pennsylvania avenue nw",
"city": "washington",
"state": "DC",
"zip": "20500"
}
],
"party": "Democratic",
"phones": [
"(202) 456-1111"
],
"urls": [
"http://www.whitehouse.gov/"
],
"photoUrl": "http://www.whitehouse.gov/sites/default/files/imagecache/admin_official_lowres/administration-official/ao_image/president_official_portrait_hires.jpg",
"channels": [
{
"type": "GooglePlus",
"id": "+whitehouse"
},
{
"type": "Facebook",
"id": "whitehouse"
},
{
"type": "Twitter",
"id": "whitehouse"
},
{
"type": "YouTube",
"id": "barackobama"
}
]
},
]
Yes, it is! However, for elections that are not nationwide we rely solely on official data published by states and local governments through the Voting Information Project. This means that not every upcoming general, primary or local election will have data available, though quite a few will (or have).
For elections we do cover, including the general elections in November, data is generally only available relatively close to the election day (ideally 4-6 weeks before, but depending on the state that is publishing the data it can be closer). For this year’s general election, you can find the API data availability in this chart. You can also find test data for development purposes in the test election (election ID 2000).
No. You can use the Google Maps API if you require coordinates. Note that Maps API quota is managed separately from Civic Information API quota.