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 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, Greater London Authority, Senedd before 2026) 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

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.

By-Election Reason Definition Reference

There are various reasons why a by-election may be triggered. Not all of these can be applied to all election types. e.g. a recall petition is only used in Westminster, and failure to attend meetings applies to local government. The choices here are in part based on: UK Electoral Commission guidance on casual vacancies: https://www.electoralcommission.org.uk/guidance-returning-officers-administering-local-government-elections-england/casual-vacancies-and-elections/how-casual-vacancies-occur