Using mySociety’s APIs for #ge2017

Stuart Harrison
Apr 20, 2017 · 3 min read

If you’re living in the UK, it probably hasn’t escaped your attention that the Prime Minister Theresa May has put the wheels in motion for a UK General Election on June 8th. This means that an estimated 47 million UK citizens will be eligible to vote for a member of Parliament to represent their area (‘constituency’) to potentially make up a new government.

This has excited a large number of people in the tech community looking to build web applications to do various things, from tactical voting ideas through to encouraging young people to vote.

Whatever your political persuasion, mySociety have a couple of resources that could help, Mark went into more detail in this post on the main mySociety blog and I thought I’d write a quick technical guide for developers on how to use the APIs for two of those resources, MapIt and TheyWorkForYou.

MapIt UK

MapIt is our tool for mapping postcode and coordinates to geographical areas like council wards and parliamentary constituencies. It’s been around since the Ordnance Survey started opening up this data in 2010 and powers some of our internal services, such as WriteToThem (which allows citizens to email their MPs), and TheyWorkForYou (more on that later). It also powers a number of external services, both private and public sector.

The API is documented in full at, and a call to returns JSON with all information about a given postcode.

While you can use MapIt without an API key, you’ll be limited to 50 calls a day so it’s best if you sign up for an API key. The ‘village’ plan is free for non-profit / charitable use, and allows up to 10,000 calls a month. However, if you’re planning on using MapIt for something related to the election, and don’t think 10,000 calls a month will be enough, email us at and we’ll see if we can help.

To get you started super quickly, and with the help of other developers in the mySociety team, I’ve put a few examples in Python, Node.js, PHP and Ruby together showing how to get a constituency from a postcode:


TheyWorkForYou is one of mySociety’s longest-running projects, launching in 2004. Our API has the full history of parliamentary goings on and memberships since the 1930s and a whole bunch of really useful data.

The API is documented in full at You’ll need to sign up for an API key too, which covers low volume use for free. Again, if you’re looking to build something for the election, and think you’re likely to be busy, email us at and we’ll whitelist your API key for the duration of the election campaign.

Here’s a couple of examples (again, in Ruby, Python and Node.js) showing how to find an MP from a constituency name as well as some useful information about them, such as their party, how they campaigned in the EU referendum, and their social media contact details.

Anything else?

We’ve collated a complete list of our General Election Data sources in our shiny new data portal at

Also, as Mark mentioned in his post on the mySociety blog, Democracy Club are going all guns blazing to document who is standing, as well as election results after all ballots have been counted.

If you want to do something to help improve access to data in the run up to the election, you can find out how you can help in Democracy Club’s General election 2017 blog post.

Finally, mySociety is a charity and all of this work is carried out on a shoestring budget. If you like what we do, then please donate to help keep all of our services up and running.

Image courtesy of Megan Trace on

Helping citizens demand better, worldwide

Stuart Harrison

Written by

Senior developer at @futuregov, homebrewer of all the things

Helping citizens demand better, worldwide