Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 4 Aug 2022

frontend: Elections API

The Contact Electoral Registration Office page is published as a Local Transaction format page. These usually do postcode lookups via Locations API and then get council and URL information from Local Links Manager.

Electoral Commission have a public API for finding this information which they keep up to date.

The API is also capable of disambiguating postcodes that span local authority boundaries.

The API contains other information, such as dates and times of elections and where your local polling station is, however we're not using that yet.

Reverting to the local transaction

Should we need to revert to not using the API, we just need to comment out or remove the line in routes.rb that sends requests to electoral_controller.

The content item is still a local transaction, so the standard routing will kick in further down.


Electoral Commission's public contact details are:

The API is currently supported by Democracy Club, so another good place to ask for help is the Democracy Club Slack


To interact with the API locally, create a .env file in the root of this project with the following entries:

ELECTIONS_API_URL=<get value from integration secrets>
ELECTIONS_API_KEY=<get value from integration secrets>

The API has its own documentation.

Application flows

Unambiguous postcode

Land on

Enter unambiguous postcode (eg W1A 1AA)

Click "Find"

See results on

Ambiguous postcode

Land on

Enter ambiguous postcode (eg WV14 8TU)

Click "Find"

See address picker on

Select an address and click "Continue"

See results on

Postcode with no location

Land on

Enter "valid" postcode that doesn't exist in a local authority (eg XM45 HQ)

Click "Find"

See "We couldn't find this postcode" error on

Invalid postcode

Land on

Enter invalid postcode (eg Bernard)

Click "Find"

See "This isn't a valid postcode" error on

Invalid UPRN

Navigate to an invalid UPRN somehow:

See "This isn't a valid address" error on