Documentation
API Endpoints
Examples
There's a ton of use cases for BallotAPI, but sometimes it's not obvious what API request you want to make to get the data you need. The Quickstart provides some of the most common use cases, and below we'll list more common examples submitted to us. To see the full list of what endpoints are available and what query parameters you can use, checkout the API Endpoints documentation.
Can't find an example for your use case? We encourage you to open an issue or pull request
Example: Get the ballots for some upcoming elections
Here's an example for getting all of the upcoming elections for a specific location, and include the ballots for these elections.
API request:
Parameters breakdown:
-
coords=37.7942635,-122.395586- Filter elections to this latitude, longitude of a location (e.g. downtown San Francisco). -
dates=now,future- Filter elections happening between now and any future date. -
include=contests- Include the ballot measures and races for each election.
Example: Get a district map
Here's an example to see where a specific ballot contest will show up on the ballot.
API request:
https://api.ballotapi.com/v1/precincts?contests=234-5&extra=merge_geos
Parameters breakdown:
-
contests=234-5- Filter precincts to those that cover a specific contest (e.g. 2016 San Francisco Mayor, id=234-5). -
extra=merge_geos- Include a merged geometry of the precincts in the results.
Example: Search for a candidate's races
Here's an example to search for the recent races that a candidate is in.
API request:
https://api.ballotapi.com/v1/contests?q=Barbara%20Lee&dates=-365d,future
Parameters breakdown:
-
q=Barbara%20Lee- Search contests for an string (e.g. "Barbara Lee"). -
dates=-365d,future- Limit results to the past year and going forward.
Can't find an example for your use case? We encourage you to open an issue or pull request
Want to see the full list of available endpoints? Checkout the API Endpoints documentation.