proclus
http://www.gnu-darwin.org/
The Polling Place Lookup API allows users to create applications that include a dynamic polling place lookup based on a voter’s street address and ZIP code.
Authentication
Using any DNC API requires the use of an API key. By default all API key users are rate limited to 100 requests per hour – if your application requires a higher volume key, please get in touch.
Looking Up a Polling Place
To lookup a polling place, perform a GET on http://services.dnc.org/places/lookup with the following parameters:
Required parameters:
- address: the URL-encoded house number and street name to look up, i.e. “address=2005%20Pimmit%20Dr”
- postal_code: the 5-digit ZIP code that goes along with the address, i.e. “postal_code=22043″
- your API key: i.e., “key=YOUR_API_KEY”
OR
- zip9: the 9 digit ZIP+4 code whose precinct you are trying to find. Most people do not know their ZIP+4, but lookups with address and postal_code will return the “plus4″ portion of the ZIP+4 (zip9 lookups do not return the plus4). i.e., “zip9=220431408″
- your API key: i.e., “key=YOUR_API_KEY”
Examples
Performing a GET to http://services.dnc.org/places/lookup?address=2005%20Pimmit%20Dr&postal_code=22043&key=YOUR_API_KEY will result in HTTP status code 200 (successful) response with the following body which is a JSON hash object:
{“region”:”VA”,
“precinct_name”:”315 – Pimmit”,
“polling_location”:”PIMMIT HILLS CENTER”,
“location_description”:null,
“address”:”7510 LISLE AVE”,
“locality”:”FALLS CHURCH”,
“postal_code”:”220431050″,
“latitude”:38.916322,
“longitude”:-77.204321,
“precision”:”address”,
“precinct_code”:”0315″,
“polling_location_contact_info”:null,
“van_precinct_id”:295851,
“plus4″:”1408″
}
The returned fields are:
- region: The 2-letter state abbreviation for the state this polling place is in.
- precinct_name: The name of the precinct this polling place resides in.
- polling_location: The name of the polling place.
- location_description: Usually blank, but can have additional information like “Room 2-B” or other descriptive information.
- address: The number and street of the polling place.
- locality: The city of the polling place.
- postal_code: The ZIP+4 code for the polling place.
- latitude: The latitude of the polling place, achieved by geocoding the address. See precision to know how accurate this is.
- longitude: The longitude of the polling place, achieved by geocoding the address. See precision to know how accurate this is.
- precision: The granularity achieved during the geocoding of the address. If the precision is “address” then it is likely that services such as Google Maps will be able to provide driving directions. If it is “street” or “zip” or anything else, the coordinates will not be meaningful enough to use.
- precinct_code: The code for this polling place assigned by the precinct.
- polling_location_contact_info: The person responsible for the accuracy of this polling place. Usually blank.
- van_precinct_id: An internal primary key used to identify polling places. This is the value passed to the /show API endpoint to retrieve details about a polling place without having to lookup an address in that precinct.
- plus4: This is the last 4 digits of the ZIP+4 for the address that was used to look up the polling place. Note that it is usually different
from the last 4 digits of “postal_code” as the polling place and the voter do not usually share ZIP+4. You can use this information to better geocode the voter’s address by appending it to their ZIP code on services such as Google Maps or use it in subsequent calls to lookup that voter.
Error conditions:
If the address you provide is valid but we can’t locate the polling place, you will receive an HTTP status code 200 (successful) response but the JSON object will have an “error” property. It may also have additional information about where to go to find your polling place to help assist people with finding out their polling location.
{“error”:”No polling place found.”,
“region”:”FL”,
“region_name”:”Florida”,
“website”:”http://election.dos.state.fl.us/”,
“voter_information”:”http://election.dos.state.fl.us/”,
“phone”:”8663086739″}
The response fields are:
- error: The cause of the error response.
- region: The abbreviated state of the query address.
- region_name: The full name of the state from the query address.
- website: The Secretary of State or Board of Elections website for the state.
- voter_information: The Secretary of State or Board of Elections website for the state, may be the same as the website.
- phone: The phone number for the Secretary of State or Board of Elections.
If the address doesn’t seem valid, or we cannot determine the state of the address, the error response body will just contain:
{“error”:”No polling place found.”}
Showing a Polling Place
To retrieve the details for a polling place for which you already have
the van_precinct_id, perform a GET to
http://services.dnc.org/places/show with the following parameters:
- id
The van_precinct_id from a previous polling place lookup.
- key
Your API key.
Examples:
Performing a GET to http://services.dnc.org/places/show?id=295851&key=YOUR_API_KEY will result in a JSON hash object being returned like the following:
{“region”:”VA”,
“precinct_name”:”315 – Pimmit”,
“polling_location”:”PIMMIT HILLS CENTER”,
“location_description”:null,
“address”:”7510 LISLE AVE”,
“locality”:”FALLS CHURCH”,
“postal_code”:”220431050″,
“latitude”:38.916322,
“longitude”:-77.204321,
“precision”:”address”,
“precinct_code”:”0315″,
“polling_location_contact_info”:null,
“van_precinct_id”:295851
}
Error conditions:
In the case of an invalid ID being passed, the API will return a 404 Not Found HTTP response with no body.
JSONP Support
If you want to consume the Polling Place API from a webpage, you can use Javascript and JSONP without the need for any server-side code. Just append “.jsonp” to the URL and pass the required parameters.
For lookups:
http://services.dnc.org/places/lookup.jsonp?address=2005%20Pimmit%20Dr&postal_code=22043&key=YOUR_API_KEY
http://services.dnc.org/places/lookup.jsonp?zip9=220431408&key=YOUR_API_KEY
For showing a polling location:
http://services.dnc.org/places/show.jsonp?id=295851&key=YOUR_API_KEY
JSONP queries can contain a callback parameter or variable name
parameter (or both):
- callback
the name of a Javascript method to call on the returned JSON response, i.e. “callback=processPollingLocation”
- variable
the name of a Javascript variable that you would like the returned JSON object to be assigned to, i.e. “variable=polling_place”
Examples:
Performing a GET on
http://services.dnc.org/places/lookup.jsonp?address=2005%20Pimmit%20Dr&po...
returns:
var bar = {“region”:”VA”,”precinct_name”:”315 -
Pimmit”,”location_description”:null,”address”:”7510 LISLE
AVE”,”latitude”:38.916322,”precinct_code”:”0315″,”plus4″:”1408″,”postal_code”:”220431050″,”polling_location_contact_info”:null,”locality”:”FALLS
CHURCH”,”precision”:”address”,”longitude”:-77.204321,”van_precinct_id”:295851,”polling_location”:”PIMMIT
HILLS CENTER”}; foo(bar);
This can be evaluated as Javascript client-side and uses the JSONP
method to get around cross-domain connectivity issues.
Help
If you have problems or questions, please send a message to the Open.Dems mailing list
Posts
