The postcode and address endpoints find details of ballots, candidates and polling stations based on the user's registered address. This allows you to present Democracy Club's data to users in your website or app.
The entry point to a polling station search is a call to the postcode endpoint.
A valid postcode search may result in one of 3 outcomes:
No upcoming ballots: There are no upcoming ballots relevant to this area.
Results found: We hold data for this area and the same ballots, candidates and polling station data is relevant to all registered addresses with this postcode.
Address picker: We hold data for this area but different information is applicable to different addresses with this postcode. To find relevant data, we must show the user an address picker and make a second API call to the
addressendpoint.
Postcode search: No upcoming ballots ¶
/api/v1/postcode/{postcode}Parameters
postcode
string( required )Whitespace in postcodes is ignored, so format may be
SW1A1AAorSW1A 1AAExample:
SW1A1AA
Response ¶
Example of a response when there are no upcoming ballots.
In this case address_picker is false and dates is an empty array.
Request GET
/api/v1/postcode/{postcode}
Response
200
Headers:
Content-Type: application/json
Body:
{
"address_picker": false,
"addresses": [],
"dates": [],
"electoral_services": {
"council_id": "W06000015",
"name": "Cardiff Council",
"nation": "Wales",
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"registration": {
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"postcode_location": {
"type": "Feature",
"properties": null,
"geometry": {
"type": "Point",
"coordinates": [
-3.113797,
51.521175
]
}
}
}
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address_picker": {
"type": "boolean",
"description": "True if we need to show this user an address picker"
},
"addresses": {
"type": "array",
"description": "An array of address objects containing the addresses applicable to this request (if necessary)"
},
"dates": {
"type": "array",
"description": "An array of date objects containing details of relevant ballots, candidates and polling station information"
},
"electoral_services": {
"type": [
"object",
"null"
],
"properties": {
"council_id": {
"type": "string",
"description": "GSS code for this council"
},
"name": {
"type": "string",
"description": "Name of this council"
},
"nation": {
"type": "string",
"description": "Name of nation"
},
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Contact details for the user's local Electoral Services team. If we do not know the user's polling station, this can be used to provide contact info for their local council. This may be `null` if we are not able to determine the user's council."
},
"registration": {
"type": [
"object",
"null"
],
"properties": {
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Sometimes the contact information for registration and proxy voting is different to the electoral services contact details. Use these if they exist and your users might have questions about voter registration. If this key is null, assume the electoral services contact details can be used for electoral registration related enquiries."
},
"postcode_location": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"properties": {
"type": [
"object",
"null"
],
"properties": {}
},
"geometry": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) containing a [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) describing the centroid of the input postcode. If providing a map or directions for a polling station journey, use this as the start point. This may be `null` if we are not able to accurately geocode."
}
}
}Postcode search: Results found ¶
/api/v1/postcode/{postcode}Parameters
postcode
string( required )Whitespace in postcodes is ignored, so format may be
SW1A1AAorSW1A 1AAExample:
SW1A1AA
Response ¶
Example of a response when we hold data for this area and the same ballots, candidates and polling station data is relevant to all registered addresses with this postcode.
In this case address_picker is false and dates is an array of date objects.
Request GET
/api/v1/postcode/{postcode}
Response
200
Headers:
Content-Type: application/json
Body:
{
"address_picker": false,
"addresses": [],
"dates": [
{
"date": "2017-05-04",
"polling_station": {
"polling_station_known": true,
"custom_finder": null,
"report_problem_url": "http://wheredoivote.co.uk/report_problem/?source=testing&source_url=testing",
"station": {
"id": "w06000015.QK",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-3.119229,
51.510885
]
},
"properties": {
"postcode": "",
"address": "Earlswood Social Club, 160-164 Greenway Road, Rumney"
}
}
},
"advance_voting_station": null,
"notifications": [
{
"title": "Some unexpected event is happening",
"type": "cancelled_election",
"detail": "Some more details",
"url": "https://foo.bar/baz"
}
],
"ballots": [
{
"ballot_paper_id": "local.cardiff.pontprennauold-st-mellons.2017-05-04",
"ballot_title": "Cardiff local election Pontprennau/Old St. Mellons",
"poll_open_date": "2017-05-04",
"elected_role": "Local Councillor",
"metadata": null,
"cancelled": false,
"cancellation_reason": "null",
"replaced_by": null,
"replaces": null,
"requires_voter_id": "EA-2022",
"election_id": "local.cardiff.2017-05-04",
"election_name": "Cardiff local election",
"post_name": "Pontprennau/Old St. Mellons",
"candidates_verified": false,
"voting_system": {
"slug": "FPTP",
"name": "First-past-the-post",
"uses_party_lists": false
},
"seats_contested": 1,
"candidates": [
{
"list_position": null,
"party": {
"party_id": "party:90",
"party_name": "Liberal Democrats"
},
"previous_party_affiliations": [
{
"party_id": "party:90",
"party_name": "Liberal Democrats"
}
],
"person": {
"ynr_id": 23417,
"name": "David Keigwin",
"email": "dave@example.com",
"photo_url": null
}
},
{
"list_position": null,
"party": {
"party_id": "party:52",
"party_name": "Conservative and Unionist Party"
},
"person": {
"ynr_id": 8071,
"name": "Joel Williams",
"email": null,
"photo_url": "https://static-candidates.democracyclub.org.uk/media/images/images/8071.png"
}
}
]
}
]
}
],
"electoral_services": {
"council_id": "W06000015",
"name": "Cardiff Council",
"nation": "Wales",
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"registration": {
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"postcode_location": {
"type": "Feature",
"properties": null,
"geometry": {
"type": "Point",
"coordinates": [
-3.113797,
51.521175
]
}
}
}
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address_picker": {
"type": "boolean",
"description": "True if we need to show this user an address picker"
},
"addresses": {
"type": "array",
"description": "An array of address objects containing the addresses applicable to this request (if necessary)"
},
"dates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Polling day on which an election will occur"
},
"polling_station": {
"type": "object",
"properties": {
"polling_station_known": {
"type": "boolean",
"description": "Do we know where this user should vote?"
},
"custom_finder": {
"type": [
"string",
"null"
],
"description": "If we don't know a user's polling station, sometimes we can provide the URL of another polling station finder. This will always be populated for users in Northern Ireland where Electoral Office for Northern Ireland run their own service."
},
"report_problem_url": {
"type": [
"string",
"null"
],
"description": "If we provide a polling station result, this URL may be used to provide a user with a back-channel to report inaccurate data."
},
"station": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"geometry": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
},
"description": "A GeoJSON [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) object describing the location of this polling station. Optionally null if we know the address only but can't geocode a location."
},
"properties": {
"type": "object",
"properties": {
"postcode": {
"type": "string",
"description": "Postcode for this polling station"
},
"address": {
"type": "string",
"description": "Address for this polling station"
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) describing the user's polling station (if known)"
}
},
"description": "Results for polling station search"
},
"advance_voting_station": {
"type": [
"object",
"null"
],
"properties": {},
"additionalProperties": false,
"description": "Advance Voting Stations\n\n + `name`: (string) - The name of the Advance Voting Station\n + `address`: (string) - The address of the Advance Voting Station\n + `postcode`: (string) - The postcode of the Advance Voting Station\n + `location`: (object) - A GeoJSON [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) object describing the location of this Advance Voting Station.\n + type: `Point` (string)\n + coordinates: (array[number], fixed-type)\n + `-3.119229`\n + `51.510885`\n + `opening_times`: (array[array], fixed-type):\n + (array)\n + `date`\n + `open`\n + `close`"
},
"notifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"cancelled_election",
"voter_id"
],
"description": "Type of notification"
},
"detail": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"description": "Array of notifications to be shown to the user about special conditions to be aware of on this date."
},
"ballots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ballot_paper_id": {
"type": "string",
"description": "Identifier for this ballot"
},
"ballot_title": {
"type": "string",
"description": "Friendly name for this ballot"
},
"poll_open_date": {
"type": "string",
"description": "Polling day for this ballot (ISO 8601)"
},
"elected_role": {
"type": "string",
"description": "Name of the role the winner(s) of this election will assume"
},
"metadata": {
"type": [
"object",
"null"
],
"properties": {},
"description": "Object containing information about special conditions for the user to be aware about (e.g: cancelled elections, voter id pilot). (details TBC)"
},
"cancelled": {
"type": "boolean",
"description": "True if this ballot has been cancelled"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"NO_CANDIDATES",
"EQUAL_CANDIDATES",
"UNDER_CONTESTED",
"CANDIDATE_DEATH",
"null",
null
],
"description": "If a ballot has been cancelled, this key may hold a codified reason for that ballot's cancellation"
},
"replaced_by": {
"type": [
"string",
"null"
],
"description": "If a ballot has been cancelled (cancelled = true) and rescheduled for a later date, this key will hold the ballot_paper_id of the ballot that replaces it."
},
"replaces": {
"type": [
"string",
"null"
],
"description": "If this ballot replaces another cancelled ballot, this key will hold the ballot_paper_id of the ballot that it replaces."
},
"requires_voter_id": {
"type": [
"string",
"null"
],
"enum": [
"EFA-2002",
"EA-2022",
"pilot-2018",
"pilot-2019",
null
],
"description": "The type of voter ID required in order to vote in this election. Nullable, or one of Electoral Fraud (Northern Ireland) Act 2002, Elections Act 2022 or one of the pilots."
},
"election_id": {
"type": "string",
"description": "Identifier for this ballot's parent election group"
},
"election_name": {
"type": "string",
"description": "Friendly name for this ballot's parent election group"
},
"post_name": {
"type": "string",
"description": "Name of the division or post the winner(s) of this election will represent"
},
"candidates_verified": {
"type": "boolean",
"description": "True if the list of candidates for this election has been confirmed against the nomination papers for this ballot. If this property is False, the candidate list is provisional or unconfirmed."
},
"voting_system": {
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "One of `AMS`, `FPTP`, `PR-CL`, `sv`, `STV`"
},
"name": {
"type": "string",
"description": "The name of this voting system (e.g: \"First-past-the-post\")"
},
"uses_party_lists": {
"type": "boolean",
"description": "True if this voting system uses party lists"
}
},
"description": "The voting system used in this election"
},
"seats_contested": {
"type": "number"
},
"candidates": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"list_position": {
"type": [
"number",
"null"
],
"description": "Numeric position in party list. This value is only relevant to elections using party lists. It will always be null in First-Past-The-post elections."
},
"party": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
},
"previous_party_affiliations": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
}
},
"person": {
"type": "object",
"properties": {
"ynr_id": {
"type": "number"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"description": "Email address for this candidate, if we hold it"
},
"photo_url": {
"type": [
"string",
"null"
],
"description": "URL for a photo of this candidate, if we hold one"
}
}
}
}
},
{
"type": "object",
"properties": {
"list_position": {
"type": [
"number",
"null"
],
"description": "Numeric position in party list. This value is only relevant to elections using party lists. It will always be null in First-Past-The-post elections."
},
"party": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
},
"person": {
"type": "object",
"properties": {
"ynr_id": {
"type": "number"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"description": "Email address for this candidate, if we hold it"
},
"photo_url": {
"type": [
"string",
"null"
],
"description": "URL for a photo of this candidate, if we hold one"
}
}
}
}
}
],
"description": "Array of candidate objects describing candidates that will appear on this ballot paper. 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."
}
}
},
"description": "List of ballots happening on this date. It is possible for more than one ballot to occur on the same date. For example, a user may vote in a local council election and mayoral election on the same day."
}
}
},
"description": "An array of date objects (each describing a date on which an election or poll will take place) containing details of relevant ballots, candidates and polling station information"
},
"electoral_services": {
"type": [
"object",
"null"
],
"properties": {
"council_id": {
"type": "string",
"description": "GSS code for this council"
},
"name": {
"type": "string",
"description": "Name of this council"
},
"nation": {
"type": "string",
"description": "Name of nation"
},
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Contact details for the user's local Electoral Services team. If we do not know the user's polling station, this can be used to provide contact info for their local council. This may be `null` if we are not able to determine the user's council."
},
"registration": {
"type": [
"object",
"null"
],
"properties": {
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Sometimes the contact information for registration and proxy voting is different to the electoral services contact details. Use these if they exist and your users might have questions about voter registration. If this key is null, assume the electoral services contact details can be used for electoral registration related enquiries."
},
"postcode_location": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"properties": {
"type": [
"object",
"null"
],
"properties": {}
},
"geometry": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) containing a [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) describing the centroid of the input postcode. If providing a map or directions for a polling station journey, use this as the start point. This may be `null` if we are not able to accurately geocode."
}
}
}Postcode search: Address picker ¶
/api/v1/postcode/{postcode}Parameters
postcode
string( required )Whitespace in postcodes is ignored, so format may be
SW1A1AAorSW1A 1AAExample:
SW1A1AA
Response ¶
Example of a response when we must show the user an address picker. This should be followed by a second API call to the address endpoint.
In this case address_picker is true and dates is an empty array. addresses is an array of address objects.
Request GET
/api/v1/postcode/{postcode}
Response
200
Headers:
Content-Type: application/json
Body:
{
"address_picker": true,
"addresses": [
{
"address": "16 DUNCAN CLOSE, ST. MELLONS, CARDIFF",
"postcode": "CF3 1NP",
"slug": "100100106448",
"url": "http://developers.democracyclub.org.uk/api/v1address/100100106448"
},
{
"address": "26 DUNCAN CLOSE, ST. MELLONS, CARDIFF",
"postcode": "CF3 1NP",
"slug": "100100106458",
"url": "http://developers.democracyclub.org.uk/api/v1address/100100106458"
}
],
"dates": [],
"electoral_services": {
"council_id": "W06000015",
"name": "Cardiff Council",
"nation": "Wales",
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"registration": {
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"postcode_location": {
"type": "Feature",
"properties": null,
"geometry": {
"type": "Point",
"coordinates": [
-3.113797,
51.521175
]
}
}
}
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address_picker": {
"type": "boolean",
"description": "True if we need to show this user an address picker"
},
"addresses": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"postcode": {
"type": "string"
},
"slug": {
"type": "string"
},
"url": {
"type": "string",
"description": "Call this URL to get data for this registered address"
}
}
},
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"postcode": {
"type": "string"
},
"slug": {
"type": "string"
},
"url": {
"type": "string",
"description": "Call this URL to get data for this registered address"
}
}
}
],
"description": "An array of address objects containing the addresses applicable to this request (if necessary)"
},
"dates": {
"type": "array",
"description": "An array of date objects containing details of relevant ballots, candidates and polling station information"
},
"electoral_services": {
"type": [
"object",
"null"
],
"properties": {
"council_id": {
"type": "string",
"description": "GSS code for this council"
},
"name": {
"type": "string",
"description": "Name of this council"
},
"nation": {
"type": "string",
"description": "Name of nation"
},
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Contact details for the user's local Electoral Services team. If we do not know the user's polling station, this can be used to provide contact info for their local council. This may be `null` if we are not able to determine the user's council."
},
"registration": {
"type": [
"object",
"null"
],
"properties": {
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Sometimes the contact information for registration and proxy voting is different to the electoral services contact details. Use these if they exist and your users might have questions about voter registration. If this key is null, assume the electoral services contact details can be used for electoral registration related enquiries."
},
"postcode_location": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"properties": {
"type": [
"object",
"null"
],
"properties": {}
},
"geometry": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) containing a [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) describing the centroid of the input postcode. If providing a map or directions for a polling station journey, use this as the start point. This may be `null` if we are not able to accurately geocode."
}
}
}Address search ¶
/api/v1/address/{slug}Parameters
slug
string( required )A unique slug describing a residential address
Example:
60017560
Response ¶
In the event that the same information is not applicable to all addresses described by a postcode, a call to postcode will return an array of address objects, each of which corresponds to a call to the address endpoint. A subsequent call to address will return an object of the same format as a valid call to postcode.
Request GET
/api/v1/address/{slug}
Response
200
Headers:
Content-Type: application/json
Body:
{
"address_picker": false,
"addresses": [],
"dates": [
{
"date": "2017-05-04",
"polling_station": {
"polling_station_known": true,
"custom_finder": null,
"report_problem_url": "http://wheredoivote.co.uk/report_problem/?source=testing&source_url=testing",
"station": {
"id": "w06000015.QK",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-3.119229,
51.510885
]
},
"properties": {
"postcode": "",
"address": "Earlswood Social Club, 160-164 Greenway Road, Rumney"
}
}
},
"advance_voting_station": null,
"notifications": [
{
"title": "Some unexpected event is happening",
"type": "cancelled_election",
"detail": "Some more details",
"url": "https://foo.bar/baz"
}
],
"ballots": [
{
"ballot_paper_id": "local.cardiff.pontprennauold-st-mellons.2017-05-04",
"ballot_title": "Cardiff local election Pontprennau/Old St. Mellons",
"poll_open_date": "2017-05-04",
"elected_role": "Local Councillor",
"metadata": null,
"cancelled": false,
"cancellation_reason": "null",
"replaced_by": null,
"replaces": null,
"requires_voter_id": "EA-2022",
"election_id": "local.cardiff.2017-05-04",
"election_name": "Cardiff local election",
"post_name": "Pontprennau/Old St. Mellons",
"candidates_verified": false,
"voting_system": {
"slug": "FPTP",
"name": "First-past-the-post",
"uses_party_lists": false
},
"seats_contested": 1,
"candidates": [
{
"list_position": null,
"party": {
"party_id": "party:90",
"party_name": "Liberal Democrats"
},
"previous_party_affiliations": [
{
"party_id": "party:90",
"party_name": "Liberal Democrats"
}
],
"person": {
"ynr_id": 23417,
"name": "David Keigwin",
"email": "dave@example.com",
"photo_url": null
}
},
{
"list_position": null,
"party": {
"party_id": "party:52",
"party_name": "Conservative and Unionist Party"
},
"person": {
"ynr_id": 8071,
"name": "Joel Williams",
"email": null,
"photo_url": "https://static-candidates.democracyclub.org.uk/media/images/images/8071.png"
}
}
]
}
]
}
],
"electoral_services": {
"council_id": "W06000015",
"name": "Cardiff Council",
"nation": "Wales",
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"registration": {
"address": "Electoral Registration Officer\\nCity of Cardiff Council\\nCounty Hall Atlantic Wharf",
"postcode": "CF10 4UW",
"email": "electoralservices@cardiff.gov.uk",
"phone": "029 2087 2034",
"website": "http://www.cardiff.gov.uk/"
},
"postcode_location": {
"type": "Feature",
"properties": null,
"geometry": {
"type": "Point",
"coordinates": [
-3.113797,
51.521175
]
}
}
}
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address_picker": {
"type": "boolean",
"description": "True if we need to show this user an address picker"
},
"addresses": {
"type": "array",
"description": "An array of address objects containing the addresses applicable to this request (if necessary)"
},
"dates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Polling day on which an election will occur"
},
"polling_station": {
"type": "object",
"properties": {
"polling_station_known": {
"type": "boolean",
"description": "Do we know where this user should vote?"
},
"custom_finder": {
"type": [
"string",
"null"
],
"description": "If we don't know a user's polling station, sometimes we can provide the URL of another polling station finder. This will always be populated for users in Northern Ireland where Electoral Office for Northern Ireland run their own service."
},
"report_problem_url": {
"type": [
"string",
"null"
],
"description": "If we provide a polling station result, this URL may be used to provide a user with a back-channel to report inaccurate data."
},
"station": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"geometry": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
},
"description": "A GeoJSON [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) object describing the location of this polling station. Optionally null if we know the address only but can't geocode a location."
},
"properties": {
"type": "object",
"properties": {
"postcode": {
"type": "string",
"description": "Postcode for this polling station"
},
"address": {
"type": "string",
"description": "Address for this polling station"
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) describing the user's polling station (if known)"
}
},
"description": "Results for polling station search"
},
"advance_voting_station": {
"type": [
"object",
"null"
],
"properties": {},
"additionalProperties": false,
"description": "Advance Voting Stations\n\n + `name`: (string) - The name of the Advance Voting Station\n + `address`: (string) - The address of the Advance Voting Station\n + `postcode`: (string) - The postcode of the Advance Voting Station\n + `location`: (object) - A GeoJSON [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) object describing the location of this Advance Voting Station.\n + type: `Point` (string)\n + coordinates: (array[number], fixed-type)\n + `-3.119229`\n + `51.510885`\n + `opening_times`: (array[array], fixed-type):\n + (array)\n + `date`\n + `open`\n + `close`"
},
"notifications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"cancelled_election",
"voter_id"
],
"description": "Type of notification"
},
"detail": {
"type": "string"
},
"url": {
"type": "string"
}
}
},
"description": "Array of notifications to be shown to the user about special conditions to be aware of on this date."
},
"ballots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ballot_paper_id": {
"type": "string",
"description": "Identifier for this ballot"
},
"ballot_title": {
"type": "string",
"description": "Friendly name for this ballot"
},
"poll_open_date": {
"type": "string",
"description": "Polling day for this ballot (ISO 8601)"
},
"elected_role": {
"type": "string",
"description": "Name of the role the winner(s) of this election will assume"
},
"metadata": {
"type": [
"object",
"null"
],
"properties": {},
"description": "Object containing information about special conditions for the user to be aware about (e.g: cancelled elections, voter id pilot). (details TBC)"
},
"cancelled": {
"type": "boolean",
"description": "True if this ballot has been cancelled"
},
"cancellation_reason": {
"type": [
"string",
"null"
],
"enum": [
"NO_CANDIDATES",
"EQUAL_CANDIDATES",
"UNDER_CONTESTED",
"CANDIDATE_DEATH",
"null",
null
],
"description": "If a ballot has been cancelled, this key may hold a codified reason for that ballot's cancellation"
},
"replaced_by": {
"type": [
"string",
"null"
],
"description": "If a ballot has been cancelled (cancelled = true) and rescheduled for a later date, this key will hold the ballot_paper_id of the ballot that replaces it."
},
"replaces": {
"type": [
"string",
"null"
],
"description": "If this ballot replaces another cancelled ballot, this key will hold the ballot_paper_id of the ballot that it replaces."
},
"requires_voter_id": {
"type": [
"string",
"null"
],
"enum": [
"EFA-2002",
"EA-2022",
"pilot-2018",
"pilot-2019",
null
],
"description": "The type of voter ID required in order to vote in this election. Nullable, or one of Electoral Fraud (Northern Ireland) Act 2002, Elections Act 2022 or one of the pilots."
},
"election_id": {
"type": "string",
"description": "Identifier for this ballot's parent election group"
},
"election_name": {
"type": "string",
"description": "Friendly name for this ballot's parent election group"
},
"post_name": {
"type": "string",
"description": "Name of the division or post the winner(s) of this election will represent"
},
"candidates_verified": {
"type": "boolean",
"description": "True if the list of candidates for this election has been confirmed against the nomination papers for this ballot. If this property is False, the candidate list is provisional or unconfirmed."
},
"voting_system": {
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "One of `AMS`, `FPTP`, `PR-CL`, `sv`, `STV`"
},
"name": {
"type": "string",
"description": "The name of this voting system (e.g: \"First-past-the-post\")"
},
"uses_party_lists": {
"type": "boolean",
"description": "True if this voting system uses party lists"
}
},
"description": "The voting system used in this election"
},
"seats_contested": {
"type": "number"
},
"candidates": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"list_position": {
"type": [
"number",
"null"
],
"description": "Numeric position in party list. This value is only relevant to elections using party lists. It will always be null in First-Past-The-post elections."
},
"party": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
},
"previous_party_affiliations": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
}
},
"person": {
"type": "object",
"properties": {
"ynr_id": {
"type": "number"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"description": "Email address for this candidate, if we hold it"
},
"photo_url": {
"type": [
"string",
"null"
],
"description": "URL for a photo of this candidate, if we hold one"
}
}
}
}
},
{
"type": "object",
"properties": {
"list_position": {
"type": [
"number",
"null"
],
"description": "Numeric position in party list. This value is only relevant to elections using party lists. It will always be null in First-Past-The-post elections."
},
"party": {
"type": "object",
"properties": {
"party_id": {
"type": "string"
},
"party_name": {
"type": "string"
}
}
},
"person": {
"type": "object",
"properties": {
"ynr_id": {
"type": "number"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"description": "Email address for this candidate, if we hold it"
},
"photo_url": {
"type": [
"string",
"null"
],
"description": "URL for a photo of this candidate, if we hold one"
}
}
}
}
}
],
"description": "Array of candidate objects describing candidates that will appear on this ballot paper. 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."
}
}
},
"description": "List of ballots happening on this date. It is possible for more than one ballot to occur on the same date. For example, a user may vote in a local council election and mayoral election on the same day."
}
}
},
"description": "An array of date objects (each describing a date on which an election or poll will take place) containing details of relevant ballots, candidates and polling station information"
},
"electoral_services": {
"type": [
"object",
"null"
],
"properties": {
"council_id": {
"type": "string",
"description": "GSS code for this council"
},
"name": {
"type": "string",
"description": "Name of this council"
},
"nation": {
"type": "string",
"description": "Name of nation"
},
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Contact details for the user's local Electoral Services team. If we do not know the user's polling station, this can be used to provide contact info for their local council. This may be `null` if we are not able to determine the user's council."
},
"registration": {
"type": [
"object",
"null"
],
"properties": {
"address": {
"type": "string",
"description": "Contact address for this council"
},
"postcode": {
"type": "string",
"description": "Postcode component of contact address for this council"
},
"email": {
"type": "string",
"description": "Contact email address for this council's Electoral Services team"
},
"phone": {
"type": "string",
"description": "Telephone number for this council's Electoral Services team"
},
"website": {
"type": "string",
"description": "URL for this council's website"
}
},
"description": "Sometimes the contact information for registration and proxy voting is different to the electoral services contact details. Use these if they exist and your users might have questions about voter registration. If this key is null, assume the electoral services contact details can be used for electoral registration related enquiries."
},
"postcode_location": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"properties": {
"type": [
"object",
"null"
],
"properties": {}
},
"geometry": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"coordinates": {
"type": "array",
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
}
}
}
},
"description": "A [GeoJSON Feature](https://tools.ietf.org/html/rfc7946#section-3.2) containing a [Point object](https://tools.ietf.org/html/rfc7946#section-3.1.2) describing the centroid of the input postcode. If providing a map or directions for a polling station journey, use this as the start point. This may be `null` if we are not able to accurately geocode."
}
}
}