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 on a single day 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]

Previous Party Affiliations

The Local Elections (Principal Areas) (Wales) Rules 2021 Statutory Instrument, among other things introduced a requirement for candidates to list any other political party membership in the last 12 months on the Statement Of Persons Nominated.

We store this information, and present it for candidates in Welsh run elections. The field exists on the candidate object in the candidates list on each ballot. It wil be null unless the candidate has declared affiliation with another party in the last 12 months.

Note that this is not the same as previous candidacies for this person. A person must declare parties they have beem members of in the previous 12 months before the date of the election.

When data exists, it's a list of parties. This information is transcribed from the Statement of Persons Nominated.