Using the candidate data

The data that's submitted to this site is available as a CSV/Excel download and programmatically via a RESTful API.

Using our data

The data on this site is provided under a CC BY-SA licence.

This means you are free to reuse the data for any reason, as long as you give attribution to "Democracy Club" and any reuse is shared under the same licence. Please read the full terms for more information.

This licence excludes:

  • The party logos, which are taken from the Electoral Commission's website
  • Candidate photos, which are typically either submitted by the candidates themselves, or from sources where it seems reasonable that we might use them on this site, such as the party's official page for that candidate, or their social media profile picture.

If the CC-BY-SA licence is problematic for you, but you feel that you have a worthwhile use of the data in mind, please contact us to discuss your situation further.

Giving attribution

If you are reusing our data, please credit "Democracy Club" on the same page(s) as the data is used, and provide a link (or write the URL in the case of printed material) to https://democracyclub.org.uk

We would like you to include our logo alongside the data, but we understand that this won't always be possible.

Election results

There is a separate page explaining how to get election results from this site.

CSV/Excel Download

All Candidates

This CSV file contains details of all candidates in the database

Current Elections

Aug. 29, 2017

Local elections

Aug. 31, 2017

Local elections

Sept. 7, 2017

Local elections

Sept. 12, 2017

Local elections

Sept. 14, 2017

Local elections

Sept. 21, 2017

Local elections

Sept. 28, 2017

Local elections

Oct. 5, 2017

Local elections

Oct. 12, 2017

Local elections

Oct. 19, 2017

Local elections

Past Elections

May 6, 2010

Member of Parliament

May 7, 2015

Member of Parliament

May 5, 2016

Local Councillor
Mayor
Member of Parliament
Member of the Legislative Assembly
Member of the London Assembly
Member of the National Assembly for Wales
Member of the Scottish Parliament
Police and Crime Commissioner

Feb. 23, 2017

UK Parliament

March 2, 2017

Member of the Legislative Assembly

March 23, 2017

Local elections

May 4, 2017

Directly elected Mayor
Local elections
UK Parliament

May 11, 2017

Local elections

June 8, 2017

Local elections
UK Parliament

June 29, 2017

Local elections

July 20, 2017

Local elections

July 27, 2017

Local elections

Aug. 3, 2017

Local elections

Aug. 17, 2017

Local elections

Sept. 11, 2017

Local elections

API

This API is a work in progress

This is an alpha version of the YourNextRepresentative API, which is likely to change in the near future.

Browsable API root

The browsable base URL of the site's read-only API is: https://candidates.democracyclub.org.uk/api/v0.9/

The following sections give examples of how to use the API.

Find a Constituency ID

In order to look up candidates for a constituency, you have to find the ID of that constituency. As of the 2016 local and regional elections we use a combination of area type and GSS codes. You can look up the GSS codes using another web service, MapIt. There's a list of area types in the MapIt API documentation.

... from a postcode

Suppose you want to find the constituency for the postcode SW1A 1AA, then you would make a GET request to the following URL:

http://mapit.mysociety.org/postcode/SW1A1AA

This returns a JSON object, which contains the details of all the admistrative areas that cover that postcode. You need to loop over the areas object till you find the area with the correct type - for Westminster constitiencies this is WMC. The GSS code for that area is in codes.gss.

There's more documentation available on postcode lookups on the MapIt front-page and area codes in MapIt API documentation.

... from a latitude / longitude or other coordinate

You can look up constituencies in MapIt using a variety of coordinate systems. To give the most common example, you might have a WGS84 coordinate from a GPS or location API, in which can you should put the SRID 4326 in your lookup. For example, latitude 52.205083 and longitude 0.115194 could be looked up with:

http://mapit.mysociety.org/point/4326/0.115194,52.205083?type=WMC
(Note that the longitude comes before the latitude, which might not be what you expect.) The returned object should have a single key and inside the value the GSS code is in codes.gss.

There's more documentation available on point lookups on the MapIt front-page.

... by selecting it from its name

If you need to produce a list of all constituencies (e.g. for a select box) and allow the user to pick one, you can get a list of all Westminster constituencies in the UK from this request:
http://mapit.mysociety.org/areas/WMC

The returned data from that request includes a set of keys, the values of which contains the GSS code in codes.gss.

Find Candidates for a Constituency

You can request all the candidates in that constituency by querying posts with the extra_slug filter parameter. For example, for Dulwich and West Norwood, which has the GSS code E14000673, you would make the request: https://candidates.democracyclub.org.uk/api/v0.9/posts/WMC:E14000673/

Each of the memberships in that response links to a person who is a candidate in that constituency for any known election. The election property of each membership tells you which election that candidacy is for.

Pre 2016 data

Prior to the 2016 local and regional elections we used the MapIt codes for areas. For postcode lookups this is available from shortcuts.wmc in the returned object. For the point lookup and by type lookups the MapIt ID are contained in the keys of the returned object.

Dulwich and West Norwood as a MapIt ID of 65808 so to look up the pre 2016 results you would make the request: https://candidates.democracyclub.org.uk/api/v0.9/posts/65808/