已通过 Google 文档发布
Civic Info API FAQs
每 5 分钟自动更新一次

Civic Info API Frequently Asked Questions

Last updated: Sep 2016

Overview        1

Resource types and methods        2

Elections        2

Representatives        2

Divisions        2

Useful links:        2

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: What are OCDIDs?        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

Overview

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.

Resource types and methods

Elections

Query for available elections or voting information by address

Representatives

Query for elected officials (and/or political geography).

Divisions

Query for a political geography by name or OCDID

Useful links:

Query explorer:

Civic Info API explorer

You can click on any of the available services listed below to try it - e.g. voterInfoQuery 

Frequently Asked Questions and Answers:

Q: When will API data be available for the General Election?

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.

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?

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.

Q: Will “EarlyVotingSites” return both early voting locations and absentee in person locations?

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.

Q: Who is currently using the Civic Info API?

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

http://myreps.datamade.us

Q: Is there a quota limits for the Civic Info API? If so, what is the quota.

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.

Q: Is there any easy way to try querying the API?

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

Q: What are OCDIDs?

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

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)?

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.

Q: Does the API support divisions endpoint search by address?

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.

Q: How should I format the OCDID string for the Division search and Representative by Division search?

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”)

Q: For the elected representatives, there is a list of elected officials and a list of offices. Are they linked together? If so, how?

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"

    }

   ]

  },

]

Q: Is the API still supported? Why am I only seeing a few elections available?

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).

Q: Does the API provide geocoded coordinates?

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.