UK Election IDs
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
>>> 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 'local.test-org.test-division.2018-05-03' >>> myid.ids [ 'local.2018-05-03', 'local.test-org.2018-05-03', 'local.test-org.test-division.2018-05-03' ] # 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 'local.2018-05-03' >>> myid.organisation_group_id 'local.test-org.2018-05-03' >>> 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] [ 'local.test-org.area1.2018-05-03', 'local.test-org.area2.2018-05-03', 'local.test-org.area3.2018-05-03' ]
See the full API Reference
Election Types and Subtypes
Valid Election types and subtypes are defined in the reference definition.
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 City Council')
- Local authorities in England: use the 'name' column/key
- Principal local authorities in Wales: use the 'name' column/key
- Local authorities in Scotland: use the 'name' column/key
- Local authorities in Northern Ireland
Alternatively organisation names can be sourced from the Every Election API. Use the
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.
Run the tests locally:
Rebuild the API docs:
pydoc uk_election_ids.election_ids.IdBuilder > docs.txt