---
title: "Only the subscription URL for an address selected after postcode search"
method: GET
path: "/calendar-url"
---

# Only the subscription URL for an address selected after postcode search

`GET /calendar-url`

## Request

- Base URL: `https://whenisbins.com/v1`
- URL: `https://whenisbins.com/v1/calendar-url`
- Auth: one of:
  - none
  - HTTP bearer

First call GET /addresses with a postcode, let the user choose from
candidates, then send the selected candidate's id as property_id here.
No intervening POST /lookups or schedule download is needed. The
selected address must already have a usable saved schedule. If the
postcode response cannot offer property_id choices, follow the ordinary
lookup flow for the council's required input instead.

A read-only lookup of an existing public calendar. Supply exactly one
identifier form: uprn, property_id, or gss plus council_id. No other
query parameters, repeated parameters or written addresses are accepted.
The identity must resolve uniquely, and its saved schedule must pass
the existing date and cache-usability gates. Provisional, undated and
postcode-representative results cannot supply a link here.
This operation never discovers addresses, contacts a council, creates
a lookup or queues a refresh, even for stale or missing schedules.
Public feeds must be enabled. The URL is the one a Schedule's
calendar_url names for the same property: a verified UPRN, either the
property's own or the one verified UPRN its UPRN-shaped council
identifier maps to under the same GSS; otherwise the council's
property identifier. A URL that would not resolve uniquely is refused.

The separate allowance is 100 requests per rolling 24 hours per
anonymous network (IPv4 address or IPv6 /64), or per bearer token.
Successful and unsuccessful reads, including HEAD, consume it;
ordinary read allowance is not consumed. The preceding GET /addresses
uses the standard address-discovery allowance. Outer traffic protections
still apply. Like other request quotas this is process-local and
resets on restart; the boundary minute is conservatively retained.
Responses use no-store. Save a successful URL for subscription;
calendar fetches have their own existing behaviour and read limits.

## Query parameters

- `uprn` string
- `property_id` string
- `gss` string
- `council_id` string

## Response `200`

Only the absolute subscription URL, as plain text, without a JSON wrapper.

## Other responses

- `400`: Malformed input (e.g. `invalid_postcode`).
- `401`: Supplied bearer token is malformed, unknown or revoked, or a token is missing during a token-only hold (`unauthorized`).
- `404`: No usable public calendar, unknown or ambiguous identity, or public feeds disabled (`no_schedule`). No work is started.
- `405`: The path exists but not with this method. Every resource below answers exactly one method; the `Allow` header names it.
- `429`: Request, provider or new-work allowance exceeded; optional limit_scope and token_request_url explain the limit.
- `500`: An unexpected fault on our side (`server_error`). Nothing is implied about whether the work started; retry with the same `Idempotency-Key` where one applies.
- `503`: Required service configuration, a dependency, or shared lookup admission is temporarily unavailable (`service_unavailable`).

---

[API](https://skmtc.dev/whenisbins/apis/whenisbins-uk-bin-collection-api-for-apps-and-ai-agents.md) · [All operations](https://skmtc.dev/whenisbins/apis/whenisbins-uk-bin-collection-api-for-apps-and-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/whenisbins/apis/whenisbins-uk-bin-collection-api-for-apps-and-ai-agents/revisions/6e4a960474a4?raw)