📦 Create Democracy Club Election Identifiers
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


UK Election IDs

Build Status Coverage Status PyPI Version License Python Support

Create Democracy Club Election Identifiers.

Democracy Club defines a specification for creating reproducible unique identifiers for elections in the UK. See our reference definition. If you are interested in independently producing identifiers which are compatible with those produced by our Every Election platform, this python package includes a builder object, slugging logic and validation rules for creating identifiers that conform to the spec.


pip install uk-election-ids

Usage Examples

>>> from uk_election_ids.election_ids import IdBuilder
>>> from datetime import date

# Chain method calls to build up an ID object
>>> myid = IdBuilder('local', date(2018, 5, 3))\
...     .with_organisation('Test Org')\
...     .with_division('Test Division')
# IdBuilder will deal with slugging strings for us
>>> myid.ballot_id
>>> myid.ids

# IdBuilder only allows values defined in the Reference Definition
>>> myid = IdBuilder('gla', date(2018, 5, 3)).with_subtype('x')
ValueError: Allowed values for subtype are ('c', 'a')

# Group IDs can be created with partial information
>>> myid = IdBuilder('local', date(2018, 5, 3)).with_organisation('Test Org')
>>> myid.election_group_id
>>> myid.organisation_group_id
>>> myid.ballot_id
ValueError: election_type local must have a division in order to create a ballot id

# A Group ID object can be used to create multiple ballot IDs
>>> divisions = ["area1", "area2", "area3"]
>>> org_id = IdBuilder('local', date(2018, 5, 3)).with_organisation('Test Org')
>>> [org_id.with_division(d).ballot_id for d in divisions]

API Documentation

See the full API Reference

Data Sources

Election Types and Subtypes

Valid Election types and subtypes are defined in the reference definition.

Organisation Names

For compatibility, organisation segments must use official names. Organisation names can be sourced from gov.uk registers. Short form versions of names should be used i.e: add an organisation segment with myid.with_organisation('Birmingham') not myid.with_organisation('Birmingham City Council')

Alternatively organisation names can be sourced from the Every Election API. Use the common_name key.

Division Names

For compatibility, division segments must use official names. For boundaries that are already in use, names of parliamentary constituencies, district wards and county electoral divisions should be sourced from OS Boundary Line. New boundaries must be extracted from legislation. We also maintain a parser which can help with extracting this data from Electoral Change Orders.


To report a bug, raise an issue. If you are using election identifiers, join our slack to ask questions or tell us about your project.


Run the tests locally:


Build locally:


Rebuild the API docs:

pydoc uk_election_ids.election_ids.IdBuilder > docs.txt