Notes and Tips ¶
Polling Stations
- If we don't know a user's polling station, sometimes we may provide an external link for more info in
custom_finder
. This will always be populated for users in Northern Ireland where the Electoral Office for Northern Ireland run their own service. e.g:
{
...
"custom_finder": "http://www.eoni.org.uk/Offices/Postcode-Search-Results?postcode=BT28%202EY"
}
- If we don't know a user's polling station and
custom_finder
is not populated, the contact details in theelectoral_services
orregistration
object can be used to provide contact details for the user's local electoral services or registration team.
Contact details
We provide two types of contact details; "electoral services" and "registration". This is because in Scotland and Northern Ireland the local authority doesn't handle electoral registration. If you are using the data to deal with electoral registration, use the registration
contact details. Please make sure you are using the correct contact details for your users needs.
Ballots and Candidates
It is possible for more than one ballot to occur on the same date, so a
ballots
array may contain many objects. For example, a user may vote in a local council election and mayoral election on the same day.Occasionally a ballot needs to be cancelled. The most common reason for this is if one of the candidates dies between close of nominations and polling day, but there are other situations where this may happen. Remember to check the
cancelled
flag on ballot objects.In an election using party lists, candidates should be shown to users grouped by party and ordered by
list_position
within parties. In an election which uses party lists, thecandidates
array is sorted by party andlist_position
within parties. For other election types it is sorted alphabetically by candidate name.
Notifications
We'll use the notifications
array to provide additional info
to be shown to the user about special conditions to be aware of on this date
e.g: identification requirements, or a cancelled poll.
ID Requirements
Some UK elections require ID in order to vote in person.
This is defined at the ballot level, as it's possible for some ballots to require ID and some not to. In this case the user must be told about the requirements, even if not all ballots require them.
The ballot has a requires_voter_id
key that will be one of the following values:
EFA-2002
: ID required under the Electoral Fraud (Northern Ireland) Act 2002EA-2022
: ID required under the Elections Act 2022pilot-2018
: 2018 voter ID pilot scheme (historic elections only)pilot-2019
: 2019 voter ID pilot scheme (historic elections only)
If the requires_voter_id
is not null then users must be told that they are required to bring ID. The exact ID
requirements change depending on the value. This should be taken into account when writing copy that is shown to users.
Cancelled Polls
Sometimes a scheduled poll may be cancelled. This is usuaully either because the election is uncontested or due to death of a candidate.
When a single ballot is cancelled, a cancellation_reason
will be added to the response. The values are:
NO_CANDIDATES
: No candidatesEQUAL_CANDIDATES
: Equal candidates to contested seatsUNDER_CONTESTED
: Fewer candidates than seatsCANDIDATE_DEATH
: Death of a candidate
The fact the election is cancelled must be presented to the user, but it's up to consumers to define if or how the reason for the cancellation is presented.
If all elections for a query are cancelled we will add a notification in the notification
array (see above), e.g:
{
...
"notifications": [
{
"url": null,
"type": "cancelled_election",
"detail": "The poll for this election will not take place because it is uncontested.",
"title": "Uncontested Election"
}
]
}
Advance Voting Stations
For the 2022 local elections in Wales, four councils are piloting "Advance Voting". This means people in the pilot areas will be able to cast their vote in the days before polling day.
We support this pilot, and have an extra key in the API in the dates
array.
{
...
"advance_voting_station": {
"name": "Exeter Guildhall",
"address": "Exeter City Council\nCivic Centre\nParis Street\nExeter\nDevon",
"postcode": "EX1 1JN",
"location": {
"type": "Point",
"coordinates": [
-3.524551005678706,
50.72486002944331
]
},
"opening_times": [
[
"2018-11-20",
"10:00:00",
"16:00:00"
],
[
"2018-11-21",
"10:00:00",
"16:00:00"
]
]
},
}
If this object exists in the API response, it's highly recommended to display it to the user.
Each Advance Voting Station has a name, address, postcode and location. Opening times are given as an ordered list of lists, containing:
[date, open time, close time]