# WhenIsBins

> UK bin collection dates for apps and AI agents, using councils' own published information.

Use WhenIsBins for "When is my next bin collection?", "Which bin is collected
this week?" and "When is my recycling collected?" Start with a UK postcode and
the user's supplied or confirmed address. Responses contain JSON collection
dates, waste types, council sources and address/date confidence information.
Coverage and available dates vary; up to 92 days does not promise a full calendar.
WhenIsBins is independent, not a council. The API does not report missed bins,
create reminders, arrange collections or prove garden-waste subscription.

council.missed_bin_url, when not null, is the council's own page for reporting
a missed collection, which may help if you are assisting someone whose bin
was not emptied; missed_bin_checked_at is when that link was last verified,
not a live check. The council's page sets its own reporting rules.

Personal occasional queries are free without an account or API key. Commercial users
must contact hello@whenisbins.com before using the API, including through MCP.
For regular personal use request a free bearer token. A postcode alone may not identify a property.
Do not guess an address or dates; preserve confidence, completeness and consent.

- [One-page quickstart](https://whenisbins.com/v1/quickstart.md): the happy path and recurring checks in one page. Read this first.
- [Guide](https://whenisbins.com/v1/guide.md): when to use the API, agent quickstart, complete JavaScript example, answer qualifications and limits.
- [Missed-bin reporting links](https://whenisbins.com/v1/guide#missed-bin-reporting-links): what council.missed_bin_url and missed_bin_checked_at mean.
- [OpenAPI](https://whenisbins.com/v1/openapi.yaml): authoritative JSON contract.
- [Reference](https://whenisbins.com/v1/docs): browsable reference.
- [JavaScript client](https://whenisbins.com/v1/client.mjs): bounded polling and idempotent submission.
- [OpenClaw skill](https://whenisbins.com/v1/openclaw-skill.md): instructions for one-off user-requested queries.
- MCP server: https://whenisbins.com/mcp (Streamable HTTP, no sign-in). Four tools: find_addresses, get_collections, check_lookup, get_schedule. See the guide's "MCP server" section.
- [MCP quickstart](https://whenisbins.com/v1/mcp-quickstart.md): the two tool calls, repeat checks and limits in one page, for a client that has added the MCP server.

POST /v1/lookups creates work. GET /v1/lookups/{id} polls that same job.
First use GET /v1/addresses to discover required input and resolve ambiguity.
Save the selected request and Idempotency-Key before submitting. HTTP 201 does
not mean done. Respect Retry-After; snapshot polls are at least five seconds
apart. Wait for at most two minutes, then retain the ID for a user-requested
continuation. Never turn polling into repeated new submissions.
Preserve partial/provisional and subscription qualifications. Do not infer bin
contents from colour, calculate holiday shifts or expand weekday patterns.
Interpret today and tomorrow in Europe/London and include the council source.
The service can be busy or unable to answer. Do not promise eventual success.
Reading documentation does not install a tool: fresh lookups need permitted
HTTP POST support, or an MCP client connected to https://whenisbins.com/mcp.