AgoraPI : The Swiss Army Knife of Voting Systems

We are very excited to present you our latest creation: AgoraPI, a solution to integrate votes and polls on your website or in your software.

What is an API?

An API (Application Programming Interface) is a set of functions that developers create so that other developers can simply use complex tools, methods and algorithms.

The goal is to provide a gateway to a feature by hiding the details of its implementation. The API is therefore a “toolbox” interface that provides services to other softwares. You can use all the functions we have designed, by a simple call to AgoraPI.

 

Why this product?

For the past 2 years, you have been making votes, surveys and polls with our Slack application; with nearly 60,000 users and 35,000 polls, we’ve heard your growing need for quick and simple voting tools. We are fully convinced of the interest that alternative voting systems represent. That is why we have worked tirelessly during the last months to offer you AgoraPI (Agora Polling Interface).

We see endless applications to AgoraPI, but here are a few use cases that we have identified:

 

This list is obviously not exhaustive, your imagination is the only limit and we look forward to seeing what you will achieve with AgoraPI!

It is available for early access starting today. You are all invited to test it, to see if it fits your needs, and to tell us if anything is missing in the guide or the reference. Early access is expected to last until late summer and we will improve our service throughout this transitional period.

We count on you: the more feedback you will give us, the better AgoraPI will be for its official launch!

The Swiss Army Knife of voting systems

When designing AgoraPI, we kept in mind our goal of creating a complete and flexible tool. As a consequence, AgoraPI allows you to use the most sutiable voting system for your poll: the usual majority rule (the choice with the most votes wins) or the Condorcet method (ranked voting leading to a consensual result).

Below is a summary of the main functions offered by AgoraPI:

Authentification

To ensure security and confidentiality, all requests to the API are identified, by means of a token, allowing full access to your data. So make sure your tokens remain secret!

Creation of a poll

By sending a request containing the title and the different choices of the poll, you generate identifiers (PXXX for the poll, CXXX for the choices that are attached to it). These identifiers will allow you to manage all interactions with the poll (voting, adding choices, closing …)

Voting

You have to send a request with the PXXX identifier of the poll and the CXXX’s of the selected choice. It is possible to vote for several choices at the same or at a different preference level (ranked vote), sending the list of desired choices and their respective perference ranks (example: C003 at rank 1, C006 at rank 2, C002 at rank 3)

Displaying results

The results contain the list of choices, sorted by decreasing order of their scores. You can also generate result charts to get crystal clear illustrations of the outcome of the poll.

User managment

If the application that uses AgoraPI has users, the API allows you to associate each vote with a user and to ensure that each user has voted only once.

 

 

Many additional options are available; from insertion / modification of the choices during poll to anonymization of the votes, we have implemented every function which we could think of to customize your poll. Please read the User Guide and the exhaustive reference to learn how to harness the power of AgoraPI in your projects.

And it’s not over! We will soon enlarge the range of available voting systems so that each of your polls is carried out using the most appropriate method.

Use Case example: website Poll Integration

If you’re still here at this point, I have no doubt you’re going to be interested in this example.
This 10 minutes tutorial will show you how to quickly set up a Condorcet voting interface on your website.

Prerequisites:

Open a shell console and start by setting up the API_TOKEN shell variable to your API key value:

API_TOKEN=<MyApiKey>
_

You can check on the validity of your key by sending this simple request:

curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X GET "https://api.open-agora.com/info?api_token=$API_TOKEN"

This should show you the key description that you set up earlier and your used and remaining credits.

You can now create your poll: send the request below after replacing My poll title with your question, and first choice, second choice and third choice with the answers you want to suggest (you can add some others).

curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X POST "https://api.open-agora.com/polls/with-choices?api_token=$API_TOKEN" \
     -d '{"title": "My poll title", "choices": [{"label": "first choice"}, {"label": "second choice"}, {"label": "third choice"}]}'

This request will send you back a JSON content with a P-starting “id” value on the first line:

"id": "PXXXXXXXXX"

Write down this value, you will use it to access the poll you just created in your browser.
You are now ready to integrate the poll in your website.

You have to download and unzip these files: poll_example_FILES.zip

Then, edit api.ini in the OA folder, and replace <MyApiKey> with your API key value.

[client]
base_url = https://api.open-agora.com
token =<MyApiKey>

Save api.ini and upload all the files in the folder or server of your choice (keep api.ini and CurlClient.php in the OA folder).
If you want to test locally, just launch a PHP server from your console (you must be in the root folder of the files):

php -S localhost:8888

And here we are ! You can access the vote_index.php via your browser. You have to pass the Poll_id you wrote down earlier in parameter of the URL:
either http://your.domain.url/vote_index.php?id=Poll_id if it is on your online server or localhost:8888/vote_index.php?id=Poll_id if you are running it locally. People who access this page will be able to vote without restriction and to see the current state of the votes.

Do not hesitate to comment on this article and give us feedback on your experience with AgoraPI, we would be delighted to share about it with you.

Tweet about this on TwitterShare on LinkedInShare on Google+Share on Facebook

Leave a Reply

Your email address will not be published. Required fields are marked *