Where Do I Vote?

wheredoivote.co.uk Beta API ¶

Open access to the data powering wheredoivote.co.uk: A website to help people in the UK find their polling station, built by Democracy Club.

More information about the project is available on our website

Note this API is currently in beta and outputs are subject to change.

Usage restrictions

Anonymous users are limited to 1,000 requests per day. If you need a higher limit, please contact us to discuss your usage and obtain an API key.

API Root ¶

/.json

Example: https://wheredoivote.co.uk/api/beta/.json

The initial API entry point for discovering endpoints.

Retrieve the Entry Point ¶

Request GET /.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "councils": "https://wheredoivote.co.uk/api/beta/councils.json",
  "pollingstations": "https://wheredoivote.co.uk/api/beta/pollingstations.json",
  "pollingdistricts": "https://wheredoivote.co.uk/api/beta/pollingdistricts.json"
}

Polling Station Finder ¶

The /postcode and /address endpoints find a user's polling station based on their home address. This allows you to leverage Democracy Club's data to integrate a polling station finder into your website or app.

A 200 OK response from /postcode or /address is an object containing the following top-level keys:

polling_station_known: (boolean) - Do we know where this user should vote?
postcode_location: (object, nullable) - A GeoJSON Feature containing a Point object describing the centroid of the input postcode.
polling_station: (object, nullable) - A GeoJSON polling station feature
addresses: (array) - An array of address objects listing the addresses applicable to this request (if necessary).
council: (object, nullable) - A Council object describing the local authority which covers this postcode. If we do not know the user's polling station, this can be used to provide contact info for their local council. Council may be null if we are not able to determine the user's council.
custom_finder: (string, nullable) - If we don't know a user's polling station, sometimes we can provide the URL of a polling station finder provided by their local council.
report_problem_url: (string, nullable) - If we provide a polling station result, this URL may be used to provide a user with a back-channel to report inaccurate data.
metadata: (object, nullable) - This field may be used to supply additional information about an election, particularly if there is some unusual condition or event for voters to be aware of.
ballots: (array) - An array of ballot objects listing the elections applicable to this request. 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. If ballots is an empty array [], there are no upcoming elections in this area.

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:

Result found: We hold data for this area and all voters with this postcode vote at the same polling station.
Address picker: We hold data for this area but voters with this postcode don't all vote at the same polling station. To find the user's polling station, we must make a second API call to the /address endpoint.
Result not Found: We do not hold data for this area.

Postcode search: Result found ¶

/postcode/{postcode}.json

Example: https://wheredoivote.co.uk/api/beta/postcode/SW1A1AA.json

Parameters

postcode string ( required )

Whitespace in postcodes is ignored, so format may be SW1A1AA or SW1A 1AA

Example: SW1A1AA

When we hold data for this area and all voters with this postcode vote at the same polling station, the following conditions can be observed in the response body:

polling_station_known is true
polling_station is a GeoJSON polling station feature
addresses is an empty array

Postcode search: Result found ¶

Request GET /postcode/{postcode}.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "polling_station_known": true,
  "postcode_location": {
    "type": "Feature",
    "properties": null,
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.277029,
        50.836643
      ]
    }
  },
  "custom_finder": null,
  "addresses": [],
  "polling_station": {
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.269324,
        50.834949
      ]
    },
    "type": "Feature",
    "id": "E07000223.527",
    "properties": {
      "urls": {
        "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
        "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
      },
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
      "station_id": "527",
      "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
      "postcode": "BN43 6WF"
    }
  },
  "council": {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  },
  "report_problem_url": "https://wheredoivote.co.uk/report_problem/?source=api&source_url=%2Fapi%2Fbeta%2FTEST.json",
  "metadata": null,
  "ballots": [
    {
      "ballot_paper_id": "local.adur.buckingham.2018-05-03",
      "ballot_title": "Adur local election Buckingham",
      "poll_open_date": "2018-05-03",
      "elected_role": "Local Councillor",
      "metadata": null,
      "cancelled": false,
      "replaced_by": null,
      "replaces": null
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "polling_station_known": {
      "type": "boolean",
      "description": "Do we know where this user should vote?"
    },
    "postcode_location": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "properties": {
          "type": [
            "object",
            "null"
          ],
          "properties": {}
        },
        "geometry": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "required": [
            "type",
            "coordinates"
          ],
          "additionalProperties": false,
          "description": "A GeoJSON Point object describing the centroid of the input postcode"
        }
      },
      "required": [
        "type",
        "properties",
        "geometry"
      ],
      "additionalProperties": false,
      "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."
    },
    "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."
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "An array of address objects containing the addresses applicable to this request (if necessary)"
    },
    "polling_station": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "geometry": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "description": "A GeoJSON Point object describing the location of this polling station. Optionally null if we do not hold this information"
        },
        "type": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "properties": {
            "urls": {
              "type": "object",
              "properties": {
                "detail": {
                  "type": "string",
                  "description": "URL to retrieve JSON meta-data about this polling station"
                },
                "geo": {
                  "type": "string",
                  "description": "URL to retrieve GeoJSON feature describing this polling station"
                }
              }
            },
            "council": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
            },
            "station_id": {
              "type": "string",
              "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
            },
            "address": {
              "type": "string",
              "description": "Address for this polling station"
            },
            "postcode": {
              "type": "string",
              "description": "Postcode for this polling station"
            }
          }
        }
      },
      "description": "A GeoJSON polling station feature"
    },
    "council": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for this resource"
        },
        "council_id": {
          "type": "string",
          "description": "GSS code for this council"
        },
        "name": {
          "type": "string",
          "description": "Name of 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"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode component of contact address for this council"
        },
        "address": {
          "type": "string",
          "description": "Contact address for this council"
        }
      },
      "description": "A Council object describing the local authority which covers this postcode. If we do not know the user's polling station, this can be used to provide contact info for their local council."
    },
    "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."
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "This field may be used to supply additional information about an election."
    },
    "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"
          },
          "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)."
          },
          "cancelled": {
            "type": "boolean",
            "description": "True if this ballot has been cancelled"
          },
          "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."
          }
        }
      },
      "description": "An array of ballot objects listing the elections applicable to this request"
    }
  }
}

Request GET /postcode/{postcode}.json

Response 400

Headers:

Content-Type: application/json

Body:

{ "detail": "Could not geocode from any source" }

Postcode search: Address picker ¶

/postcode/{postcode}.json

Example: https://wheredoivote.co.uk/api/beta/postcode/SW1A1AA.json

Parameters

postcode string ( required )

Whitespace in postcodes is ignored, so format may be SW1A1AA or SW1A 1AA

Example: SW1A1AA

When we hold data for this area but voters with this postcode don't all vote at the same polling station, the following conditions can be observed in the response body:

polling_station_known is false
polling_station is null
addresses is an array of address objects covered by the input postcode. This can be used to request the user's address and make a second API call to the /address endpoint.

Postcode search: Address picker ¶

Request GET /postcode/{postcode}.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "polling_station_known": false,
  "postcode_location": {
    "type": "Feature",
    "properties": null,
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.26354,
        50.844772
      ]
    }
  },
  "custom_finder": null,
  "addresses": [
    {
      "url": "https://wheredoivote.co.uk/api/beta/address/e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw/",
      "polling_station_id": "527",
      "postcode": "BN436HW",
      "address": "5 Truleigh Way, Shoreham-by-Sea, West Sussex",
      "slug": "e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw",
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/"
    },
    {
      "url": "https://wheredoivote.co.uk/api/beta/address/e07000223-524-2-truleigh-way-shoreham-by-sea-west-sussex-bn436hw?",
      "polling_station_id": "524",
      "postcode": "BN436HW",
      "address": "2 Truleigh Way, Shoreham-by-Sea, West Sussex",
      "slug": "e07000223-524-2-truleigh-way-shoreham-by-sea-west-sussex-bn436hw",
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/"
    }
  ],
  "polling_station": null,
  "council": {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  },
  "report_problem_url": null,
  "metadata": null,
  "ballots": [
    {
      "ballot_paper_id": "local.adur.buckingham.2018-05-03",
      "ballot_title": "Adur local election Buckingham",
      "poll_open_date": "2018-05-03",
      "elected_role": "Local Councillor",
      "metadata": null,
      "cancelled": false,
      "replaced_by": null,
      "replaces": null
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "polling_station_known": {
      "type": "boolean",
      "description": "Do we know where this user should vote?"
    },
    "postcode_location": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "properties": {
          "type": [
            "object",
            "null"
          ],
          "properties": {}
        },
        "geometry": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "required": [
            "type",
            "coordinates"
          ],
          "additionalProperties": false,
          "description": "A GeoJSON Point object describing the centroid of the input postcode"
        }
      },
      "required": [
        "type",
        "properties",
        "geometry"
      ],
      "additionalProperties": false,
      "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."
    },
    "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."
    },
    "addresses": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "Call this URL to get data for this registered address"
            },
            "polling_station_id": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "address": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "council": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "Call this URL to get data for this registered address"
            },
            "polling_station_id": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "address": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "council": {
              "type": "string"
            }
          }
        }
      ],
      "description": "An array of address objects containing the addresses applicable to this request (if necessary)"
    },
    "polling_station": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "A GeoJSON polling station feature"
    },
    "council": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for this resource"
        },
        "council_id": {
          "type": "string",
          "description": "GSS code for this council"
        },
        "name": {
          "type": "string",
          "description": "Name of 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"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode component of contact address for this council"
        },
        "address": {
          "type": "string",
          "description": "Contact address for this council"
        }
      },
      "description": "A Council object describing the local authority which covers this postcode. If we do not know the user's polling station, this can be used to provide contact info for their local council."
    },
    "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."
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "This field may be used to supply additional information about an election."
    },
    "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"
          },
          "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)."
          },
          "cancelled": {
            "type": "boolean",
            "description": "True if this ballot has been cancelled"
          },
          "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."
          }
        }
      },
      "description": "An array of ballot objects listing the elections applicable to this request"
    }
  }
}

Request GET /postcode/{postcode}.json

Response 400

Headers:

Content-Type: application/json

Body:

{ "detail": "Could not geocode from any source" }

Postcode search: Result not Found ¶

/postcode/{postcode}.json

Example: https://wheredoivote.co.uk/api/beta/postcode/SW1A1AA.json

Parameters

postcode string ( required )

Whitespace in postcodes is ignored, so format may be SW1A1AA or SW1A 1AA

Example: SW1A1AA

When we do not hold data for the area described by the postcode provided, the following conditions can be observed in the response body:

polling_station_known is false
polling_station is null
addresses is an empty array

Postcode search: Result not Found ¶

Request GET /postcode/{postcode}.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "polling_station_known": false,
  "postcode_location": {
    "type": "Feature",
    "properties": null,
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.277029,
        50.836643
      ]
    }
  },
  "custom_finder": null,
  "addresses": [],
  "polling_station": null,
  "council": {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  },
  "report_problem_url": null,
  "metadata": null,
  "ballots": [
    {
      "ballot_paper_id": "local.adur.buckingham.2018-05-03",
      "ballot_title": "Adur local election Buckingham",
      "poll_open_date": "2018-05-03",
      "elected_role": "Local Councillor",
      "metadata": null,
      "cancelled": false,
      "replaced_by": null,
      "replaces": null
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "polling_station_known": {
      "type": "boolean",
      "description": "Do we know where this user should vote?"
    },
    "postcode_location": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "properties": {
          "type": [
            "object",
            "null"
          ],
          "properties": {}
        },
        "geometry": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "required": [
            "type",
            "coordinates"
          ],
          "additionalProperties": false,
          "description": "A GeoJSON Point object describing the centroid of the input postcode"
        }
      },
      "required": [
        "type",
        "properties",
        "geometry"
      ],
      "additionalProperties": false,
      "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."
    },
    "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."
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      },
      "description": "An array of address objects containing the addresses applicable to this request (if necessary)"
    },
    "polling_station": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "A GeoJSON polling station feature"
    },
    "council": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for this resource"
        },
        "council_id": {
          "type": "string",
          "description": "GSS code for this council"
        },
        "name": {
          "type": "string",
          "description": "Name of 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"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode component of contact address for this council"
        },
        "address": {
          "type": "string",
          "description": "Contact address for this council"
        }
      },
      "description": "A Council object describing the local authority which covers this postcode. If we do not know the user's polling station, this can be used to provide contact info for their local council."
    },
    "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."
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "This field may be used to supply additional information about an election."
    },
    "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"
          },
          "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)."
          },
          "cancelled": {
            "type": "boolean",
            "description": "True if this ballot has been cancelled"
          },
          "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."
          }
        }
      },
      "description": "An array of ballot objects listing the elections applicable to this request"
    }
  }
}

Request GET /postcode/{postcode}.json

Response 400

Headers:

Content-Type: application/json

Body:

{ "detail": "Could not geocode from any source" }

Address search ¶

/address/{slug}.json

Example: https://wheredoivote.co.uk/api/beta/address/e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw.json

Parameters

slug string ( required )

A unique slug describing a residential address

Example: e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw

In the event that the addresses described by a postcode are not all assigned to the same polling station, an array of address objects will be returned, each of which corresponds to a call to the /address endpoint.

When we make a valid call to the /address endpoint, the following conditions can be observed in the response body:

polling_station_known is true
polling_station is a GeoJSON polling station feature
addresses is an array of length one containing a single address object describing the requested address

Address search ¶

Request GET /address/{slug}.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "polling_station_known": true,
  "postcode_location": {
    "type": "Feature",
    "properties": null,
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.26354,
        50.844772
      ]
    }
  },
  "custom_finder": null,
  "addresses": [
    {
      "url": "https://wheredoivote.co.uk/api/beta/address/e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw/",
      "polling_station_id": "527",
      "postcode": "BN436HW",
      "address": "5 Truleigh Way, Shoreham-by-Sea, West Sussex",
      "slug": "e07000223-527-5-truleigh-way-shoreham-by-sea-west-sussex-bn436hw",
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/"
    }
  ],
  "polling_station": {
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.269324,
        50.834949
      ]
    },
    "type": "Feature",
    "id": "E07000223.527",
    "properties": {
      "urls": {
        "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
        "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
      },
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
      "station_id": "527",
      "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
      "postcode": "BN43 6WF"
    }
  },
  "council": {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  },
  "report_problem_url": "https://wheredoivote.co.uk/report_problem/?source=api&source_url=%2Fapi%2Fbeta%2FTEST.json",
  "metadata": null,
  "ballots": [
    {
      "ballot_paper_id": "local.adur.buckingham.2018-05-03",
      "ballot_title": "Adur local election Buckingham",
      "poll_open_date": "2018-05-03",
      "elected_role": "Local Councillor",
      "metadata": null,
      "cancelled": false,
      "replaced_by": null,
      "replaces": null
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "polling_station_known": {
      "type": "boolean",
      "description": "Do we know where this user should vote?"
    },
    "postcode_location": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "properties": {
          "type": [
            "object",
            "null"
          ],
          "properties": {}
        },
        "geometry": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "required": [
            "type",
            "coordinates"
          ],
          "additionalProperties": false,
          "description": "A GeoJSON Point object describing the centroid of the input postcode"
        }
      },
      "required": [
        "type",
        "properties",
        "geometry"
      ],
      "additionalProperties": false,
      "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."
    },
    "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."
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Call this URL to get data for this registered address"
          },
          "polling_station_id": {
            "type": "string"
          },
          "postcode": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "council": {
            "type": "string"
          }
        }
      },
      "description": "An array of address objects containing the addresses applicable to this request (if necessary)"
    },
    "polling_station": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "geometry": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "type": {
              "type": "string"
            },
            "coordinates": {
              "type": "array",
              "items": [
                {
                  "type": "number"
                },
                {
                  "type": "number"
                }
              ]
            }
          },
          "description": "A GeoJSON Point object describing the location of this polling station. Optionally null if we do not hold this information"
        },
        "type": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "properties": {
          "type": "object",
          "properties": {
            "urls": {
              "type": "object",
              "properties": {
                "detail": {
                  "type": "string",
                  "description": "URL to retrieve JSON meta-data about this polling station"
                },
                "geo": {
                  "type": "string",
                  "description": "URL to retrieve GeoJSON feature describing this polling station"
                }
              }
            },
            "council": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
            },
            "station_id": {
              "type": "string",
              "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
            },
            "address": {
              "type": "string",
              "description": "Address for this polling station"
            },
            "postcode": {
              "type": "string",
              "description": "Postcode for this polling station"
            }
          }
        }
      },
      "description": "A GeoJSON polling station feature"
    },
    "council": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for this resource"
        },
        "council_id": {
          "type": "string",
          "description": "GSS code for this council"
        },
        "name": {
          "type": "string",
          "description": "Name of 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"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode component of contact address for this council"
        },
        "address": {
          "type": "string",
          "description": "Contact address for this council"
        }
      },
      "description": "A Council object describing the local authority which covers this postcode. If we do not know the user's polling station, this can be used to provide contact info for their local council."
    },
    "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."
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ],
      "properties": {},
      "description": "This field may be used to supply additional information about an election."
    },
    "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"
          },
          "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)."
          },
          "cancelled": {
            "type": "boolean",
            "description": "True if this ballot has been cancelled"
          },
          "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."
          }
        }
      },
      "description": "An array of ballot objects listing the elections applicable to this request"
    }
  }
}

Request GET /address/{slug}.json

Response 404

Headers:

Content-Type: application/json

Body:

{ "detail": "Address not found" }

Local Elections May 2019 ¶

On 2 May 2019, local elections take place in England and Northern Ireland.

Ballots

Local council elections will be taking place in 250 local authorities in England. Some areas also have mayoral elections. We are able to provide information about mayoral and local elections down to district/borough ward level. In some areas, there may also be parish/town/community council elections happening. We are currently not able to provide information about these election types.

The ballots array can be used to provide information about scheduled elections. If ballots is an empty array, we do not hold the details of any scheduled election (excluding parish/town/community councils). Where elections are scheduled, ballots may contain multiple objects. For example, a user may vote in a district 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. In the case where a poll is cancelled, the metadata object will contain a key cancelled_election with the information necessary to provide the user with a notification. e.g:

{
...
  "metadata": {
    "cancelled_election": {
      "title": "Cancelled Election",
      "url": "http://www.tamworth.gov.uk/election-news",
      "detail": "The election for a Borough Councillor to represent the Glascote Ward has now been postponed following the sad death of one of the standing candidates."
    }
  }
}

This information will be provided in all responses from the /address and /postcode API endpoints, even if we are not able to provide a polling station result.

Northern Ireland

WhereDoIVote will not hold any polling station data for Northern Ireland in 2019.

If we don't know a user's polling station, sometimes we may provide an external link for more info in the custom_finder key. 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"
}

ID Requirements

All voters in Northern Ireland must present photo ID to vote at a polling station.

Additionally, following on from the pilots in 2018, voters in 11 local authorities in England will be required to present identification in order to vote at a polling station. Each area has slightly different requirements. API responses for a postcode or address in an authority where identification is required will have a key voter_id under the metadata object with the information necessary to provide the user with a notification. e.g:

{
...
  "metadata": {
    "voter_id": {
      "title": "You need to show ID to vote at this election",
      "url": "https://www.woking.gov.uk/voterid",
      "detail": "Voters in Woking will be required to show photo ID before they can vote."
    }
  }
}

This information will be provided in all responses from the /address and /postcode API endpoints, even if we are not able to provide a polling station result. We encourage our API consumers to provide users in these areas with information about the pilots.

Councils ¶

Retrieve details of UK councils/local authorities.

Polling stations and districts are maintained by local councils so all of our data is attached to a council.

Councils Collection: JSON ¶

/councils.json

Example: https://wheredoivote.co.uk/api/beta/councils.json

List all councils. Returns an array of council objects

List All Councils: JSON ¶

Request GET /councils.json

Response 200

Headers:

Content-Type: application/json

Body:

[
  {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Councils: JSON ¶

/councils/{council_id}.json

Example: https://wheredoivote.co.uk/api/beta/councils/W06000015.json

Parameters

council_id string ( required )

GSS code for this council

Example: W06000015

Retrieve meta-data about a council in JSON format.

Retrieve a Council: JSON ¶

Request GET /councils/{council_id}.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
  "council_id": "E07000223",
  "name": "Adur District Council",
  "email": "elections@adur-worthing.gov.uk",
  "phone": "01903 221014/5/6",
  "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
  "postcode": "BN11 1HA",
  "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "URL for this resource"
    },
    "council_id": {
      "type": "string",
      "description": "GSS code for this council"
    },
    "name": {
      "type": "string",
      "description": "Name of 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"
    },
    "postcode": {
      "type": "string",
      "description": "Postcode component of contact address for this council"
    },
    "address": {
      "type": "string",
      "description": "Contact address for this council"
    }
  }
}

Request GET /councils/{council_id}.json

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}

Councils: GeoJSON ¶

/councils/{council_id}/geo.json

Example: https://wheredoivote.co.uk/api/beta/councils/W06000015/geo.json

Parameters

council_id string ( required )

GSS code for this council

Example: W06000015

Retrieve a GeoJSON Feature containing a GIS boundary and meta-data about a council.

Retrieve a Council: GeoJSON ¶

Request GET /councils/{council_id}/geo.json

Response 200

Headers:

Content-Type: application/json

Body:

{
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      "..."
    ]
  },
  "type": "Feature",
  "id": "E07000223",
  "properties": {
    "url": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "council_id": "E07000223",
    "name": "Adur District Council",
    "email": "elections@adur-worthing.gov.uk",
    "phone": "01903 221014/5/6",
    "website": "http://adur-worthing.gov.uk/elections-and-voting/register-to-vote/",
    "postcode": "BN11 1HA",
    "address": "Adur District Council\\nTown Hall\\nChapel Road\\nWorthing\\nWest Sussex"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "geometry": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "coordinates": {
          "type": "array"
        }
      },
      "description": "A GeoJSON object describing the boundary of this area"
    },
    "type": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "GSS code for this council"
    },
    "properties": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "URL for this resource"
        },
        "council_id": {
          "type": "string",
          "description": "GSS code for this council"
        },
        "name": {
          "type": "string",
          "description": "Name of 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"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode component of contact address for this council"
        },
        "address": {
          "type": "string",
          "description": "Contact address for this council"
        }
      }
    }
  }
}

Request GET /councils/{council_id}/geo.json

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}

Polling Stations ¶

The /pollingstations endpoint provides access to the polling station data underpinning our polling station finder.

Polling Stations Collection: JSON ¶

/pollingstations.json?council_id={council_id}

Example: https://wheredoivote.co.uk/api/beta/pollingstations.json?council_id=E07000170

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170

List all polling stations in a local authority. Returns an array of polling station objects

List All Polling Stations in a Local Authority: JSON ¶

Request GET /pollingstations.json?council_id={council_id}

Response 200

Headers:

Content-Type: application/json

Body:

[
  {
    "urls": {
      "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
      "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
    },
    "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "station_id": "527",
    "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
    "postcode": "BN43 6WF"
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Polling Stations Collection: GeoJSON ¶

/pollingstations/geo.json?council_id={council_id}

Example: https://wheredoivote.co.uk/api/beta/pollingstations/geo.json?council_id=E07000170

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170

List all polling stations in a local authority. Returns a GeoJSON FeatureCollection of polling station features

List All Polling Stations in a Local Authority: GeoJSON ¶

Request GET /pollingstations/geo.json?council_id={council_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "type": "FeatureCollection",
  "features": [
    {
      "geometry": {
        "type": "Point",
        "coordinates": [
          -0.269324,
          50.834949
        ]
      },
      "type": "Feature",
      "id": "E07000223.527",
      "properties": {
        "urls": {
          "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
          "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
        },
        "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
        "station_id": "527",
        "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
        "postcode": "BN43 6WF"
      }
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "features": {
      "type": "array"
    }
  }
}

Polling Stations: JSON ¶

/pollingstations.json?council_id={council_id}&station_id={station_id}

Example: https://wheredoivote.co.uk/api/beta/pollingstations.json?council_id=E07000170&station_id=SUM4

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170
station_id string ( required )

Polling Station ID. Polling Station IDs are unique within councils, but are not unique nationally

Example: SUM4

Retrieve meta-data about a polling station in JSON format.

Retrieve a Polling Station: JSON ¶

Request GET /pollingstations.json?council_id={council_id}&station_id={station_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "urls": {
    "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
    "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
  },
  "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
  "station_id": "527",
  "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
  "postcode": "BN43 6WF"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "urls": {
      "type": "object",
      "properties": {
        "detail": {
          "type": "string",
          "description": "URL to retrieve JSON meta-data about this polling station"
        },
        "geo": {
          "type": "string",
          "description": "URL to retrieve GeoJSON feature describing this polling station"
        }
      }
    },
    "council": {
      "type": "string",
      "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
    },
    "station_id": {
      "type": "string",
      "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
    },
    "address": {
      "type": "string",
      "description": "Address for this polling station"
    },
    "postcode": {
      "type": "string",
      "description": "Postcode for this polling station"
    }
  }
}

Request GET /pollingstations.json?council_id={council_id}&station_id={station_id}

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}

Polling Stations: GeoJSON ¶

/pollingstations/geo.json?council_id={council_id}&station_id={station_id}

Example: https://wheredoivote.co.uk/api/beta/pollingstations/geo.json?council_id=E07000170&station_id=SUM4

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170
station_id string ( required )

Polling Station ID. Polling Station IDs are unique within councils, but are not unique nationally

Example: SUM4

Retrieve a GeoJSON Feature describing a polling station.

Retrieve a Polling Station: GeoJSON ¶

Request GET /pollingstations/geo.json?council_id={council_id}&station_id={station_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "geometry": {
    "type": "Point",
    "coordinates": [
      -0.269324,
      50.834949
    ]
  },
  "type": "Feature",
  "id": "E07000223.527",
  "properties": {
    "urls": {
      "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
      "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
    },
    "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "station_id": "527",
    "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
    "postcode": "BN43 6WF"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "geometry": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "coordinates": {
          "type": "array",
          "items": [
            {
              "type": "number"
            },
            {
              "type": "number"
            }
          ]
        }
      },
      "description": "A GeoJSON Point object describing the location of this polling station. Optionally null if we do not hold this information"
    },
    "type": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "properties": {
      "type": "object",
      "properties": {
        "urls": {
          "type": "object",
          "properties": {
            "detail": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about this polling station"
            },
            "geo": {
              "type": "string",
              "description": "URL to retrieve GeoJSON feature describing this polling station"
            }
          }
        },
        "council": {
          "type": "string",
          "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
        },
        "station_id": {
          "type": "string",
          "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
        },
        "address": {
          "type": "string",
          "description": "Address for this polling station"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode for this polling station"
        }
      }
    }
  }
}

Request GET /pollingstations/geo.json?council_id={council_id}&station_id={station_id}

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}

Polling Districts ¶

The /pollingdistricts endpoint provides access to the polling district data underpinning our polling station finder. Where possible a polling district contains a polling station object describing the station which serves this district. This may optionally be null if this district is an orphan district. An orphan district occurrs where we hold the boundary of a polling district but we don't know the corresponding polling station. The polling station which serves a district does not necessarily have to be located inside the district it serves.

Polling Districts Collection: JSON ¶

/pollingdistricts.json?council_id={council_id}

Example: https://wheredoivote.co.uk/api/beta/pollingdistricts.json?council_id=E07000170

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170

List all polling districts in a local authority. Returns an array of polling district objects

List All Polling Districts in a Local Authority: JSON ¶

Request GET /pollingdistricts.json?council_id={council_id}

Response 200

Headers:

Content-Type: application/json

Body:

[
  {
    "urls": {
      "detail": "https://wheredoivote.co.uk/api/beta/pollingdistricts/?council_id=E07000170&district_id=SUM4",
      "geo": "https://wheredoivote.co.uk/api/beta/pollingdistricts/geo/?council_id=E07000170&district_id=SUM4"
    },
    "council": "https://wheredoivote.co.uk/api/beta/councils/E07000170.json",
    "district_id": "SUM4",
    "polling_station": {
      "urls": {
        "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
        "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
      },
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
      "station_id": "527",
      "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
      "postcode": "BN43 6WF"
    }
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Polling Districts Collection: GeoJSON ¶

/pollingdistricts/geo.json?council_id={council_id}

Example: https://wheredoivote.co.uk/api/beta/pollingdistricts/geo.json?council_id=E07000170

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170

List all polling districts in a local authority. Returns a GeoJSON FeatureCollection of polling district features

List All Polling Districts in a Local Authority: GeoJSON ¶

Request GET /pollingdistricts/geo.json?council_id={council_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "type": "FeatureCollection",
  "features": [
    {
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          "..."
        ]
      },
      "type": "Feature",
      "id": "E07000170.SUM4",
      "properties": {
        "urls": {
          "detail": "https://wheredoivote.co.uk/api/beta/pollingdistricts/?council_id=E07000170&district_id=SUM4",
          "geo": "https://wheredoivote.co.uk/api/beta/pollingdistricts/geo/?council_id=E07000170&district_id=SUM4"
        },
        "council": "https://wheredoivote.co.uk/api/beta/councils/E07000170.json",
        "district_id": "SUM4",
        "polling_station": {
          "urls": {
            "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
            "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
          },
          "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
          "station_id": "527",
          "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
          "postcode": "BN43 6WF"
        }
      }
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "features": {
      "type": "array"
    }
  }
}

Polling Districts: JSON ¶

/pollingdistricts.json?council_id={council_id}&district_id={district_id}

Example: https://wheredoivote.co.uk/api/beta/pollingdistricts.json?council_id=E07000170&district_id=SUM4

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170
district_id string ( required )

Polling District ID. Polling District IDs are unique within councils, but are not unique nationally

Example: SUM4

Retrieve meta-data about a polling district in JSON format.

Retrieve a Polling District: JSON ¶

Request GET /pollingdistricts.json?council_id={council_id}&district_id={district_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "urls": {
    "detail": "https://wheredoivote.co.uk/api/beta/pollingdistricts/?council_id=E07000170&district_id=SUM4",
    "geo": "https://wheredoivote.co.uk/api/beta/pollingdistricts/geo/?council_id=E07000170&district_id=SUM4"
  },
  "council": "https://wheredoivote.co.uk/api/beta/councils/E07000170.json",
  "district_id": "SUM4",
  "polling_station": {
    "urls": {
      "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
      "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
    },
    "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
    "station_id": "527",
    "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
    "postcode": "BN43 6WF"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "urls": {
      "type": "object",
      "properties": {
        "detail": {
          "type": "string",
          "description": "URL to retrieve JSON meta-data about this polling district"
        },
        "geo": {
          "type": "string",
          "description": "URL to retrieve GeoJSON feature describing this polling district"
        }
      }
    },
    "council": {
      "type": "string",
      "description": "URL to retrieve JSON meta-data about the council which administers this polling district"
    },
    "district_id": {
      "type": "string",
      "description": "An identifier for this polling district. District IDs are unique within councils, but are not unique nationally"
    },
    "polling_station": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "urls": {
          "type": "object",
          "properties": {
            "detail": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about this polling station"
            },
            "geo": {
              "type": "string",
              "description": "URL to retrieve GeoJSON feature describing this polling station"
            }
          }
        },
        "council": {
          "type": "string",
          "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
        },
        "station_id": {
          "type": "string",
          "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
        },
        "address": {
          "type": "string",
          "description": "Address for this polling station"
        },
        "postcode": {
          "type": "string",
          "description": "Postcode for this polling station"
        }
      },
      "description": "A polling station object describing the station which serves this district. Optionally null if we do not hold this information"
    }
  }
}

Request GET /pollingdistricts.json?council_id={council_id}&district_id={district_id}

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}

Polling Districts: GeoJSON ¶

/pollingdistricts/geo.json?council_id={council_id}&district_id={district_id}

Example: https://wheredoivote.co.uk/api/beta/pollingdistricts/geo.json?council_id=E07000170&district_id=SUM4

Parameters

council_id string ( required )

GSS code for this council

Example: E07000170
district_id string ( required )

Polling District ID. Polling District IDs are unique within councils, but are not unique nationally

Example: SUM4

Retrieve a GeoJSON Feature containing a GIS boundary and meta-data about a polling district.

Retrieve a Polling District: GeoJSON ¶

Request GET /pollingdistricts/geo.json?council_id={council_id}&district_id={district_id}

Response 200

Headers:

Content-Type: application/json

Body:

{
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      "..."
    ]
  },
  "type": "Feature",
  "id": "E07000170.SUM4",
  "properties": {
    "urls": {
      "detail": "https://wheredoivote.co.uk/api/beta/pollingdistricts/?council_id=E07000170&district_id=SUM4",
      "geo": "https://wheredoivote.co.uk/api/beta/pollingdistricts/geo/?council_id=E07000170&district_id=SUM4"
    },
    "council": "https://wheredoivote.co.uk/api/beta/councils/E07000170.json",
    "district_id": "SUM4",
    "polling_station": {
      "urls": {
        "detail": "https://wheredoivote.co.uk/api/beta/pollingstations/?station_id=527&council_id=E07000223",
        "geo": "https://wheredoivote.co.uk/api/beta/pollingstations/geo/?station_id=527&council_id=E07000223"
      },
      "council": "https://wheredoivote.co.uk/api/beta/councils/E07000223/",
      "station_id": "527",
      "address": "Shoreham Free Church Hall\\nBuckingham Road/Gordon Road\\nShoreham-by-Sea",
      "postcode": "BN43 6WF"
    }
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "geometry": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "coordinates": {
          "type": "array"
        }
      },
      "description": "A GeoJSON object describing the boundary of this area"
    },
    "type": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "properties": {
      "type": "object",
      "properties": {
        "urls": {
          "type": "object",
          "properties": {
            "detail": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about this polling district"
            },
            "geo": {
              "type": "string",
              "description": "URL to retrieve GeoJSON feature describing this polling district"
            }
          }
        },
        "council": {
          "type": "string",
          "description": "URL to retrieve JSON meta-data about the council which administers this polling district"
        },
        "district_id": {
          "type": "string",
          "description": "An identifier for this polling district. District IDs are unique within councils, but are not unique nationally"
        },
        "polling_station": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "urls": {
              "type": "object",
              "properties": {
                "detail": {
                  "type": "string",
                  "description": "URL to retrieve JSON meta-data about this polling station"
                },
                "geo": {
                  "type": "string",
                  "description": "URL to retrieve GeoJSON feature describing this polling station"
                }
              }
            },
            "council": {
              "type": "string",
              "description": "URL to retrieve JSON meta-data about the council which administers this polling station"
            },
            "station_id": {
              "type": "string",
              "description": "An identifier for this polling station. Station IDs are unique within councils, but are not unique nationally"
            },
            "address": {
              "type": "string",
              "description": "Address for this polling station"
            },
            "postcode": {
              "type": "string",
              "description": "Postcode for this polling station"
            }
          },
          "description": "A polling station object describing the station which serves this district. Optionally null if we do not hold this information"
        }
      }
    }
  }
}

Request GET /pollingdistricts/geo.json?council_id={council_id}&district_id={district_id}

Response 404

Headers:

Content-Type: application/json

Body:

{
  "detail": "Not found."
}