VoteIt API Server
This is a server component for a VoteIt API — part of a suite of tools for managing parliamentary (or other) vote results.
Before installing, make sure you have the following dependencies available on your system:
- MongoDB, ideally greater than 2.7.
- Python 2.7 and virtualenv
When you set up
voteit-api, first check out the application from GitHub,
create a virtual environment and install the Python dependencies:
git clone https://github.com/tmtmtmtm/voteit-api.git cd voteit-api virtualenv env source env/bin/activate pip install -r requirements.txt python setup.py develop
Next, you need to start MongoDB. For testing, you can simply run
You also need to configure
voteit-api to point at this. Create a copy of the file
settings.py in the repository base, and change
MONGODB_URI if required (the default should just work unless you've configured MongoDB differently).
Once the new configuration is set up, you need to set an environment variable to point
voteit-api at the configuration file:
Finally, you can run
python voteit/manage.py runserver
Test that it's working by visiting the URL it tells you it's running on.
When developing voteit-api day-to-day, you'll need to run
whenever you start a new shell. This tells Python to load the dependencies for
voteit-api. It will place
(env) at the start of your shell prompt.
Bulk loader format
Data for people, parties, and votes, conforming to the relevant Popolo specfications, can be bulk-loaded from JSON files.
people.json- Popolo person data for each person that has cast votes. (Example)
parties.json- Popolo organization data for each person that has cast votes. (Example)
motions.json- Popolo motion data, with nested vote_events, vote_counts, and votes. (Example)
vote is expected to contain a
voter_id that resolve against the people and party data.
These files can be imported using:
python voteit/manage.py loadpeople <filename> python voteit/manage.py loadparties <filename> python voteit/manage.py loadmotions <filename>
It is presumed that your normal usage is 'append only' — i.e. that historic data will not change — you will simply be adding new data. Therefore, these do bulk imports, and so will not replace or ignore pre-existing records, but issue an error if clashes are detected.
If you do need to change historic data, you can either write your own
code to do that, or simply delete and recreate any data set (for
the average Parliament, a complete
people.json file will reload in
a few seconds)
To clean out existing data first you can run:
python voteit/manage.py deletepeople python voteit/manage.py deleteparties python voteit/manage.py deletemotions
or all three at once:
python voteit/manage.py deletealldata
Deploying to Heroku
The code should run cleanly on Heroku, and depending on your data, you should be able to store at least half a million individual vote records within their usage limits.
To deploy, first install a MongoHQ sandbox from https://addons.heroku.com/
heroku git:remote --app <your app name> git push heroku master export MONGOHQ_URL=`heroku config:get MONGOHQ_URL` export VOTEIT_SETTINGS=`pwd`/heroku_settings.py heroku config:set VOTEIT_SETTINGS=/app/heroku_settings.py
Then push your data, as above.
A read-only API exposes the following end-points:
- GET /api/1/motions
- GET /api/1/motion/
- GET /api/1/parties
- GET /api/1/parties/
- GET /api/1/persons
- GET /api/1/persons/
aggregrate API end-point is also provided that allows grouping and filtering of vote information. For example:
To see vote counts by party on a given motion:
- GET /api/1/aggregate?motion=62-2012-1&bloc=party_id
Or how a specific party voted on a range of motions:
- GET /api/1/aggregate?motion=62-2012-1&motion=62-2012-2&filter=party_id:13