API Reference

Endpoints

The base URL for all API requests is https://bins.felixyeung.com.

Premises by Postcode

Retrieves a list of premises associated with a given postcode.

Endpoint: GET /api/premises
URL: https://bins.felixyeung.com/api/premises?postcode=LS62SE
Query Parameters:
- postcode (required): The postcode for which to retrieve the premises. Example: LS62SE

Example Request

GET https://bins.felixyeung.com/api/premises?postcode=LS62SE

Response

{
  "success": true,
  "timestamp": "2024-08-21T19:37:52.068Z",
  "data": [
    {
      "id": 884874,
      "addressRoom": null,
      "addressNumber": "1",
      "addressStreet": "SHARP MEWS",
      "addressLocality": "MEANWOOD",
      "addressCity": "LEEDS",
      "addressPostcode": "LS6 2SE",
      "updatedAt": "2024-08-21T02:01:05.664Z"
    },
    {
      "id": 842278,
      "addressRoom": null,
      "addressNumber": "2",
      "addressStreet": "SHARP MEWS",
      "addressLocality": "MEANWOOD",
      "addressCity": "LEEDS",
      "addressPostcode": "LS6 2SE",
      "updatedAt": "2024-08-21T02:01:05.664Z"
    },
    ...
  ]
}

Response Schema

success (boolean): Indicates whether the request was successful.
timestamp (string): The time when the response was generated, in ISO 8601 format.
data (array): A list of premises associated with the provided postcode. Each premise object contains:
- id (integer): The unique identifier for the premises.
- addressRoom (string|null): First line of address, if applicable.
- addressNumber (string|null): Second line of address, if applicable.
- addressStreet (string|null): The name of the street, if applicable.
- addressLocality (string): The locality or neighborhood of the premises.
- addressCity (string): The city where the premises are located.
- addressPostcode (string): The postcode of the premises.
- updatedAt (string): The last time the premises information was updated, in ISO 8601 format.

Jobs by Premises ID

Retrieves a list of scheduled bin collection dates for a specific premises.

Endpoint: GET /api/jobs
URL: https://bins.felixyeung.com/api/jobs?premises=842289
Query Parameters:
- premises (required): The ID of the premises for which to retrieve the jobs. Example: 842289

Example Request

GET https://bins.felixyeung.com/api/jobs?premises=842289

Response

{
  "success": true,
  "timestamp": "2024-08-21T19:40:26.057Z",
  "data": {
    "id": 842289,
    "addressRoom": null,
    "addressNumber": "6",
    "addressStreet": "SHARP MEWS",
    "addressLocality": "MEANWOOD",
    "addressCity": "LEEDS",
    "addressPostcode": "LS6 2SE",
    "updatedAt": "2024-08-21T02:01:05.664Z",
    "jobs": [
      {
        "bin": "BROWN",
        "date": "2024-07-26"
      },
      {
        "bin": "GREEN",
        "date": "2024-07-29"
      },
      {
        "bin": "BLACK",
        "date": "2024-08-05"
      },
      {
        "bin": "BROWN",
        "date": "2024-08-09"
      },
      ...
    ]
  }
}

Response Schema

success (boolean): Indicates whether the request was successful.
timestamp (string): The time when the response was generated, in ISO 8601 format.
data (object): Contains details of the premises and its associated jobs. Fields include:
- id (integer): The unique identifier for the premises.
- addressRoom (string|null): First line of address, if applicable.
- addressNumber (string|null): Second line of address, if applicable.
- addressStreet (string|null): The name of the street, if applicable.
- addressLocality (string): The locality or neighborhood of the premises.
- addressCity (string): The city where the premises are located.
- addressPostcode (string): The official postcode of the premises.
- updatedAt (string): The last time the premises information was updated, in ISO 8601 format.
- jobs (array): A list of job objects, each containing:
  - bin (string): The type of bin scheduled for collection.
  - date (string): The scheduled collection date for the bin, in YYYY-MM-DD format.

Error Handling

For both endpoints, if the request fails (e.g., due to an invalid postcode or premises ID), the API will return a JSON object containing an error message along with a success: false flag. Additional properties may be included in the response object, depending on the error.

Rate Limits

To ensure fair usage and maintain optimal performance, the Household Waste Collection API enforces rate limits on all API requests. These limits control the number of requests that can be made within a specified time frame.

Current Rate Limit

At the time of writing, the API allows 10 requests within a 10-second timeframe. This means you can make up to 10 requests every 10 seconds without being rate limited.

How Rate Limits Work

Each API request includes several headers that provide information about your current rate limit status. These headers allow you to monitor and manage your API usage effectively.

Rate Limit Headers

When you make a request to the API, the following headers are included in the response:

X-RateLimit-Success: Indicates whether the request was successful (true) or denied due to rate limiting (false).
X-RateLimit-Limit: The maximum number of requests allowed within the current time window.
X-RateLimit-Remaining: The number of requests you have remaining in the current time window.
X-RateLimit-Reset: The time (milliseconds elapsed since the epoch) when the current rate limit window will reset.

Example Response Headers

X-RateLimit-Success: true
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1724634840000

Managing Your Usage

To avoid hitting the rate limit, monitor the X-RateLimit-Remaining header. If this value is low, consider reducing the frequency of your requests until the X-RateLimit-Reset time. Once the rate limit window resets, your X-RateLimit-Remaining count will be replenished.

If you exceed the rate limit, subsequent requests will be denied until the rate limit resets. In such cases, the X-RateLimit-Success header will return false.

By staying within the rate limits, you can ensure continued access to the API without interruptions.

Introduction Calendar Subscription