Building an API Wrapper for Fost Plus: A Journey into Waste Collection Automation

Introduction

Building open-source projects often leads to solving specific real-world problems. In this article, I’ll walk you through my journey of creating a TypeScript wrapper for the Fost Plus API. This wrapper facilitates easy access to waste collection data, allowing users to generate iCalendar files for scheduled trash pickups based on location and date range.

The project, now available as an npm package, is designed to simplify interactions with the Fost Plus waste collection API. It enables seamless querying for zip codes, streets, and generating iCal files to remind users about trash pickup schedules. Below, I’ll cover the features of the package, the process behind its development, and guide you through how to use it in your own projects.

What is the FostPlus API Wrapper?

The FostPlus API Wrapper is a utility designed to streamline access to waste collection data in Belgium. Fost Plus handles recycling and waste management, and this package allows developers to integrate that data into their applications. The key feature is the ability to retrieve waste collection schedules for specific zip codes, streets, and houses and convert the data into an iCalendar file format, which can be imported into calendar applications.

Why Did I Build It?

After realizing how valuable a system for tracking waste collection schedules could be, I decided to simplify the process by providing an API wrapper. The need to access data like zip codes, street names, and schedules from the Fost Plus API was clear, but there wasn’t a simple, open-source tool that packaged all these operations together.

Moreover, waste collection reminders in the form of iCalendar files are incredibly useful. The iCal format is widely supported by all major calendar applications (Google Calendar, Apple Calendar, Outlook), making it an ideal solution for this problem.

Core Features of the API Wrapper

Here are some key features of the FostPlus API Wrapper:

  • Retrieve Waste Collection Data: Access information about waste collection dates for specific zip codes, streets, and house numbers.
  • Generate iCalendar Files: Automatically generate .ics files containing waste collection reminders.
  • Easy Integration: Written in TypeScript, making it type-safe and developer-friendly.

How to Install the FostPlus API Wrapper

You can install the package using npm. Here’s the command:

npm install @leventhan/fostplus-api-wrapper

Once installed, it’s easy to start using the wrapper in your project.

Step-by-Step Usage Guide

Let’s take a look at how you can use this package to fetch waste collection data and create an iCalendar file. Below is an example that covers all the steps, from installation to generating the iCalendar file.

1. Set Up API Consumer Key

First, you'll need a consumer key from Fost Plus. While this key is publicly accessible (and can be scraped for testing), it's essential for authenticating your requests.

const FostPlusAPI = require('@leventhan/fostplus-api-wrapper').default;
const fs = require('fs');
const path = require('path');

const api = new FostPlusAPI({
  xConsumer: process.env.CONSUMER_UNIQUE_KEY || 'your_consumer_id',
});

2. Get Available Zip Codes

To retrieve waste collection data, you first need to fetch available zip codes. Use the getZipcodes method, passing a valid zip code.

const zipcodesResponse = await api.getZipcodes("2880");
const selectedZipcode = zipcodesResponse.items[0];
const zipcodeId = selectedZipcode.id;
console.log(`Selected Zipcode ID: ${zipcodeId}`);

3. Fetch Street Data

Once you have the zipcodeId, fetch the street data using getStreets. The street name is passed as a parameter:

const streetsResponse = await api.getStreets("Sint-Amandsesteenweg", zipcodeId);
const selectedStreet = streetsResponse.items[0];
const streetId = selectedStreet.id;
console.log(`Selected Street ID: ${streetId}`);

4. Define Date Range and House Number

Define the date range for which you want the waste collection data and specify a house number:

const fromDate = "2024-10-19";
const untilDate = "2024-11-02";
const houseNumber = "80";

5. Generate the iCalendar File

Use the generateICalendar method to create an iCalendar file for the selected zip code, street, house number, and date range:

const icsContent = await api.generateICalendar(zipcodeId, streetId, houseNumber, fromDate, untilDate);

6. Save the iCalendar File

Finally, save the generated .ics file to your system:

const filePath = path.join(__dirname, 'trash_collection_calendar.ics');
fs.writeFile(filePath, icsContent, (err) => {
  if (err) {
    console.error('Error saving iCalendar file:', err);
  } else {
    console.log(`iCalendar file has been saved to ${filePath}`);
  }
});

Now you have a fully working application that fetches waste collection schedules and saves them in a format that can be imported into any calendar application.

Who Can Benefit from This Package?

The FostPlus API Wrapper can be a great tool for:

  • Developers building local applications or smart home systems that notify users about trash collection schedules.
  • City or Municipal Websites that want to display waste collection information dynamically.
  • Environmentally Conscious Individuals who want to automate waste management reminders on their personal devices.

Conclusion

The FostPlus API Wrapper simplifies the process of accessing and utilizing waste collection data, offering an elegant solution for automation. This package, built with TypeScript, enables developers to generate iCalendar files with ease, making waste collection reminders accessible for a wide audience.

You can check out the npm package here and start integrating it into your project today!

FAQs

  1. How do I get a consumer key for the Fost Plus API? You can obtain the consumer key directly from Fost Plus, or scrape it from the web (A lot of companies do use them just look at the network tab for the calls and their X- headers).

  2. What is the purpose of the iCalendar file method? The iCalendar file (.ics) can be imported into any calendar application, allowing users to receive automatic reminders about their waste collection schedule.

  3. Is there a rate limit for Fost Plus API requests? As of now, there are no strict rate limits. However, this could change in the future.

  4. Can this package be used outside of Belgium? No, the data provided by Fost Plus is specific to Belgium’s waste management and recycling systems.

  5. Is the package free to use? Yes, the FostPlus API Wrapper is open-source and available for free on npm.

  6. Do I need to know TypeScript to use this package? While the package is written in TypeScript, you can still use it in plain JavaScript projects.