Practical guide

This guide is intended for prospective and current API customers of Ballotpedia. We want to make it easy for you to understand and use the data we provide in our API; this document gives concrete examples for some real-world applications you might want to build using the API.

Sample Ballot Application

Suppose you want to provide a sample ballot lookup on your website. This can be accomplished by the following steps:

Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates.
With the user's lat/long, query the /election_dates endpoint.
With the user's lat/long and chosen election date, pass these parameters to the /elections_by_point endpoint.
Finally, display the results. Exactly how to do this is up to you, but now you have all the data you need to do it. You can loop over the districts, races, and candidates and display their names, party affiliations, link to their Ballotpedia profile, status, and much more.

Click here to view Ballotpedia's Sample Ballot Tool

Current Representatives Application

Suppose you want to allow users to look up their current elected officials. This can be accomplished by the following steps:

Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates.
Fetch the elected officials for the user’s location. Supply the latitude/longitude coordinates from the previous step into the /officeholders endpoint.
Display the results. This part is up to you, but now you have all the data you need to do it. You can loop over the districts, offices, and officeholders and display their names, party affiliations, link to their Ballotpedia profile, contact information, and much more.

Previous/elections_by_state NextDownloading bulk data via the client portal

Last updated 19 days ago

Sample Ballot Application

Suppose you want to provide a sample ballot lookup on your website. This can be accomplished by the following steps:

Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates.

With the user's lat/long, query the /election_dates endpoint.

With the user's lat/long and chosen election date, pass these parameters to the /elections_by_point endpoint.

Finally, display the results. Exactly how to do this is up to you, but now you have all the data you need to do it. You can loop over the districts, races, and candidates and display their names, party affiliations, link to their Ballotpedia profile, status, and much more.

Current Representatives Application

Suppose you want to allow users to look up their current elected officials. This can be accomplished by the following steps:

Fetch the elected officials for the user’s location. Supply the latitude/longitude coordinates from the previous step into the /officeholders endpoint.

Display the results. This part is up to you, but now you have all the data you need to do it. You can loop over the districts, offices, and officeholders and display their names, party affiliations, link to their Ballotpedia profile, contact information, and much more.