Developer API

Alpha This is a new service – your feedback will help us to improve it.

Overview and concepts

This API takes a postcode or UPRN and returns current information about elections, councils, candidates and polling stations.

High level concepts

It's important to understand that this API returns different types of response depending on the postcode entered

This is because some postcodes are "split" across council areas or polling districts, meaning that we need more information than just a postcode in order to give accurate responses.

The additional information we need is the exact UPRN for the property, and this is provided as a [list of addresses] if we detect a split postcode.

Case 1: Results after address picker shown
sequenceDiagram Client->>+API: Postcode lookup to /api/postcode/{postcode} API->>+Client: Address picker with UPRNs Client->>+API: UPRN lookup to /api/address/{UPRN} API->>+Client: Results
Case 2: Results direct from postcode
sequenceDiagram Client->>+API: Postcode lookup to /api/postcode/{postcode} API->>+Client: Address picker with UPRNs Client->>+API: UPRN lookup to /api/address/{UPRN} API->>+Client: Results

Authentication

Calls to the API must be authenticated with a valid API key.

To get a key, please [log in or register](/user/login/) and create a key.

To authenticate with a key either pass in the `auth_token` param or use the `Authorization` header

Authenticate with curl
    curl -X GET https://api.electoralcommission.org.uk/api/[endpoint]/ -H 'Authorization: Token 123456'
    
Authenticate with URL param
    curl -X GET https://api.electoralcommission.org.uk/api/[endpoint]/?token=123456'
    

Errors

Errors will be reported using HTTP status codes. The body of the error will be formatted as valid JSON and will give a description of the error

Example error response
    { "detail": "Could not geocode from any source" }