---
name: whenisbins
description: Find upcoming UK household rubbish, recycling, food waste and garden waste collection dates by postcode and confirmed address. Use WhenIsBins for questions such as "When is my next bin collection?", "Which bin is collected this week?" or "When is my recycling collected?" Returns council sources and date confidence; occasional queries need no account or API key. Does not report missed bins, create reminders, arrange collections or prove garden-waste subscription.
metadata: {"openclaw":{"emoji":"♻️","homepage":"https://whenisbins.com/v1/guide","primaryEnv":"WHENISBINS_API_TOKEN"}}
---

Read https://whenisbins.com/v1/guide.md for the live API contract and limits.
WhenIsBins is an independent service using councils' own published information.
Coverage and available dates vary by council and property. Results may include
dates up to 92 days ahead; a complete calendar is not guaranteed.
Occasional queries need no registration or API token. A regular integration
may use WHENISBINS_API_TOKEN from its secret configuration. Never put a token
in a URL, chat response or log. Request higher access at hello@whenisbins.com.

## Installed helper

The complete package includes a dependency-free Node 22+ helper. Read
`{baseDir}/scripts/whenisbins.mjs`, `{baseDir}/api-agent-cli.mjs` and
`{baseDir}/api-example-client.mjs` before its first use. With an already
permitted exec tool, run:

```sh
node "{baseDir}/scripts/whenisbins.mjs" --help
node "{baseDir}/scripts/whenisbins.mjs" check
```

`check` reads only the fixed waste-type list. Other commands take JSON on
stdin. Keep full addresses and tokens out of command arguments; stdin, tool
output and lookup identifiers are private too. Retain only what the task and
its requested continuation need. The token is an optional environment variable,
not a JSON field.

| Command | JSON on stdin | Result |
|---|---|---|
| `addresses` | `{"postcode":"POSTCODE"}`; optional `q` narrows a road/area | Council, required fields and choices |
| `key` | No input | Random `idempotencyKey`; save before POST |
| `submit` | `{"input":{...requested fields...},"idempotencyKey":"saved key"}` | Lookup in `data`, key and `retryAfterSeconds` |
| `wait` | `{"lookupId":"returned id","retryAfterSeconds":5}` | `lookup` and `timedOut`; no POST |
| `schedule` | `{"propertyId":"saved opaque id"}` | Address-free schedule; may trigger a bounded refresh |

Pass the actual submission's `retryAfterSeconds` to `wait`. A done or failed
submission is terminal: do not wait. Preserve the submission result if waiting
times out, especially a partial answer; an empty pending placeholder must not
replace it. Each wait lasts at most two minutes. A further wait needs the
user's continuation. If a timed-out wait returns `retryAfterSeconds`, save
when that delay expires and pass the remaining seconds to a later wait.
Save the key and exact input before submitting so an
uncertain POST can be retried with both unchanged.

If only this standalone SKILL.md was downloaded, the helper files are absent:
use permitted HTTP tools for the journey below. A full package also includes
`{baseDir}/references/guide.md`; use the live guide for current limits.

## Lookup journey

1. Ask for a postcode if the user has not provided one. GET
   https://whenisbins.com/v1/addresses?postcode=POSTCODE using URL encoding.
2. Follow required_input and input_options. Select a property only when the
   user's address matches unambiguously. Ask for clarification when needed;
   never choose a similarly numbered property or assume a flat number.
3. POST the requested JSON fields to https://whenisbins.com/v1/lookups.
   Supply a random Idempotency-Key and reuse that key and body if retrying
   after a lost response. Do not send email or request reminders.
4. Inspect status. If still queued, running or partial, GET the returned
   lookup id, respecting Retry-After and waiting at least five seconds between
   polls. Stop after two minutes and report that the lookup is still pending;
   keep its id so a user-requested continuation can poll the same lookup.
   Never submit a new lookup merely because the original is slow.
5. For a completed answer, report the actual dates, bin names, council source,
   retrieval time and relevant confidence/completeness or subscription notes.
   Preserve any representative-address qualification and required consent.
   A partial answer or projected date must remain labelled. Never invent
   dates, extrapolate a recurrence, or promise that a pending lookup will work.
   A null retrieval time means unknown, not now. Empty dates for a service
   mean dates are unavailable, not that there are no collections. A settled
   lookup with missing dates needs a fresh user-requested lookup, not indefinite
   polling or an automatic second submission.

Interpret today, tomorrow and this week in Europe/London. A collection date
does not establish a collection time or put-out deadline. Do not infer bin
contents from colour or calculate an assumed bank-holiday shift. Provisional
neighbour answers must never become a final answer after the exact lookup
fails, or be used for reminders, feeds or a persistent schedule cache.

On 429, explain the allowance and Retry-After; optionally give the free-token
request address. Do not rotate IPs or credentials or create parallel requests
to get around the limit. On 503, explain that capacity is temporarily unavailable.

OpenClaw web_fetch only performs GET. Use an already permitted HTTP/exec tool
for POST; if none is enabled, explain what capability is missing. Do not turn
a browser challenge into a bypass attempt. The auditable JavaScript client at
https://whenisbins.com/v1/client.mjs supports addresses(), submit(), wait() and
schedule(); inspect and save it before executing, rather than piping a remote
script into a shell. No package installation is needed for the client.