Waste Services API

Introduction

This API offers a core set of resources and operations for interacting with local council waste and recycling services.

Outstanding issues

A way to discover if a task has been moved from its regular timeslot and why.
Handling of non-property sites, e.g. where the bins are located separately from a building.

ESD Standards

The ESD Standards define all the categories of services that local authorities typically provide. These will be referenced via URL from the Services API, to allow individual council instances of a service to be matched to common service definitions.

Services

Get a list of waste services

get /services

Query parameters

Name	Type	Description
`uprn`	string	Dispalys services related to the property with this UPRN. This also includes basic completed and upcoming collection information and automatically includes related tasks if the property has a parent UPRN.
`full`	boolean	Return the full service information.
`start_date`	date	Filter related tasks that occur after this date.
`end_date`	date	Filter related tasks that start before this date.

Example responses

HTTP code: 200

[
  {
    "frequency": "weekly",
    "@id": "http://example.com/services/1",
    "name": "Recycling service",
    "description": "Please put your recycling box on the street."
  },
  {
    "frequency": "weekly",
    "@id": "http://example.com/services/2",
    "name": "Refuse",
    "description": "Black bins."
  }
]

HTTP code: 400

{
  "code": 400,
  "userMessage": "The parameters were incorrect."
}

Get a single service

get /services/{serviceId}

Query parameters

Name	Type	Description
`uprn`	string	Limit results to those related to the property with this UPRN. This will include the last and next collection task information.

Example responses

HTTP code: 200

{
  "@id": "http://example.com/services/1",
  "feature_types": [
    {
      "color": "black",
      "shape": "wheelie_bin",
      "materials": [
        {
          "@id": "/waste/materials/mixed-recycling",
          "name": "Mixed recyclables"
        }
      ],
      "@type": "ContainerType",
      "lid_color": "green"
    },
    {
      "color": "brown",
      "shape": "caddy",
      "materials": [
        {
          "@id": "/waste/materials/food-waste",
          "name": "Food waste"
        }
      ],
      "@type": "ContainerType"
    }
  ],
  "name": "Mixed recycling",
  "next_collections": [
    {
      "start_date": "2014-05-23T20:00Z",
      "features": [
        {
          "status": "in_service",
          "id": "2140541",
          "@id": "http://example.com/feature-types/2",
          "@type": "WasteContainer",
          "size": 240
        }
      ],
      "@type": "EmptyBinTask"
    }
  ],
  "service_area": {
    "@type": "AdministrativeArea",
    "name": "Anytown"
  },
  "@type": "WasteService",
  "frequency": "weekly",
  "esd_url": "http://id.esd.org.uk/service/1130",
  "provider": {
    "url": "http://www.example.gov.uk",
    "@type": "Organization",
    "name": "Example Council"
  },
  "available_channel": {
    "service_url": "http://www.example.gov.uk/waste",
    "service_phone": {
      "telephone": "0123456789",
      "email": "waste@example.gov.uk",
      "@type": "ContactPoint"
    },
    "name": "Household waste and street maintenance",
    "@type": "ServiceChannel"
  },
  "last_collections": [
    {
      "start_date": "2014-05-23T20:00Z",
      "features": [
        {
          "status": "In use",
          "id": "2140541",
          "@id": "http://example.com/feature-types/1",
          "@type": "WasteContainer",
          "size": 240
        }
      ],
      "@type": "EmptyBinTask"
    }
  ],
  "service_operator": {
    "@type": "Organization",
    "name": "Example Waste Operator Co"
  },
  "id": 1,
  "description": "Please put your recycling wheelie bin on the street."
}

HTTP code: 400

{
  "code": 400,
  "userMessage": "The parameters were incorrect."
}

Tasks

Get a list of tasks

get /tasks

Query parameters

Name	Type	Description
`type`	string	Limit results to a specific task type.
`uprn`	string	Limit results to those related to the property with this UPRN.
`start_date`	date	Filter tasks that occur after this date.
`end_date`	date	Filter tasks that start before this date.
`include`	string	Comma-separated labels of additional information to include. `related` includes all tasks for any parent sites and associated bin stores where possible, e.g. `include=related`. Only applicable when filtering by UPRN.

Example responses

HTTP code: 200

[
  {
    "@id": "http://example.com/tasks/123",
    "@type": "EmptyBinTask",
    "name": "Empty Black 240L"
  },
  {
    "@id": "http://example.com/tasks/124",
    "@type": "EmptyBinTask",
    "name": "Empty Green 240L"
  }
]

HTTP code: 400

{
  "code": 400,
  "userMessage": "The parameters were incorrect."
}

Get a single task

get /tasks/{taskId}

Example responses

HTTP code: 200

{
  "status": "not_started",
  "features": [
    {
      "status": "In use",
      "id": "2140541",
      "type": "http://example.com/feature-types/1",
      "@type": "WasteContainer",
      "size": 240
    }
  ],
  "name": "Empty Black 240L",
  "@type": "EmptyBinTask",
  "location": "http://example.com/sites/1",
  "@id": "http://example.com/tasks/123",
  "start_date": "2015-09-27T21:04:00.743",
  "description": "Empty Black 240L"
}

Event types

Get a list of event types

get /event-types

Example responses

HTTP code: 200

[
  {
    "id": "1",
    "@id": "http://example.com/event-types/1",
    "@type": "EventType",
    "name": "NOT PRESENTED"
  },
  {
    "id": "2",
    "@id": "http://example.com/event-types/2",
    "@type": "EventType",
    "name": "DAMAGED"
  }
]

Get a single event type

get /event-types/{eventTypeId}

Example responses

HTTP code: 200

{
  "id": "2",
  "@id": "http://example.com/event-types/2",
  "@type": "EventType",
  "name": "NOT PRESENTED"
}

Events

Get a list of events

get /events

Query parameters

Name	Type	Description
`uprn`	string	Limit results to those related to the property with this UPRN.
`usrn`	string	Limit results to those related to the street with this USRN.
`start_date`	date	Filter events that occurred after this date.
`end_date`	date	Filter events that occurred before this date.

Example responses

HTTP code: 200

[
  {
    "event_type": "Not presented",
    "usrn": "123456789012",
    "image": "http://example.com/images/123.png",
    "uprn": "123456789012",
    "date_created": "2014-05-23T20:00",
    "geo": {
      "latitude": "40.75",
      "@type": "GeoCoordinates",
      "longitude": "73.98"
    }
  },
  {
    "event_type": "Too heavy",
    "usrn": "123456789012",
    "image": "http://example.com/images/123.png",
    "uprn": "123456789012",
    "date_created": "2014-05-23T20:00",
    "geo": {
      "latitude": "45.75",
      "@type": "GeoCoordinates",
      "longitude": "53.98"
    }
  }
]

Get a single event

get /events/{eventId}

Example responses

HTTP code: 200

{
  "type": "Not presented",
  "features": [
    {
      "color": "#fff",
      "type": {
        "materials": {
          "@id": "/api/materials/paper",
          "name": "paper"
        },
        "name": "240L wheelie bin",
        "reusable": true
      }
    }
  ],
  "usrn": "123456789012",
  "@id": "/api/events/1",
  "image": "http://example.com/images/123.png",
  "@type": "WasteEvent",
  "uprn": "123456789012",
  "geo": {
    "latitude": "40.75",
    "@type": "GeoCoordinates",
    "longitude": "73.98"
  },
  "start_date": "2014-05-23T20:00Z"
}

Features

Get a list of features

get /features

Query parameters

Name	Type	Description
`uprn`	string	Limit results to those related to the property with this UPRN.
`usrn`	string	Limit results to those related to the street with this USRN.

Get a single feature

get /features/{featureId}

Example responses

HTTP code: 200

{
  "type": {
    "description": "240L wheelie bin",
    "materials": {
      "@id": "/api/materials/paper",
      "name": "paper"
    },
    "name": "240L wheelie bin",
    "reusable": true
  },
  "id": "123"
}

Feature types

Get a list of feature types

get /feature-types

Query parameters

Name	Type	Description
`uprn`	string	Limit results to those related to the property with this UPRN.

Get a single feature type

get /feature-types/{featureTypeId}

Example responses

HTTP code: 200

{
  "description": "240L wheelie bin",
  "sizes": [
    180,
    240
  ],
  "materials": {
    "@id": "/api/materials/paper",
    "name": "paper"
  },
  "reusable": true,
  "@id": "http://example.com/container-types/1",
  "@type": "WasteContainerType",
  "name": "240L wheelie bin"
}

Sites

Get a list of sites

get /sites

Query parameters

Name	Type	Description
`usrn`	string	Limit results to those related to the street with this USRN.
`postcode`	string	Limit results to those with the given postcode.

Example responses

HTTP code: 200

{}

Get a single site indexed by UPRN, or another form of index if some sites do not have a UPRN. In that situation, the format of other IDs must not collide with UPRNs.

get /sites/{ID}

Example responses

HTTP code: 200

{
  "usrn": "12345678",
  "geo": {
    "latitude": "40.75",
    "@type": "GeoCoordinates",
    "longitude": "73.98"
  },
  "address": {
    "locality": "Anytown",
    "region": "Anyshire",
    "street": "Acacia Avenue",
    "postcode": "AB1 2CD",
    "@type": "BS7666Address",
    "paon": "1"
  },
  "uprn": "123456789012",
  "attributes": [
    {
      "name": "assisted collection",
      "value": "yes"
    }
  ],
  "parent_uprn": "123456789012",
  "@id": "/sites/1",
  "@type": "Site"
}

Cases

Get a list of cases

get /cases

Query parameters

Name	Type	Description
`uprn`	string	Limit results to cases associated with this UPRN.
`usrn`	string	Limit results to cases within this USRN.
`postcode`	string	Limit results to those with the given postcode.

Example responses

HTTP code: 200

{}

Create a new case

post /cases

Get a case record

get /cases/{caseId}

Example responses

HTTP code: 200

{
  "customer": {
    "name": "Bob Smith"
  },
  "date_created": "2014-05-23T20:00Z",
  "@id": "/cases/1",
  "id": "1"
}