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.

Installation

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
'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'
]

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')

• 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 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.

Support

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.

Development

Run the tests locally:

./run_tests.py

Build package locally:

./build.sh

Build the API docs:

cd docs && make clean html