Simple app for ranked-choice voting in an election.

Ranked-voting is a Flask app that serves API endpoints for a ranked-choice voting, supporting both creation of elections, retrieval of results and casting of votes using HTTP requests.

How to use ranked-voting

Create an Election

Creation of elections is performed by sending either a GET or POST request.


A GET request is the quickest way to setup a ranked-choice election, but offers no customization options since all fields take their default values. Create an election by appending a / separated list of candidates to the /add endpoint.

curl --location --request GET 'https://ranked-voter.herokuapp.com/add/pancakes/waffles/ice-cream'


You can also create an election by sending a POST request. This is the most flexible way to create an election, but requires you to specify the fields you wish to customize.

The request body is a JSON object with the following fields:

    "election_id": {OPTIONAL} A custom ID for the election. If not provided, a random ID will be generated.
    "election_name": {OPTIONAL} The name of your election
    "start_time": {OPTIONAL} when does the election start?
    "end_time": {OPTIONAL} when does the election end?
    "description": {OPTIONAL} A short description of your election
    "anonymous": {OPTIONAL} true or false
    "candidates": ["candidate-1", "candidate-2", ...]

An example is provided below:

curl --location --request POST 'https://ranked-voter.herokuapp.com/add' \
--header 'Content-Type: application/json' \
--data-raw '{
    "election_name": "Food ranking",
    "description": "Rank your favourite foods!",
    "candidates": ["pancakes", "ice-cream", "waffles"],
    "anonymous": true

Once you create an election, you will be shown the ELECTION_ID. Remember to use this ID when casting your votes and to access results.

Retrieve Results

You can view your election results by sending a GET request to the /ELECTION_ID endpoint.

An example is provided below:

curl --location --request GET 'https://ranked-voter.herokuapp.com/ELECTION_ID'

Remove an Election

You can remove an election by sending a GET request to the /vote/ELECTION_ID endpoint. Note that this action is irreversible and can only be performed by the person who created the election.

curl --location --request GET 'https://ranked-voter.herokuapp.com/remove/ELECTION_ID'

Cast your votes

You can cast your votes by sending a GET request to the vote/ELECTION_ID endpoint. Append the URL with the ordered candidates, separated with a /. Remember to include all the candidates since this is a ranked-choice voting.

An example is provided below:

curl --location --request GET 'https://ranked-voter.herokuapp.com/vote/ELECTION_ID/pancakes/icecream/waffles'

Remove your vote

You can remove your vote by sending a GET request to the /unvote/ELECTION_ID endpoint. Note that this action will remove only your vote, not all votes.

curl --location --request GET 'https://ranked-voter.herokuapp.com/unvote/ELECTION_ID'

How to setup ranked-voting

  1. Clone the repository and navigate to the root directory

    git clone https://github.com/aditeyabaral/ranked-voting
    cd ranked-voting
  2. Create a new Python3 environment and activate it

    virutalenv ranked-voting
    source ranked-voting/bin/activate
  3. Install the requirements

    pip install -r requirements.txt
  4. Create a .env file and add a database connection URL

  5. Run the app

    python3 app/app.py


View Github