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.

All API calls return JSON data.

Specifying your API Key

You must provide your API key that you can find on your account page. You can specify your API key in a header:

curl -H "x-api-key: <key>" "https://www.opavote.com/api/v0/me"

or as a URL parameter:

curl "https://www.opavote.com/api/v0/me?key=<key>"

All Items (Elections, Polls, and Counts)

GET /api/v0/me

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

Returns a list of your items.

GET /api/v0/items/<eid>

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>

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

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:

  • 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 "x-api-key: <key>" -H "Content-Type: application/json" -d '{"method":"ERS97 STV","blt":"2 1\n1 1 0\n0\n\"A\"\n\"B\"\n\"title\"\n"}' https://www.opavote.com/api/v0/counts