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 the electoral_services or registration 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, the candidates array is sorted by party and list_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 2002

• EA-2022: ID required under the Elections Act 2022

• pilot-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 candidates

• EQUAL_CANDIDATES: Equal candidates to contested seats

• UNDER_CONTESTED: Fewer candidates than seats

• CANDIDATE_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]