json-endpoints.html

---
title: Using bin collection data as JSON
description: How to use Gedling Borough Council bin collection calendar data in the JSON format.
layout: default
---

<h1 class="h2">{{ page.title }}</h1>

<p>The original idea behind this project was to provide Gedling Borough Council bin collection data in the iCalender format for importing or subscribing as calendar data. JSON is also another well used and portable format which other applications can use which this project supports.</p>

<p>Each bin collection has it's own JSON endpoint, which is automatically generated from the original iCal data. Using the <a href="https://github.com/kewisch/ical.js">ical.js library</a>, every time a website deployment build occurs, the JSON data is generated from the original iCal source data.</p>

<p>The JSON schema is described below. Each JSON endpoint provides a header with various meta information for unit tests and reference purposes. The main data most applications will be interested in is the <code>collectionDates</code> key</p>

<ul>
    <li><code>filename</code> - The JSON endpoint filename, this is the original iCal filename, but with <code>.json</code>.</li>
    <li><code>name</code> - This is the iCalendar name taken from <code>X-WR-CALNAME</code>.</li>
    <li><code>description</code> - This is iCalendar description taken from <code>X-WR-CALDESC</code>.</li>
    <li><code>collectionWeekday</code> - The assigned weekday of the collection schedule.</li>
    <li><code>collectionType</code> - The type of collection, this can be either <code>Refuse</code> or <code>Garden</code>.</li>
    <li><code>icalPath</code> - The root relative iCal filepath.</li>
    <li><code>jsonPath</code> - The root relative JSON filepath.</li>
    <li><code>lastGenerated</code> - The last time the JSON data was generated from a deployment.</li>
    <li><code>lastModified</code> - The last time the calendar data was modified, this is based on the modified date of the original iCal source.</li>
    <li><code>totalCollections</code> - The total items within the <code>collectionDates</code> key.</li>
    <li><code>totalChangedCollections</code> - The total of one-off changed collection dates that differ from the <code>collectionWeekday</code>.</li>
    <li><code>revisedCollectionDates</code> - An array containing collection dates which have been changed as a map.</li>
    <li><code>collectionDates</code> - The array containing all bin collection dates, with occurrences expanded to single events.</li>
</ul>

<p>Example schema using the Friday G4 2024/25 calendar.</p>

{% highlight json %}
{
    "filename": "gedling_borough_council_friday_g4_bin_schedule.json",
    "name": "Gedling Borough Council Bin Day 2024/25 Friday G4",
    "description": "https://apps.gedling.gov.uk/refuse/data/FridayG4-2025.pdf",
    "collectionWeekday": "Friday",
    "collectionType": "Refuse",
    "icalPath": "ical/gedling_borough_council_friday_g4_bin_schedule.ics",
    "jsonPath": "json/gedling_borough_council_friday_g4_bin_schedule.json",
    "lastGenerated": "2024-12-08T02:31:31.886Z",
    "lastModified": "2024-12-03T20:16:15.895Z",
    "totalCollections": 52,
    "totalChangedCollections": 2,
    "revisedCollectionDates": [
        ...
    ],
    "collectionDates": [
        ...
    ]
}
{% endhighlight %}

<p>The <code>revisedCollectionDates</code> key is an array that contains any date which is a singular/one-off occurrence.</p>

<p>For refuse collections, this is an array map between the usual collection date as a key and revised date as the value:</p>

{% highlight json %}
"revisedCollectionDates": [
    {
      "2024-12-27": "2024-12-28"
    },
    {
      "2025-01-03": "2025-01-04"
    }
]
{% endhighlight %}

<p>For garden waste collections, a flat array of the list of the dates which are different from the usual weekday value is used:</p>

{% highlight json %}
"revisedCollectionDates": [
    "2024-03-30",
    "2024-05-25"
]
{% endhighlight %}

<p>The <code>collectionDates</code> key contains all the VEVENT data from the original calendar source. Any VEVENT that uses RRULE for repeating occurrences are expanded in full.</p>

<p>An example collection item under an regular occurrence schedule:</p>

{% highlight json %}
{
    "name": "Black Bin Day",
    "alternativeName": "Black Bin",
    "weekday": "Friday",
    "isOccurrence": true,
    "type": "black-bin",
    "collectionDate": "2024-12-13",
    "isChangedCollection": false
  }
{% endhighlight %}

<p>An example collection item that is a one-off i.e. changed collection date due to a national holiday:</p>

{% highlight json %}
{
    "name": "Green Bin Day (Changed Collection)",
    "alternativeName": "Green Bin",
    "weekday": "Saturday",
    "isOccurrence": false,
    "type": "green-bin",
    "collectionDate": "2025-01-04",
    "isChangedCollection": true
  }
{% endhighlight %}

<p><b>Note:</b> A change from 2023/24 is the revised collection date can be the following day, rather than being being one or more days before the usual collection date. For Wednesday, Thursday and Friday schedules some revised dates are the next day after the original collection date.</p>

<p>A collection item provides the following keys:</p>

<ul>
    <li><code>name</code> - Original iCal VEVENT <code>SUMMARY</code> value.</li>
    <li><code>alternativeName</code> - Modified VEVENT <code>SUMMARY</code> value. E.g. shorter value for use by other applications if required.</li>
    <li><code>weekday</code> - The weekday of the collection date. If <code>isChangedCollection</code> is true the day will differ to the overall <code>collectionWeekday</code> calendar value.</li>
    <li><code>isOccurrence</code> - A boolean to indicate if the collection date is part of a occurrence rule or not.</li>
    <li><code>type</code> - A consistent type value for referencing in other contexts.</li>
    <li><code>collectionDate</code> - The collection date formatted as Y-m-d.</li>
    <li><code>isChangedCollection</code> - A boolean to denote if the collection date is outside of the usual sequence.</li>
</ul>

<h2 class="h3 mt-4">JSON endpoints</h2>

<p>All the live JSON endpoints are available below. The URL paths for these endpoints can be used in other software without any imposed restrictions or limitations.</p>

{% for type in site.data.calendars.bin_collections %}
    <div class="{% if forloop.last %}mb-0{% else %}mb-5{% endif %}">
        <h3 class="h4 mb-3">{{ type.name }}</h3>
        {% for weekday in type.collections %}
            {%- for collection in weekday[1] -%}
                <div class="mb-4">
                    <span class="fw-bold d-block mb-2">{{ weekday[0] }} {{ collection.name }} Calendar JSON URL:</span>
                    {%- highlight html -%}
                        {{- collection.json | absolute_url -}}
                    {%- endhighlight -%}
                </div>
            {%- endfor -%}
        {% endfor %}
    </div>
{% endfor %}