API Reference

Developers Guide v2

This guide shows developers how to use the endpoints of the Elections API v2 to retrieve the election information necessary to construct election ballots.

Follow the below steps to get started creating ballots for elections using the mySidewalk Elections API v2.
Click the links to the endpoint documentation in each section for more information.

1. Search for an Election

To see what upcoming elections are available in a state...

Create a GET request for the Elections endpoint. Try the online API tester.

For example:

curl "https://elections.mysidewalk.com/api/election/v2/elections?state=CA" \
  -H "Authorization: Token your_token"

This request returns a JSON formatted list of elections.

2. Get Ballots

The Ballots endpoint is the one stop shop for all election information necessary to create a ballot.

There are two ways to retrieve ballots from the ballot endpoint.

  • To get a ballot for a specific election and coordinate...

    Create a GET request for the Ballots using the election id from Step 1 and a latitude and longitude. Try the online API tester.

    For example:

curl "https://elections.mysidewalk.com/api/election/v2/ballots?latitude=${latitude}&longitude=${longitude}&election=${election_id}" \
  -H "Authorization: Token your_token"

  • To get all ballots for a specific coordinate (within the next 60 day window)...

    SKIP Step 1

    Create a GET request for the Ballots using a latitude and longitude. Try the online API tester.

curl "https://elections.mysidewalk.com/api/election/v2/ballots?latitude=${latitude}&longitude=${longitude}" \
  -H "Authorization: Token your_token"

Both requests return a JSON formatted list of Ballot objects and all related Election, Party, Referendum, and Candidates objects.

📘

Try our JSONAPI Parser

To parse the flattened JSON Ballot objects (or any Election object) use our JSONAPI parser https://github.com/mysidewalk/jsonapi-parse.

3. Construct the Ballot for a Voter

To construct a ballot for a voter...

  1. Filter out all contests that have a party that is not the voter's party.

📘

All related Party objects are included in the Ballot object linked field.
Simply search for the party with the same name as the voter's party.

  1. For the remaining contests that are partisan, partisan field is true, display only candidates that match the voter's party.

Terms of Use

By accessing or using the mySidewalk Elections API without a more specific licensing agreement, you accept and agree to be bound by the following terms and conditions. It is important that you read these Terms as they form a legal agreement between you and mySidewalk, Inc. If you do not have authority, or if you do not agree with the terms of this API Agreement, do not access or use the API.

For more information about how to license the mySidewalk Elections API and how to receive an access token, please contact [email protected].