Democracy Club Developers

Democracy Club Developer API 

This API is currently in private beta. All requests must be made with an API key. If you're interested in working with the data, contact us for an API key. Usage must comply with our terms of use.

Postcode search 

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 /address endpoint.

Postcode search: No upcoming ballots 

/postcode/{postcode}

Parameters

  • postcode string ( required )

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

    Example: SW1A1AA

Example of a response when there are no upcoming ballots.

In this case address_picker is false and dates is an empty array.

Postcode search: No upcoming ballots 

Request GET /postcode/{postcode}
Response 200
Headers:
Content-Type: application/json
Body:
{
  "address_picker": false,
  "addresses": [],
  "dates": [],
  "electoral_services": {
    "council_id": "W06000015",
    "name": "Cardiff Council",
    "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"
        },
        "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."
    },
    "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."
    }
  }
}
Request GET /postcode/{postcode}
Response 400
Headers:
Content-Type: application/json
Body:
{ "detail": "Could not geocode from any source" }

Postcode search: Results found 

/postcode/{postcode}

Parameters

  • postcode string ( required )

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

    Example: SW1A1AA

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.

Postcode search: Results found 

Request GET /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"
          }
        }
      },
      "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",
          "ballot_url": "https://developers.democracyclub.org.uk/api/v1/local.cardiff.pontprennauold-st-mellons.2017-05-04/",
          "poll_open_date": "2017-05-04",
          "elected_role": "Local Councillor",
          "metadata": null,
          "cancelled": false,
          "replaced_by": null,
          "replaces": null,
          "election_id": "local.cardiff.2017-05-04",
          "election_name": "Cardiff local election",
          "post_name": "Pontprennau/Old St. Mellons",
          "candidates_verified": false,
          "candidates": [
            {
              "list_position": null,
              "party": {
                "party_id": "party:90",
                "party_name": "Liberal Democrats"
              },
              "person": {
                "ynr_id": 23417,
                "name": "David Keigwin",
                "absolute_url": "https://whocanivotefor.co.uk/person/23417/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",
                "absolute_url": "https://whocanivotefor.co.uk/person/8071/joel-williams",
                "email": null,
                "photo_url": "https://static-candidates.democracyclub.org.uk/media/images/images/8071.png"
              }
            }
          ],
          "wcivf_url": "https://whocanivotefor.co.uk/elections/local.cardiff.2017-05-04/post-UTE:W05000900/pontprennauold-st-mellons"
        }
      ]
    }
  ],
  "electoral_services": {
    "council_id": "W06000015",
    "name": "Cardiff Council",
    "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"
          },
          "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"
                },
                "ballot_url": {
                  "type": "string",
                  "description": "API link for more detailed info about this ballot from the /elections endpoint"
                },
                "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"
                },
                "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."
                },
                "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."
                },
                "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"
                            }
                          }
                        },
                        "person": {
                          "type": "object",
                          "properties": {
                            "ynr_id": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            },
                            "absolute_url": {
                              "type": "string",
                              "description": "Link for more (human-readable) information about this candidate"
                            },
                            "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"
                            },
                            "absolute_url": {
                              "type": "string",
                              "description": "Link for more (human-readable) information about this candidate"
                            },
                            "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."
                },
                "wcivf_url": {
                  "type": "string",
                  "description": "Link for more (human-readable) information about this ballot"
                }
              }
            },
            "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"
        },
        "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."
    },
    "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."
    }
  }
}
Request GET /postcode/{postcode}
Response 400
Headers:
Content-Type: application/json
Body:
{ "detail": "Could not geocode from any source" }

Postcode search: Address picker 

/postcode/{postcode}

Parameters

  • postcode string ( required )

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

    Example: SW1A1AA

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.

Postcode search: Address picker 

Request GET /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": "w06000015-100100106448",
      "url": "http://developers.democracyclub.org.uk/api/v1/address/w06000015-100100106448"
    },
    {
      "address": "26 DUNCAN CLOSE, ST. MELLONS, CARDIFF",
      "postcode": "CF3 1NP",
      "slug": "w06000015-100100106458",
      "url": "http://developers.democracyclub.org.uk/api/v1/address/w06000015-100100106448"
    }
  ],
  "dates": [],
  "electoral_services": {
    "council_id": "W06000015",
    "name": "Cardiff Council",
    "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"
        },
        "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."
    },
    "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."
    }
  }
}
Request GET /postcode/{postcode}
Response 400
Headers:
Content-Type: application/json
Body:
{ "detail": "Could not geocode from any source" }

Address search 

Address search 

/address/{slug}

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 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.

Address search 

Request GET /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"
          }
        }
      },
      "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",
          "ballot_url": "https://developers.democracyclub.org.uk/api/v1/local.cardiff.pontprennauold-st-mellons.2017-05-04/",
          "poll_open_date": "2017-05-04",
          "elected_role": "Local Councillor",
          "metadata": null,
          "cancelled": false,
          "replaced_by": null,
          "replaces": null,
          "election_id": "local.cardiff.2017-05-04",
          "election_name": "Cardiff local election",
          "post_name": "Pontprennau/Old St. Mellons",
          "candidates_verified": false,
          "candidates": [
            {
              "list_position": null,
              "party": {
                "party_id": "party:90",
                "party_name": "Liberal Democrats"
              },
              "person": {
                "ynr_id": 23417,
                "name": "David Keigwin",
                "absolute_url": "https://whocanivotefor.co.uk/person/23417/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",
                "absolute_url": "https://whocanivotefor.co.uk/person/8071/joel-williams",
                "email": null,
                "photo_url": "https://static-candidates.democracyclub.org.uk/media/images/images/8071.png"
              }
            }
          ],
          "wcivf_url": "https://whocanivotefor.co.uk/elections/local.cardiff.2017-05-04/post-UTE:W05000900/pontprennauold-st-mellons"
        }
      ]
    }
  ],
  "electoral_services": {
    "council_id": "W06000015",
    "name": "Cardiff Council",
    "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"
          },
          "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"
                },
                "ballot_url": {
                  "type": "string",
                  "description": "API link for more detailed info about this ballot from the /elections endpoint"
                },
                "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"
                },
                "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."
                },
                "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."
                },
                "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"
                            }
                          }
                        },
                        "person": {
                          "type": "object",
                          "properties": {
                            "ynr_id": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            },
                            "absolute_url": {
                              "type": "string",
                              "description": "Link for more (human-readable) information about this candidate"
                            },
                            "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"
                            },
                            "absolute_url": {
                              "type": "string",
                              "description": "Link for more (human-readable) information about this candidate"
                            },
                            "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."
                },
                "wcivf_url": {
                  "type": "string",
                  "description": "Link for more (human-readable) information about this ballot"
                }
              }
            },
            "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"
        },
        "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."
    },
    "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."
    }
  }
}
Request GET /address/{slug}
Response 404
Headers:
Content-Type: application/json
Body:
{ "detail": "Address not found" }

Elections 

The /elections/ endpoint gives access to Democracy Club's full database of elections.

Each election object is assigned an Election Identifier

Democracy Club's election model is hierarchical. The lowest level (or most detailed) election object is called the ballot id and describes a single ballot paper. Each level above this is a group id. For example the ballot local.worcestershire.bewdley.2017-05-04 is a child of the (organisation) group local.worcestershire.2017-05-04 which is in turn a child of the (election) group local.2017-05-04.

An election object is described fully in the JSON schema, but broadly contains information about:

  • The election or group itself

  • The object's position in the hierarchy

  • The organisation (e.g: parliament or council) holding the election

  • The division (e.g: constituency or ward) that a candidate will be elected to represent

List Elections 

/elections/

Parameters

  • coords string ( optional )

    Pass a lat/lon string as ?coords={lat},{lon} to find elections covering the given coordinates. For lookup by postcode/address, use the /postcode endpoint.

    Example: 52.290719,-1.935395

  • current string ( optional )

    Pass ?current=1 to return only elections which will happen in the near future (we may hold info on candidates or polling stations) or happened in the recent past (we may hold results). Usually this is an election whose polling date is either in the next 90 days or was in the last 20 days, but we may sometimes make an editorial decision that a major election (e.g: a scheduled general election) is "current" for a wider window than this.

    Example: 1

  • future string ( optional )

    Pass ?future=1 to return only elections whose polling date is in the future

    Example: 1

  • identifier_type string ( optional )

    Pass ?identifier_type=election, ?identifier_type=organisation or ?identifier_type=ballot to return only election groups, organisation groups or ballot objects.

    Example: ballot

  • limit number ( optional )

    Pass ?limit={num} to specify number of election objects to return. Use with offset to page over results

    Example: 20

  • offset number ( optional )

    Pass ?offset={num} to specify Election object to start from. Use with limit to page over results

    Example: 20

List or filter all election objects.

List elections 

Request GET /elections/
Response 200
Headers:
Content-Type: application/json
Body:
{
  "count": 18014,
  "next": "https://developers.democracyclub.org.uk/api/v1/elections/?limit=100&offset=100",
  "previous": null,
  "results": [
    {
      "election_id": "naw.c.alyn-and-deeside.by.2018-02-06",
      "election_title": "Alyn and Deeside (Constituencies) by-election",
      "poll_open_date": "2018-02-06",
      "election_type": {
        "name": "National Assembly for Wales elections",
        "election_type": "naw"
      },
      "election_subtype": {
        "name": "Constituencies",
        "election_subtype": "c"
      },
      "organisation": {
        "official_identifier": "naw",
        "organisation_type": "naw",
        "organisation_subtype": "",
        "official_name": "Welsh assembly",
        "common_name": "Welsh assembly",
        "slug": "naw",
        "territory_code": "WLS",
        "election_name": "National Assembly for Wales election",
        "start_date": "1999-05-06",
        "end_date": null
      },
      "group": "naw.c.2018-02-06",
      "identifier_type": "ballot",
      "children": [],
      "elected_role": "Assembly Member",
      "seats_contested": 1,
      "division": {
        "divisionset": {
          "start_date": "2016-04-13",
          "end_date": null,
          "legislation_url": null,
          "consultation_url": null,
          "short_title": "2016 Boundaries",
          "notes": "Auto imported from http://mapit.mysociety.org"
        },
        "name": "Alyn and Deeside",
        "official_identifier": "gss:W09000007",
        "slug": "alyn-and-deeside",
        "division_type": "WAC",
        "division_election_sub_type": "c",
        "seats_total": null,
        "territory_code": "WLS"
      },
      "voting_system": {
        "slug": "FPTP",
        "name": "First-past-the-post",
        "uses_party_lists": false
      },
      "current": false,
      "metadata": null,
      "cancelled": false,
      "replaces": null,
      "replaced_by": null
    }
  ]
}
Schema:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Total number of election objects"
    },
    "next": {
      "type": [
        "string",
        "null"
      ],
      "description": "Link to next page of results"
    },
    "previous": {
      "type": [
        "string",
        "null"
      ],
      "description": "Link to previous page of results"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "election_id": {
            "type": "string",
            "description": "Identifier for this election"
          },
          "election_title": {
            "type": "string",
            "description": "Friendly name for this election"
          },
          "poll_open_date": {
            "type": "string",
            "description": "Polling day for this election (ISO 8601)"
          },
          "election_type": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Friendly name for this election type"
              },
              "election_type": {
                "type": "string",
                "description": "Identifier slug for this election type (a component of the identifier)"
              }
            }
          },
          "election_subtype": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "Friendly name for this election subtype"
              },
              "election_subtype": {
                "type": "string",
                "description": "Identifier slug for this election subtype (a component of the identifier)"
              }
            },
            "description": "Election subtype provides details for the subtype in Additional Member System elections (Welsh Assembly, Scottish Parliament, Greater London Assembly). This key will be null for other election types"
          },
          "organisation": {
            "type": "object",
            "properties": {
              "official_identifier": {
                "type": "string",
                "description": "An identifier for this organisation. Where possible, we'll us a code from the relevant [gov.uk register](https://www.registers.service.gov.uk/)."
              },
              "organisation_type": {
                "type": "string",
                "enum": [
                  "combined-authority",
                  "europarl",
                  "gla",
                  "local-authority",
                  "naw",
                  "nia",
                  "parl",
                  "police-area",
                  "sp"
                ]
              },
              "organisation_subtype": {
                "type": "string",
                "enum": [
                  "CA",
                  "CC",
                  "CTY",
                  "LBO",
                  "MD",
                  "NMD",
                  "SRA",
                  "UA"
                ],
                "description": "If organisation_type = 'local-authority', an additional description of what type of local authority this is from the [gov.uk local authority registers](https://www.registers.service.gov.uk/category/regional-and-local-government). Empty string for other organisation types"
              },
              "official_name": {
                "type": "string",
                "description": "Long name of the organisation"
              },
              "common_name": {
                "type": "string",
                "description": "Short name of the organisation"
              },
              "slug": {
                "type": "string",
                "description": "Identifier slug for this organisation (a component of the identifier)"
              },
              "territory_code": {
                "type": "string",
                "enum": [
                  "ENG",
                  "WLS",
                  "SCT",
                  "NIR",
                  "GBN"
                ]
              },
              "election_name": {
                "type": "string",
                "description": "Base name for elections to this organisation"
              },
              "start_date": {
                "type": "string",
                "description": "Start date (ISO 8601) for this organisation, or the first date on which we can validly create an election for it"
              },
              "end_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "End date (ISO 8601) for this organisation, or the last date on which we can validly create an election for it. Null when the organisation is current"
              }
            },
            "description": "Object describing the body the winner of this election will be elected to"
          },
          "group": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifier for this election's parent group. If this is an election group (group_type = 'election'), this will be null"
          },
          "identifier_type": {
            "type": "string",
            "description": "One of 'election', 'organisation' or 'ballot'."
          },
          "children": {
            "type": "array",
            "description": "Identifiers for any elections belonging to this election group. Empty array for ballots"
          },
          "elected_role": {
            "type": "string",
            "description": "Name of the role the winner(s) of this election will assume"
          },
          "seats_contested": {
            "type": [
              "number",
              "null"
            ],
            "description": "Number of seats contested in this election. Populated only for ballots"
          },
          "division": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "divisionset": {
                "type": "object",
                "properties": {
                  "start_date": {
                    "type": "string",
                    "description": "Start date (ISO 8601) for this Division Set, or the first date on which we can validly create an election for a division in it"
                  },
                  "end_date": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "End date (ISO 8601) for this Division Set, or the last date on which we can validly create an election for a division in it. Null when the Division Set is current"
                  },
                  "legislation_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Link to the legislation which defined the Division Set, if we hold it"
                  },
                  "consultation_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Link to the process which defined the Division Set, if we hold it."
                  },
                  "short_title": {
                    "type": "string",
                    "description": "Short name of the Division Set"
                  },
                  "notes": {
                    "type": "string",
                    "description": "Notes on the source of the boundaries"
                  }
                },
                "description": "Electoral divisions change over time. A Division Set represents a group of boundaries which are in use over a period of time."
              },
              "name": {
                "type": "string",
                "description": "Name of this division"
              },
              "official_identifier": {
                "type": "string",
                "description": "Identifier for this division. Where possible this will be a GSS code prefixed by `gss:`. If a GSS code is not available yet, we'll assign the division a temporary ID"
              },
              "slug": {
                "type": "string",
                "description": "Identifier slug for this division (a component of the identifier)"
              },
              "division_type": {
                "type": "string",
                "description": "An Ordnance Survey AREA_CODE describing what type of division this is. See https://www.ordnancesurvey.co.uk/docs/technical-specifications/boundary-line-technical-specification.pdf"
              },
              "division_election_sub_type": {
                "type": "string",
                "description": "Identifier slug for this election subtype (a component of the identifier)."
              },
              "seats_total": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Total number of seats in this division (may not all be elected in a single election)"
              },
              "territory_code": {
                "type": "string",
                "enum": [
                  "ENG",
                  "WLS",
                  "SCT",
                  "NIR"
                ]
              }
            },
            "description": "Object describing the division (e.g: constituency or ward) the winner of this election will represent, if applicable. Election groups don't have a division. Also the ballot object for some election types don't have a division (e.g: Directly elected mayors and Police and Crime Commissioners represent an organisation directly)"
          },
          "voting_system": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string",
                "description": "Identifier slug for voting system used by this election"
              },
              "name": {
                "type": "string",
                "description": "Friendly description for voting system used by this election"
              },
              "uses_party_lists": {
                "type": "boolean",
                "description": "True if this voting system uses party lists"
              }
            }
          },
          "current": {
            "type": "boolean",
            "description": "True if this election will happen in the near future or happened in the recent past. Usually this is an election whose polling date is either in the next 90 days or was in the last 20 days, but we may sometimes make an editorial decision that a major election is \"current\" for a wider window than this."
          },
          "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"
          },
          "replaces": {
            "type": [
              "string",
              "null"
            ],
            "description": "If a ballot replaces another cancelled ballot, this key will hold the identifier of the ballot that it replaces."
          },
          "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 identifier of the ballot that replaces it."
          }
        }
      },
      "description": "Array of Election objects"
    }
  }
}

Single election 

/elections/{id}

Parameters

  • id string ( required )

    A Democracy Club election ID

    Example: naw.c.alyn-and-deeside.by.2018-02-06

Retrieve a single election object by id.

Single election 

Request GET /elections/{id}
Response 200
Headers:
Content-Type: application/json
Body:
{
  "election_id": "naw.c.alyn-and-deeside.by.2018-02-06",
  "election_title": "Alyn and Deeside (Constituencies) by-election",
  "poll_open_date": "2018-02-06",
  "election_type": {
    "name": "National Assembly for Wales elections",
    "election_type": "naw"
  },
  "election_subtype": {
    "name": "Constituencies",
    "election_subtype": "c"
  },
  "organisation": {
    "official_identifier": "naw",
    "organisation_type": "naw",
    "organisation_subtype": "",
    "official_name": "Welsh assembly",
    "common_name": "Welsh assembly",
    "slug": "naw",
    "territory_code": "WLS",
    "election_name": "National Assembly for Wales election",
    "start_date": "1999-05-06",
    "end_date": null
  },
  "group": "naw.c.2018-02-06",
  "identifier_type": "ballot",
  "children": [],
  "elected_role": "Assembly Member",
  "seats_contested": 1,
  "division": {
    "divisionset": {
      "start_date": "2016-04-13",
      "end_date": null,
      "legislation_url": null,
      "consultation_url": null,
      "short_title": "2016 Boundaries",
      "notes": "Auto imported from http://mapit.mysociety.org"
    },
    "name": "Alyn and Deeside",
    "official_identifier": "gss:W09000007",
    "slug": "alyn-and-deeside",
    "division_type": "WAC",
    "division_election_sub_type": "c",
    "seats_total": null,
    "territory_code": "WLS"
  },
  "voting_system": {
    "slug": "FPTP",
    "name": "First-past-the-post",
    "uses_party_lists": false
  },
  "current": false,
  "metadata": null,
  "cancelled": false,
  "replaces": null,
  "replaced_by": null
}
Schema:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "election_id": {
      "type": "string",
      "description": "Identifier for this election"
    },
    "election_title": {
      "type": "string",
      "description": "Friendly name for this election"
    },
    "poll_open_date": {
      "type": "string",
      "description": "Polling day for this election (ISO 8601)"
    },
    "election_type": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Friendly name for this election type"
        },
        "election_type": {
          "type": "string",
          "description": "Identifier slug for this election type (a component of the identifier)"
        }
      }
    },
    "election_subtype": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Friendly name for this election subtype"
        },
        "election_subtype": {
          "type": "string",
          "description": "Identifier slug for this election subtype (a component of the identifier)"
        }
      },
      "description": "Election subtype provides details for the subtype in Additional Member System elections (Welsh Assembly, Scottish Parliament, Greater London Assembly). This key will be null for other election types"
    },
    "organisation": {
      "type": "object",
      "properties": {
        "official_identifier": {
          "type": "string",
          "description": "An identifier for this organisation. Where possible, we'll us a code from the relevant [gov.uk register](https://www.registers.service.gov.uk/)."
        },
        "organisation_type": {
          "type": "string",
          "enum": [
            "combined-authority",
            "europarl",
            "gla",
            "local-authority",
            "naw",
            "nia",
            "parl",
            "police-area",
            "sp"
          ]
        },
        "organisation_subtype": {
          "type": "string",
          "enum": [
            "CA",
            "CC",
            "CTY",
            "LBO",
            "MD",
            "NMD",
            "SRA",
            "UA"
          ],
          "description": "If organisation_type = 'local-authority', an additional description of what type of local authority this is from the [gov.uk local authority registers](https://www.registers.service.gov.uk/category/regional-and-local-government). Empty string for other organisation types"
        },
        "official_name": {
          "type": "string",
          "description": "Long name of the organisation"
        },
        "common_name": {
          "type": "string",
          "description": "Short name of the organisation"
        },
        "slug": {
          "type": "string",
          "description": "Identifier slug for this organisation (a component of the identifier)"
        },
        "territory_code": {
          "type": "string",
          "enum": [
            "ENG",
            "WLS",
            "SCT",
            "NIR",
            "GBN"
          ]
        },
        "election_name": {
          "type": "string",
          "description": "Base name for elections to this organisation"
        },
        "start_date": {
          "type": "string",
          "description": "Start date (ISO 8601) for this organisation, or the first date on which we can validly create an election for it"
        },
        "end_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "End date (ISO 8601) for this organisation, or the last date on which we can validly create an election for it. Null when the organisation is current"
        }
      },
      "description": "Object describing the body the winner of this election will be elected to"
    },
    "group": {
      "type": [
        "string",
        "null"
      ],
      "description": "Identifier for this election's parent group. If this is an election group (group_type = 'election'), this will be null"
    },
    "identifier_type": {
      "type": "string",
      "description": "One of 'election', 'organisation' or 'ballot'."
    },
    "children": {
      "type": "array",
      "description": "Identifiers for any elections belonging to this election group. Empty array for ballots"
    },
    "elected_role": {
      "type": "string",
      "description": "Name of the role the winner(s) of this election will assume"
    },
    "seats_contested": {
      "type": [
        "number",
        "null"
      ],
      "description": "Number of seats contested in this election. Populated only for ballots"
    },
    "division": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "divisionset": {
          "type": "object",
          "properties": {
            "start_date": {
              "type": "string",
              "description": "Start date (ISO 8601) for this Division Set, or the first date on which we can validly create an election for a division in it"
            },
            "end_date": {
              "type": [
                "string",
                "null"
              ],
              "description": "End date (ISO 8601) for this Division Set, or the last date on which we can validly create an election for a division in it. Null when the Division Set is current"
            },
            "legislation_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "Link to the legislation which defined the Division Set, if we hold it"
            },
            "consultation_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "Link to the process which defined the Division Set, if we hold it."
            },
            "short_title": {
              "type": "string",
              "description": "Short name of the Division Set"
            },
            "notes": {
              "type": "string",
              "description": "Notes on the source of the boundaries"
            }
          },
          "description": "Electoral divisions change over time. A Division Set represents a group of boundaries which are in use over a period of time."
        },
        "name": {
          "type": "string",
          "description": "Name of this division"
        },
        "official_identifier": {
          "type": "string",
          "description": "Identifier for this division. Where possible this will be a GSS code prefixed by `gss:`. If a GSS code is not available yet, we'll assign the division a temporary ID"
        },
        "slug": {
          "type": "string",
          "description": "Identifier slug for this division (a component of the identifier)"
        },
        "division_type": {
          "type": "string",
          "description": "An Ordnance Survey AREA_CODE describing what type of division this is. See https://www.ordnancesurvey.co.uk/docs/technical-specifications/boundary-line-technical-specification.pdf"
        },
        "division_election_sub_type": {
          "type": "string",
          "description": "Identifier slug for this election subtype (a component of the identifier)."
        },
        "seats_total": {
          "type": [
            "number",
            "null"
          ],
          "description": "Total number of seats in this division (may not all be elected in a single election)"
        },
        "territory_code": {
          "type": "string",
          "enum": [
            "ENG",
            "WLS",
            "SCT",
            "NIR"
          ]
        }
      },
      "description": "Object describing the division (e.g: constituency or ward) the winner of this election will represent, if applicable. Election groups don't have a division. Also the ballot object for some election types don't have a division (e.g: Directly elected mayors and Police and Crime Commissioners represent an organisation directly)"
    },
    "voting_system": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string",
          "description": "Identifier slug for voting system used by this election"
        },
        "name": {
          "type": "string",
          "description": "Friendly description for voting system used by this election"
        },
        "uses_party_lists": {
          "type": "boolean",
          "description": "True if this voting system uses party lists"
        }
      }
    },
    "current": {
      "type": "boolean",
      "description": "True if this election will happen in the near future or happened in the recent past. Usually this is an election whose polling date is either in the next 90 days or was in the last 20 days, but we may sometimes make an editorial decision that a major election is \"current\" for a wider window than this."
    },
    "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"
    },
    "replaces": {
      "type": [
        "string",
        "null"
      ],
      "description": "If a ballot replaces another cancelled ballot, this key will hold the identifier of the ballot that it replaces."
    },
    "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 identifier of the ballot that replaces it."
    }
  }
}
Request GET /elections/{id}
Response 404
Headers:
Content-Type: application/json
Body:
{ "detail": "Not found" }

Sandbox outputs 

At any time the live data we expose via the API reflects reality. This means that there are conditions which are important to model in your application but are difficult to replicate using live data. To make it easier to replicate a variety of behaviours in test/development we provide a 'sandbox API' at http://developers.democracyclub.org.uk/api/v1/sandbox which serves fake but plausible data. The following test postcodes and address slugs are valid in the sandbox. Each one represents a different scenario:

  • postcode AA11AA - No upcoming ballots

  • postcode AA12AA - One upcoming ballot, station known, with candidates

  • postcode AA12AB - One upcoming ballot, station not known, with candidates

  • postcode AA13AA - We need to show the user an address picker. Each of the following /address calls has different polling station info:

  • postcode AA14AA - Four upcoming ballots across 3 future dates with a cancellation:

    • mayor.lewisham.2018-05-03 - Mayoral election
    • local.lewisham.blackheath.2018-05-03 - This election is cancelled and rescheduled on 2018-05-10
    • local.lewisham.blackheath.2018-05-10 - This election replaces the cancelled local.lewisham.blackheath.2018-05-03
    • parl.lewisham-east.by.2018-06-14 - This election is scheduled but we don't know of any candidates yet
  • postcode AA15AA - Northern Ireland. This example shows the custom_finder key in use. We can use this to redirect users to Electoral Office for Northern Ireland's website for polling station data.

Notes and Tips 

Polling Stations

  • If we don't know a user's polling station, sometimes we may provide an external link for more info in custom_finder. This will always be populated for users in Northern Ireland where the Electoral Office for Northern Ireland run their own service. e.g:
{
...
  "custom_finder": "http://www.eoni.org.uk/Offices/Postcode-Search-Results?postcode=BT28%202EY"
}
  • If we don't know a user's polling station and custom_finder is not populated, the contact details in the electoral_services object can be used to provide contact details for the user's local electoral services team.

Ballots and Candidates

  • It is possible for more than one ballot to occur on the same date, so a ballots array may contain many objects. For example, a user may vote in a local council election and mayoral election on the same day.

  • Occasionally a ballot needs to be cancelled. The most common reason for this is if one of the candidates dies between close of nominations and polling day, but there are other situations where this may happen. Remember to check the cancelled flag on ballot objects.

  • In an election using party lists, candidates should be shown to users grouped by party and ordered by list_position within parties. In an election which uses party lists, the candidates array is sorted by party and list_position within parties. For other election types it is sorted alphabetically by candidate name.

Notifications

We'll use the notifications array to provide additional info to be shown to the user about special conditions to be aware of on this date e.g: identification requirements, or a cancelled poll.

ID Requirements

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

Additionally, there have been several trials in England to test introducing ID requirements more widely. API responses for a postcode or address in an authority where identification is required will include this information in the notifications array. e.g:

{
...
  "notifications": [
    {
      "url": "http://www.eoni.org.uk/Vote/Voting-at-a-polling-place",
      "title": "You need to show photographic ID to vote in this election",
      "detail": "Voters in Northern Ireland are required to show one form of photo ID, like a passport or driving licence.",
      "type": "voter_id"
    }
  ]
}

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.

Cancelled Polls

Sometimes a scheduled poll may be cancelled. This is usuaully either because the election is uncontested or due to death of a candidate. API responses for a postcode or address in an authority where identification is required will include this information in the notifications array. e.g:

{
...
  "notifications": [
    {
      "url": null,
      "type": "cancelled_election",
      "detail": "The poll for this election will not take place because it is uncontested.",
      "title": "Uncontested Election"
    }
  ]
}