Using bin collection data as JSON

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.

Each bin collection has it's own JSON endpoint, which is automatically generated from the original iCal data. Using the ical.js library, every time a website deployment build occurs, the JSON data is generated from the original iCal source data.

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 collectionDates key

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

Example schema using the Friday G4 2024/25 calendar.

{
    "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": [
        ...
    ]
}

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

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

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

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

"revisedCollectionDates": [
    "2024-03-30",
    "2024-05-25"
]

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

An example collection item under an regular occurrence schedule:

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

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

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

Note: 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.

A collection item provides the following keys:

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

JSON endpoints

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.

Refuse/Recycling Collections

Monday G1 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_g1_bin_schedule.json

Monday G2 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_g2_bin_schedule.json

Monday G3 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_g3_bin_schedule.json

Monday G4 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_g4_bin_schedule.json

Tuesday G1 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_g1_bin_schedule.json

Tuesday G2 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_g2_bin_schedule.json

Tuesday G3 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_g3_bin_schedule.json

Tuesday G4 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_g4_bin_schedule.json

Wednesday G1 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_g1_bin_schedule.json

Wednesday G2 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_g2_bin_schedule.json

Wednesday G3 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_g3_bin_schedule.json

Wednesday G4 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_g4_bin_schedule.json

Thursday G1 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_g1_bin_schedule.json

Thursday G2 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_g2_bin_schedule.json

Thursday G3 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_g3_bin_schedule.json

Thursday G4 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_g4_bin_schedule.json

Friday G1 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_g1_bin_schedule.json

Friday G2 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_g2_bin_schedule.json

Friday G3 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_g3_bin_schedule.json

Friday G4 Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_g4_bin_schedule.json

Garden Waste Collections

Monday A Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_a_garden_bin_schedule.json

Monday F Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_monday_f_garden_bin_schedule.json

Tuesday B Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_b_garden_bin_schedule.json

Tuesday G Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_tuesday_g_garden_bin_schedule.json

Wednesday C Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_c_garden_bin_schedule.json

Wednesday H Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_wednesday_h_garden_bin_schedule.json

Thursday D Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_d_garden_bin_schedule.json

Thursday I Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_thursday_i_garden_bin_schedule.json

Friday E Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_e_garden_bin_schedule.json

Friday J Calendar JSON URL:

https://www.gbcbincalendars.co.uk/json/gedling_borough_council_friday_j_garden_bin_schedule.json