--- layout: docs title: Docs - Quickstart nav: docs toc: quickstart ---
Welcome to the BallotAPI Quickstart! Follow the steps to start exploring the API.
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.
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.
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", "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.
Congratulations on finishing the Quickstart! Next, we recommend reading through the examples to see a variety of various other awesome features of the API.