OpaVote API

This is a preview of a forthcoming API, and we may make backwards incompatible changes to v0. When we launch v1 of the API, we will not make any backwards incompatible changes unless we bump up the version number.

OpaVote has an API so that you can call OpaVote from your own servers. Below are the currently supported API calls, and we will be adding functionality over time. Let us know if you would like to see any specific API calls.

You need to use your secret key with these API calls, and you can find your secret key on your account page. All API calls return JSON data.

All Items (Elections, Polls, and Counts)

GET /api/v0/me?key=<key>

This is simple sanity check to make sure that your secret key is working and returns your name and email address.

GET /api/v0/items?key=<key>

Returns a list of your items.

GET /api/v0/items/<eid>?key=<key>

Returns information about an item. The <eid> is a unique identifier of your item as returned by the previous API call. This is also the same identifier that you see in the URL of your management and voting pages.

GET /api/v0/items/<eid>/blt/<cid>?key=<key>

Returns ballots of an item. For Elections and Polls, <cid> is a 0-based integer corresponding to your contests (e.g., if you have 3 contests, then <cid> is 0, 1, or 2. For a Count, <cid> is always 0.

GET /api/v0/items/<eid>/n-votes?key=<key>

Returns the number of votes received. Although this works for all items, it is really meant for Elections and Polls to allow you to track the number of votes received.

Counts

POST /api/v0/counts

Create a Count. The POST must include the following arguments in JSON format:

  • key (your secret key)
  • method (any of OpaVote's counting methods)
  • blt (your ballots in the BLT format encoded as UTF-8)

The POST will return information about your newly created Count including its <eid>. Here is a example call using cURL:

curl -X POST -H "Content-Type: application/json" -d '{"key":"<key>","method":"ERS97 STV","blt":"2 1\n1 1 0\n0\n\"A\"\n\"B\"\n\"title\"\n"}' https://www.opavote.com/api/v0/counts