Start or immediately satisfy a household bin collection lookup

The journey's single write. Send postcode plus either free-text property (house number or name — may resolve straight to a result) or a property_id picked from a candidate list. If the address cannot be resolved to exactly one property, the response is 422 with the candidate list embedded and no lookup is created.

Free-text property must name the building: a house number or a house/building name, optionally with its flat/unit before it and its street after it (Flat 2, 60, Kings Road). A flat, floor or unit descriptor on its own — Ground Floor Flat, Flat 2, with or without a street — can never match a council's list, so it is refused with 422 property_identifier_required before any lookup exists (the held candidates ride on that response too).

allow_postcode_representative (Q10) must only be sent after the citizen explicitly consents to neighbour-based dates; it is honoured only when the exact property is not listed.

The lookup row is created before any council work begins. Cache hits return immediately. When recent cold timing predicts a result below ten seconds, when no timing history exists yet, or when the route maintainer's control plane holds the council's active deterministic route healthy (the estimate is then that route's own recent p90, or unknown, whatever the blended history says), the server briefly awaits deterministic work. For predicted longer waits it returns the durable running lookup immediately. Crossing the brief response budget also returns that durable lookup; in either case the same work continues in the background instead of restarting. For journeys that are already in, or historically expected to need, the fallback worker, the estimate also includes current queue depth and recent stage execution time. Queue telemetry can increase but never reduce the historical estimate, and the healthy-route rule never applies once a lookup has reached the browser or Opus stage or a residential handoff.

Previously verified knowledge is looked up by property_id, not by address spelling. A stale result that still contains future dates is returned immediately with its original retrieved_at while a low-priority refresh runs in the background.

post/lookups

Request

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

Headers

Idempotency-Keystring

Random token for safely retrying one lookup creation request. It must contain 1 to 128 visible ASCII characters. Repeating the same request with the same key returns the same Lookup, whether it was answered at once from stored information, joined to a lookup already running, or queued. Reusing a key with a different canonical property request returns 409. A key is remembered for 30 days or until its Lookup is removed; only HMAC digests are retained by shared admission.

Request body

postcodestring required
propertystring

The first line of the address (optional — free text, including the manual-entry flow): a house number or name, optionally preceded by its flat/unit and followed by its street, comma-separated — 15, Rose Cottage, Flat 2, 60, Kings Road. It must carry a house number or a house/building name; a flat, floor or unit descriptor alone is refused with property_identifier_required. Ignored when property_id is given.

property_idstring

A candidate id previously returned; selects the service's stored candidate mapping and is not itself council-address evidence.

streetstring

Street/road name, accepted only when GET /addresses requests a street-based input.

localitystring

Council-recognised town, locality, settlement, island, or legacy collection area when requested by GET /addresses.

normal_weekday'Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday'

Citizen-confirmed normal collection weekday. It is used only inside dates/weeks the council explicitly publishes and is never inferred from a neighbour.

property_type'private_flat_without_bin_store' | 'private_block_with_bin_store' | 'housing_estate' | 'street_bag_collection'

City of London residential service model when requested; rule-level results are not represented as a dated property calendar.

allow_postcode_representativeboolean

Q10 consent flag. Send ONLY after the citizen explicitly opts in to labelled neighbour-based dates; honoured only when the exact property is not listed. Never the default.

Example request

{
  "postcode": "CB4 2HX",
  "property": "15",
  "property_id": "p:4c5ee6c2f2c7c959",
  "street": "Church Road",
  "locality": "Coleraine"
}

Response

Lookup created. status may already be done (cache hit) or queued/running/partial — the body is the same Lookup resource GET /lookups/{lookup_id} serves.

idstring uuid required
status'queued' | 'running' | 'partial' | 'done' | 'failed' required

partial = a usable result is attached while fuller dates (ICS/PDF completion) are still being fetched — check each collection's dates_complete.

created_atstring date-time required
expected_wait_secondsinteger nullable required

Route-aware recent cold-visit p90, rounded up to seconds. Fast deterministic routes supply the initial estimate when they serve at least half of recent cold visits; a deterministic miss promotes the lookup to at least 120 for the browser handoff. Null until five timed cold observations exist in the rolling 84-day window. While the route maintainer's control plane holds the council's active deterministic route healthy, the deterministic-stage estimate is instead the p90 of recent cold successes on the fast routes alone (null below five such successes), whatever the blended history or success rate says. A lookup parked for the residential worker after a council bot-blocked the web host is estimated from that worker's own deterministic stage timing (pickup plus execution, p90) from its first recent sample; with none it shows the handoff.

success_ratenumber double nullable required

Share of cold observations with outcome success in the same rolling window. Null until five eligible cold observations exist. Cache hits are never included.

completed_atstring date-time nullable
problemstring

Present when status is failed (same codes as Problem).

detailstring

Citizen-actionable explanation when failed.

Changes

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