1. Documentation
  2. Quickstart

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):

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.

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:

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:

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.