# WhenIsBins API in one page

UK bin dates. Base URL: `https://whenisbins.com/v1`.
Occasional use needs no key. MCP: `https://whenisbins.com/mcp`.

## One lookup

1. `GET /addresses?postcode=POSTCODE`; read `required_input` and `candidates`.
2. Let the user pick; never guess. `POST /lookups` with the required fields
   and a new saved random `Idempotency-Key`. Reuse both after a lost response.
3. `201` means created, not finished. While queued, running or partial,
   `GET /lookups/{lookup_id}/wait` or `GET /lookups/{lookup_id}`.
   Obey `Retry-After`; poll no faster than 5 seconds. After 2 minutes keep
   the ID; never resubmit because a lookup is slow.
4. Done: show `result.collections[]` and `result.by_date`. Failed: show `detail` and
   `council.lookup_url`. Keep source, address, subscription and date qualifications.
   Never extend dates, infer contents from colour or assume holiday changes.

Dates are `YYYY-MM-DD` in Europe/London; read weekdays from `by_date`.

## Repeat checks

Save `result.property_id`. `GET /schedules/{property_token}` uses it without
`p:`. Send the last ETag in `If-None-Match`. Repeat the lookup only on
`404 no_schedule` or when a needed service has no dates left.

## Evening check-ins and missed bins

Offer opt-in evening check-ins only if your host can schedule them. Agree
dates, time in Europe/London, one-off or ongoing, end date, and how to stop or
change them.

At opt-in, save the agreed due date, bin type and property (UPRN when known;
otherwise confirmed address and property_id). Upcoming dates disappear after
the day passes; this is not cancellation.

A 304 means stored content is unchanged, not that the council re-verified the
date.

No reply is not evidence of a miss. Confirm property, bin and due date with
the owner.

Read the council's current reporting window, disruptions, exclusions and
evidence requirements. Too early? Keep the details and, with permission,
follow up when the window opens and before it closes. If you cannot, give the
owner the council link and saved details.

Check-in consent is not permission to submit. Get separate permission to
report and share personal details with the council.

Use an authorised signed-in session or owner-approved credentials. Hand off to
the owner only challenges you cannot safely complete. Never bypass access
controls or CAPTCHAs.

Check for an existing report in the council account or by reference if you have
access; otherwise ask the owner. After a timeout or no confirmation, reconcile
before retrying.
Deduplicate by property + due date + waste stream (bin type).

Only claim success when the council confirms it; keep its reference and next
steps. Do not promise a return collection: some streams have none.

WhenIsBins supplies dates and a link; it does not schedule check-ins or submit
reports.
Use `council.missed_bin_url` (null if unavailable) through a suitable browser
or integration. Group bins by day; never schedule provisional/interim dates.
[Full guidance](https://whenisbins.com/v1/guide#evening-check-ins-and-missed-bins).