Documentation
API Endpoints
Quickstart
Welcome to the BallotAPI Quickstart! Follow the steps to start exploring the API.
Step 1: Get the ballots for some upcoming elections.
We'll start by getting all of the upcoming elections for a San Francisco location, and include the ballots for these elections. To do this you can make a request to the /elections API endpoint with filters for the coordinates and to also include the ballot measures and races (both of these are called "contests" in our API):
-
coords=37.7942635,-122.395586
- Filter elections to this latitude, longitude of a point in 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.
Command:
curl https://api.ballotapi.org/v1/elections?coords=37.7942635,-122.3955861&dates=now,future&include=contests
Returns:
{ "type": "response", "data": [ { "type": "election", "id": "123-4", "ocd_id": null, "election_type": "..." "election_name": "...", "date": "...", "short_info": "...", "contests": { "type": "response", "data": [ { "type": "contest", "id": "234-5", "ocd_id": null, "election_id": "123-4", "contest_type": "...", "contest_level": "...", "voting_method": "...", "voting_instructions": "...", "title": "...", "question": "...", "choices": [...], }, ... ], "next": null, "extra": {}, "timestamp": "2018-01-01T00:00:00+00:00", "url": "https://api.ballotapi.org/v1/contests?elections=123", }, }, ... ], "next": null, "extra": {}, "timestamp": "2018-01-01T00:00:00+00:00", "url": "https://api.ballotapi.org/v1/elections?coords=37.7942635%2C-122.3955861&dates=now%2Cfuture&include=contests", }
The return format of every request is a Result,
which contains a list of results inside data
(in this case, the results are
Elections objects). Also, since we
added the include=contests
parameter, in each election object, there's a Result
with the Contest for that election.
NOTE: We only offer location lookup via coordinates, so if you have an address, you will need to convert that address into lat/long coordinates (a process called geocoding ). See our geocoding notes for more information.
Step 2: Get a district map.
Next, we'll see where a specific ballot contest will show up on the ballot. To do that we can make a request to the /precincts API endpoint with filters for the contest and to also include a merged area of all the precincts:
-
contests=234-5
- Filter precincts to those that a specific contest covers. -
extra=merge_geos
- Include a merged geometry of the precincts in the results.
Command:
curl https://api.ballotapi.org/v1/precincts?contests=234-5&extra=merge_geos
Returns:
{ "type": "response", "data": [ { "type": "precinct", "id": "345-6", "ocd_id": null, "election_id": "123-4", "voting_info": {...}, "geo": {"type": "Polygon", ...}, }, ... ] "next": "https://api.ballotapi.org/v1/precincts?contests=234-5&extra=merge_geos&after=789-0", "extra": { "merge_geos": { "type": "MultiPolygon", ... }, }, "timestamp": "2018-01-01T00:00:00+00:00", "url": "https://api.ballotapi.org/v1/precincts?contests=234-5&extra=merge_geos", }
This Response contains a list of
Precinct objects. Also, since
we added the extra=merge_geos
parameter, the extra
object in the Result contains a merged geometry of all the precincts in the
results (NOTE: this is not just a merge of the precincts on this page, but
all the precincts for the contest).
Also, notice the next
parameter is not null
. This means
that there are too many precincts in the results and we've split the data list
into multiple pages. The next Result page is at the next url. NOTE: extra
data (e.g. merge_geos
) will always return a result based on the
full results, not just this particular page.
Step 3: Search for a candidate's races.
Finally, we'll search for the recent races that a candidate is in. To do that we can make a request to the /contests API endpoint with with a string search and date range:
-
q=Barbara%20Lee
- Search contests for "Barbara Lee". -
dates=-365d,future
- Limit results to the past year and going forward.
Command:
curl https://api.ballotapi.org/v1/contests?q=Barbara%20Lee&dates=-365d,future
Returns:
{ "type": "response", "data": [ { "type": "contest", "id": "234-5", "ocd_id": null, "election_id": "123-4", "contest_type": "...", "contest_level": "...", "voting_method": "...", "voting_instructions": "...", "title": "...", "question": "...", "choices": [ { "type": "choice", "id": "456-7", "ocd_id": "ocd-person/111...", "title": "Barbara Lee", "party": "Democrat", "info": "..." }, ... ] }, ... ], "next": null, "extra": {}, "timestamp": "2018-01-01T00:00:00+00:00", "url": "https://api.ballotapi.org/v1/contests?q=Barbara%20Lee&dates=-365d%2Cfuture", }
This Response contains a list of Contest objects. Using these results, you can look up election or precinct information on the other API endoints.
Step 4: Check out more examples
Congratulations on finishing the Quickstart! Next, we recommend reading through the examples to see a variety of various other awesome features of the API.