canonical: https://jentic.com/apis/communitiesuk.github.io/uk-waste-services

# Communitiesuk Waste Services API

Jentic publishes the only available OpenAPI specification for the UK Waste Services API, keeping it validated and agent-ready. The API is a public-sector data interface for UK waste collection: it exposes services, collection tasks, container features, event types and event records, sites (addressable by UPRN), and case records. Look up which bins are collected at an address, when, and what type, plus open new cases (e.g., missed collection reports). Useful for council apps, sustainability dashboards, and AI assistants that answer 'when's my next bin day?'.

## For AI agents

Look up UK waste collection services, schedules, container features, and sites by UPRN, and open service cases through one public API.

## Scope

Does not handle waste pricing, payments, or hazardous-waste licensing - use for waste collection schedule lookup, site and container data, and missed-collection cases only.

## Capabilities

- Find collection sites by UPRN or alternative id via GET `/sites/{id}`
- List waste services available to a site via GET /services
- Retrieve upcoming collection tasks via GET /tasks and `/tasks/{taskId}`
- List container features (bins, sacks) and their feature types attached to a site
- Retrieve event types and event records (collected, missed, contamination)
- Open a new service case via POST /cases for a missed collection or query

## Use cases

### Bin Day Lookup for a Council App

Resolve a household address to a UPRN, call GET `/sites/{id}` to fetch the site record, then GET /tasks filtered by site to return the next collection dates. The result powers a 'when's my bin day?' lookup in a council mobile app or chatbot. The data source is the canonical UK waste services interface, so the answers match what the council uses internally.

Example prompt: Given UPRN 100023456789, GET `/sites/100023456789` and then GET /tasks for that site, returning the next three collection dates

### Missed Collection Reporting

When a resident reports a missed bin, the app calls POST /cases with the site reference, event type, and description. The case is created in the council's waste system without the resident having to phone the council. Combine with GET /event-types to pick the right classification before submission.

Example prompt: POST a new case to /cases with site reference, eventTypeId for 'missed collection', and a free-text description

### Sustainability Dashboard Data Pull

Local sustainability dashboards can pull GET /events filtered by date range to count recycling, contamination, and missed-collection events across a council area. Cross-referenced with /feature-types, this gives a clear picture of bin-by-bin waste behaviour without scraping council websites.

Example prompt: GET /events filtered by date range last_30_days and aggregate counts by eventTypeId

### AI Bin Day Assistant via Jentic

An AI agent connected to Jentic can answer 'what's my bin day?' by resolving the address to a UPRN, calling GET `/sites/{id}`, and surfacing /tasks. No credentials are required - the API is public - and Jentic still standardises the operation discovery and execution. Useful in council voice assistants and sustainability copilots.

Example prompt: Use Jentic to search 'look up uk bin collection schedule', load GET /tasks, and execute for a target site reference

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/sites` | List collection sites |
| GET | `/sites/{id}` | Get a site by UPRN or alternative id |
| GET | `/services` | List waste services |
| GET | `/tasks` | List collection tasks |
| GET | `/events` | List waste collection events |
| GET | `/event-types` | List event type classifications |
| GET | `/features` | List container features |
| POST | `/cases` | Create a new service case |

## Key resources

- **Sites** — Collection sites addressable by UPRN or alternative id
- **Services** — Waste services configured at each site (refuse, recycling, garden)
- **Tasks** — Scheduled collection tasks per site and service
- **Features and Feature Types** — Containers (bins, sacks) and their type definitions
- **Events and Event Types** — Collection event records (collected, missed, contaminated) with classifications
- **Cases** — Service cases such as missed-collection reports - only write surface in the spec

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 71 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 85 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/communitiesuk.github.io/uk-waste-services/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Waste Services API by hand means mapping its site, service, and collection-schedule resources and building your own request handling for each. Through Jentic you install once, import the Waste Services API from the API Directory, and your agent calls it, with no credential to manage since the API is open.
- **Permission scoping:** The Waste Services API puts the site id in the URL path (`/sites/{id}`) and takes case details in the request body, so a rule can pin your agent to reading a specific site while you limit it to the operations it needs. You choose the operations it may call, so you can allow schedule and site lookups while leaving case creation out unless you add it.
- **Credential handling:** The Waste Services API is open and needs no credential, so there is nothing to store, and no key enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a bin collection schedule' or 'report a missed collection', and Jentic returns the matching Waste Services operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GOV.UK Content API** — GOV.UK Content API surfaces government guidance pages that complement the structured waste data.
- **US EPA API** — The EPA API exposes US-side environmental data including some waste-related datasets.
- **Food Standards Agency API** — Sister UK public-sector API for food hygiene ratings, often consumed alongside council services.

## FAQ

### Why is there no official OpenAPI spec for the UK Waste Services API?

The UK government waste services interface is documented in human-readable form on communitiesuk.github.io but does not publish a machine-readable OpenAPI specification. Jentic generates and maintains this spec so AI agents and developers can call it via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Waste Services API require?

The spec defines no security scheme - the API is treated as public read for service and task data. Some council deployments may front the API with their own gateway requiring an API key; check the council-specific deployment URL if 401 responses appear.

### Can I look up bin collection dates for a UK address?

Yes. Resolve the address to a UPRN, call GET `/sites/{id}` to confirm the site exists, then GET /tasks filtered by that site to return upcoming collection dates with their service type.

### How do I report a missed bin collection?

POST /cases creates a new service case. Include the site reference, the eventTypeId for 'missed collection' (look it up via GET /event-types), and a description. The council receives the case in its waste system.

### What are the rate limits for the Waste Services API?

No public rate limit is documented in the spec. In practice individual council deployments may throttle requests; cache site and feature-type lookups, which change rarely, and back off on 429 responses.

### How do I look up a bin schedule through Jentic?

Search Jentic for 'look up uk bin collection schedule', load the schema for GET /tasks, and execute with a site reference. The Jentic Python SDK pattern is await client.search(...), await client.load(...), await client.execute(...).

### Can I limit what my agent is allowed to do with the Waste Services API?

Yes. Because you run Jentic One yourself, your own rules decide which Waste Services operations and inputs the agent may use. You can allow read-only lookups like GET `/sites/{id}`, GET /services, and GET /tasks while leaving case creation via POST /cases out unless you add it. Since the site id travels in the URL path, you can also pin the agent to a specific site so it reads only the collection data you intend.