skip to content

Election Identifier Reference

An election code starts with an election type string. It may optionally contain descriptors for election subtype, organisation and division The identifier is terminated with the date that the polls open (in ISO 8601 format) for that particular election. Each section is separated by a period character ('.'). Names are slugified with hyphens ('-') separating tokens. An optional segment is used to indicate by-elections

All characters used are URL-friendly lowercase unreserved characters -- i.e. RFC3986 unreserved characters = ALPHA / DIGIT / "-" / "." / "_" / "~", where ALPHA is [a-z] and DIGIT is [0-9].

Examples of this could be parl.2015-05-07 or local.ashfield.hucknall-north.by.2017-10-12

Segments

Election typeRequired, text
Election subtypeOptional, text
OrganisationOptional, text
DivisionOptional, text
By-electionOptional, text
Date polls open Required, (ISO 8601 format date)

Election type

All election identifiers must include an election type. This describes the type of elected office that will be held by the winner(s) of this election.

Election subtype

Subtypes are used when an official body (Scottish Parliament, National Assembly for Wales, Greater London Authority) elects members by two different methods. In this case, elections are split into sub-elections based on voting system.

Organisation

An administrative body which can hold an election.

When an election type only covers a single organisation the organisation segment of the ID is excluded. This is to prevent parl.parl, senedd.senedd and so on where the organisation name and election type are the same.

Organisation segments must use official names. Organisation names are sourced from gov.uk registers. Short form versions of names should be used i.e: local.birmingham.2018-05-03 not local.birmingham-city-council.2017-05-04.

Division

A sub-part of an organisation that a candidate can be elected to represent. This could be a ward in the case of a local election or a constituency in the case of a parliamentary election.

Division segments must use names as they appear in legislation. For boundaries that are already in use, the names of parliamentary constituencies, district wards and county electoral divisions are sourced from OS Boundary Line. Names of new boundaries are extracted from Electoral Change Orders.

By-election

By-elections are indicated with the segment by.

Identifier Types

Type Subtype Slug Organisations Divisions
European Parliament (UK) elections europarl   ✔️
Greater London Assembly elections Constituencies gla.c   ✔️
Greater London Assembly elections Additional gla.a    
Local elections local ✔️ ✔️
Mayoral elections mayor ✔️  
National Assembly for Wales elections Constituencies naw.c   ✔️
National Assembly for Wales elections Regions naw.r   ✔️
Northern Ireland Assembly elections nia   ✔️
UK Parliament elections parl   ✔️
Police and Crime Commissioner elections pcc ✔️  
Senedd Cymru elections Constituencies senedd.c   ✔️
Senedd Cymru elections Regions senedd.r   ✔️
Scottish Parliament elections Constituencies sp.c   ✔️
Scottish Parliament elections Regions sp.r   ✔️

Hierarchy

Election ids are hierarchical. The lowest level (or most detailed) identifer for an election type is called the ballot id and describes a single ballot paper. Each level above this is a group id.

For example, the ballot id
senedd.c.aberavon.2021-05-06 is a child of the (subtype) group
senedd.c.2021-05-06 which is in turn a child of the (election) group
senedd.2021-05-06

Similarly, the ballot id
local.worcestershire.bewdley.2017-05-04 is a child of the (organisation) group
local.worcestershire.2017-05-04 which is in turn a child of the (election) group
local.2017-05-04

The by segment only applies to a ballot id, so
parl.oldham-west-and-royton.by.2015-12-03 is a child of
parl.2015-12-03. The group id does not include the by segment, even if all of its childen are by-elections.

Implementations

uk-election-ids - A python package with includes a builder object, slugging algorithm and validation rules for creating identifiers that conform to this specification.