Discover the collecting council and required address input for a UK postcode

Start here when the user wants their household bin collection dates. Follow required_input and input_options; ask the user to resolve missing information or ambiguous choices before submitting a lookup. Discovery does not select a property on the user's behalf. Postcode-only by design: a bare postcode is street-level public data, which keeps this endpoint CDN-cacheable. Returns the collecting council and the property list as the council's own checker words it, when we hold it.

get/addresses

Request

  • Base URL: https://whenisbins.com/v1
  • URL: https://whenisbins.com/v1/addresses
  • Auth: one of:
    • none
    • HTTP bearer

Query parameters

postcodestring required
Example:CB4 2HX
qstring
Example:Lanark Road

Road, street or area name the citizen has typed so far, used ONLY to narrow input_options for councils that collect by road or area. It is discovery, never selection: the response returns rows to choose from and never picks one. Ignored by councils that resolve per property. Not a property identifier and never an address: a bare road name is the same street-level public data as the postcode this endpoint already takes.

Headers

If-None-Matchstring
Example:"a1b2c3"

Response

Council resolved; currently serviceable candidate list.

postcodestring required

Normalised form.

required_input'none' | 'property_id' | 'property' | 'street' | 'road_and_locality' | 'street_and_property' | 'settlement' | 'settlement_or_road' | 'normal_weekday' | 'normal_weekday_and_locality' | 'property_type' required

The next field this council's checker needs after the postcode. none means exactly that: this council's own checker resolves the collection from the postcode alone - it names the settlement or round itself - so nothing further should be asked, and POST /lookups accepts the postcode by itself. A property may still be sent and is still matched strictly; it is simply not required. Read this value for each lookup rather than keeping a council's former input contract: South Lanarkshire now requires a property (or a listed property_id), following its property-checker redesign.

postcode_representative'automatic' | 'opt_in' | 'unavailable'

Whether a labelled same-postcode neighbour's schedule may answer when the exact property is not listed. opt_in = only after the citizen explicitly consents, by sending allow_postcode_representative; automatic = this council is measured homogeneous, so the labelled answer is served without asking; unavailable = measured high-harm, and every tier refuses the neighbour answer. Present only at property granularity, where the neighbour concept applies.

candidates_source'council' | 'unavailable' required

council = the list came from the council's own checker. unavailable = no list is currently held; POST free-text property instead. Commercial address data is never republished through this field.

Example response

{
  "postcode": "CB4 2HX",
  "council": {
    "id": "E07000008",
    "name": "Cambridge City Council",
    "lookup_url": "https://www.cambridge.gov.uk/check-when-your-bin-will-be-emptied"
  },
  "candidates": [
    {
      "id": "p:4c5ee6c2f2c7c959",
      "label": "Flat 15, Twickenham Court, Arbury Road, Cambridge, CB4 2HX"
    }
  ],
  "unavailable_candidates": [
    {
      "id": "p:9b1d07a3c4e5f601",
      "label": "The Pavilion, Recreation Ground, Arbury Road, Cambridge, CB4 2HX"
    }
  ],
  "source_notice": {
    "detail": "Your council's bin-day checker is down for maintenance right now. It's the council's own scheduled work, so we can't read your dates until it's back - usually a few hours."
  },
  "input_options": {
    "row_limit": 12,
    "not_listed_value": "__not_listed__",
    "options": [
      {
        "value": "A70--Glenbrook Rd To B7031",
        "label": "A70--Glenbrook Rd To B7031",
        "detail": "Houton, Aglath Road, Breck Road and 5 more",
        "hint": "The stretch of Lanark Road West at your postcode"
      }
    ],
    "not_listed_help": {
      "text": "Road not in the list? Your home may use communal bins.",
      "link_text": "See the council's communal bins service",
      "url": "https://www.edinburgh.gov.uk/recycling-3/communal-bins-service"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.