--- layout: docs title: Docs - Examples nav: docs toc: 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
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.
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.
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.