NationBuilder Election Center

API Documentation

NationBuilder Election Center offers a RESTful API that you can use to build great apps for political campaigns. The API offers access to NationBuilder's world-class database of voter data, political and geographic region boundaries, and information about the campaigns using your app.

To ask questions and share tips about using the Election Center API, join our Developer Group. This is BETA, and we're just getting started, so please get involved. Share your ideas, tell us what API calls you want, show off your apps, etc.

Basic concepts

The big challenge in making an open voter file work is balancing the need to make sure the data is only used for political purposes, while making sure that citizen privacy and contact preferences are respected, without making it difficult for developers to build things. What we came up with is very similar to how Facebook and Twitter work. Election Center applications can request authorization from a campaign for access to the voter data they have been approved for. Apps can then access the API as if they are that campaign. But you can't build an app without access to some voter data to test it out! So that's why you get access to a sandbox account - a fake campaign with fake data that developers can use while their app is in development mode.

Authentication

The NBEC API currently supports OAuth 1.0 and cookie-based access through the browser. In order to access the API, you will need to register a new application. Once you have done this, you will receive a Consumer Key and Consumer Secret, and information about three end-points that you must implement:

  • Request Token URL
    http://yourapp.com/oauth/request_token
  • Access Token URL
    http://yourapp.com/oauth/access_token
  • Authorize URL
    http://yourapp.com/oauth/authorize

For more information about implementing OAuth 1.0, see the following resources:

You may also use the client interactively through the browser using the examples below. Every logged-in developer can also automatically access data as a sandboxed "Campaign User", a fake user with access to anonymized real-world voter data for any district in the USA.

Candidate Information

Use the Candidate API to retrieve information about the logged-in candidate user. You can use this to customise your app's user experience to the type of office they're running for, or the regions that they're running in.

Current Candidate

JSON hash of information about the current candidate user

/api/v1/candidate/current

Parameters: None

Try it

You must be registered and signed in to try the API.

Voters

Using the Voters API, you can find individual voters or download a CSV of all voters accessible to the logged-in candidate.

Voter Match

Returns the top-matched voter for a set of criteria. You must supply the state and at least one other parameter. This can be called by the app at any time, without a candidate user authorizing via oauth.

/api/v1/voters/match

Parameters:

NameDescription
state State code (CA, KY, etc) (required)
first_name First Name
last_name Last Name
residential_zip4 Zip4 of residential address
residential_zip5 Zip5 of residential address
home_phone Home phone number, including area code

Try it

You must be registered and signed in to try the API.

Voter Download

Returns CSV data of all the voters the candidate has access to. The schema of the CSV file is published here.

/api/v1/voters/download

Parameters: None

Try it

You must be registered and signed in to try the API.

Regions

Using the Regions API, you can retrieve a list of political and geographic districts corresponding to a given lat/long, retrieve boundary data as GeoJSON and even retrieve scaled boundary data suitable for tiling using Google Maps, Polymaps or Leaflet. Districts are all from the redistricting based on the 2010 census.

Region Search

Returns regions of all types which overlap with a given lat/lng. If just passed state (optional), it returns all known regions for the state. State is ignored if you pass the lat and lng.

/api/v1/regions

Parameters:

NameDescription
state State
lat Latitude
lng Longitude

Try it

Region Shape Definition

Returns the shape of the specified region

/api/v1/regions/:state/:region_type/:region_name

Parameters:

NameDescription
state State
region_type Region Type
region_name Region Name

Try it

You must be registered and signed in to try the API.

Region Tile Search

Returns the regions within a specified bounding box

/api/v1/regions/tile

Parameters:

NameDescription
coords Coordinates (Southern Latitude, Western Longitude, Northern Latitude, Eastern Longitude)
region_type Region Type

Try it

You must be registered and signed in to try the API.