Termin

A simple PHP script for notifying for a free slot for any appointment listed on the Berlin services website.

Notifications

Supports notifications via:

• Pushbullet
• Telegram
• ntfy

Requirements

• PHP 8.1+
• composer

Setup

Clone the repo

git clone https://github.com/inverse/termin.git

Dependencies

Install dependencies

composer install

Configuration

Configure an config.yml file based on the example.config.yml file located in the root of the repository.

Notifications

Termin supports various notifiers, it will send notifications to each one you configure.

ntfy (Easiest)

Set ntfy.topic within config.yml to something unique to you.

You can customise the server if you wish to use a 3rd party or self-hosted one.

Configure your client to listen to the same configured server/topic.

• From your phone
• From your browser

Pushbullet

Set pushbullet.api_token within config.yml with an API token from your account. Follow their quick start guide on how to get this.

Make sure you install their application or browser extension.

Telegram

Follow the official documentation on setting up a bot.

Within config.yml Set telegram.api_key with the API key provided from this process.

You will first need to make communication with the bot to enable it to send messages to you.

Once you have done that find your chat ID. You can get this by interacting with @raw_data_bot bot.

Set the value in telegram.chat_id.

Groups

If you are adding the bot to a group you must add your bot to your group.

Then find the chat ID for the group by adding @raw_data_bot and it will detail this.

Take care when copying the leading - as this is required for group chat IDs.

Site configuration

You can configure Termin to notify on multiple appointment types.

sites:
  -
    label: Vaterschaftsanerkennung
    type: berlin_service
    params:
      url: https://service.berlin.de/terminvereinbarung/termin/tag.php?termin=1&dienstleister=122900&anliegen[]=318991&herkunft=1
  -
    label: Geburtsurkunde
    type: berlin_service
    params:
      url: https://service.berlin.de/terminvereinbarung/termin/tag.php?termin=1&dienstleister=122900&anliegen[]=318957&herkunft=1

• label - the friendly label that will be displayed in the notification
• type - The type of scraper to use (berlin_service currently supported)
• params.url - the service URL you want to book. e.g. the URL behind the "Book an Appointment button"

Rules

Termin also has a simple rule engine that can be used for only notifying when certain conditions are met. Below listed are the currently supported rules that can be used to control the triggering of notifications.

after

Only notify when found appointments happen after condition.

rules:
  -
    type: after
    param: PT24H # Notify when the appointment is greater than 24h in the future

Uses the PHP DateInterval construct.

before

Only notify when found appointments happen before condition.

rules:
  -
    type: before
    param: PT24H # Notify when the appointment is less than 24h in the future

Uses the PHP DateInterval construct.

after_date

Only notify when found appointments happen after date condition.

rules:
  -
    type: after_date
    param: '2022-01-01 00:00:00'

before_date

Only notify when found appointments happen before date condition.

rules:
  -
    type: before_date
    param: '2022-01-01 00:00:00' 

Run

You can execute the script manually to test if everything is working correctly.

php app.php

If you see no errors and output similar to:

[2021-11-01T19:43:14.687782+00:00] termin.INFO: No availability found for: Anmeldung einer Wohnung [] []

You can then configure this to run on a regular schedule using something that your OS provides.

For example with cron, setup a job to call app.php on desired run interval e.g. every hour

0 * * * *  php ~/path/to/termin/app.php

Note: Don't set the frequency to high to not overload their website

Wait for a notification!

Run (docker)

Configure the application following the above steps and then run the prebuilt docker image.

docker run -it -v $(pwd)/config.yml:/app/config.yml ghcr.io/inverse/termin/termin:latest

Configure this to run on a regular schedule using something that your OS provides.

Note: Don't set the schedule frequency to high to not overload their website

Run (serverless)

Termin can also be run as a serverless application. Configure the application like you would like any other way.

Install serverless toolchain:

npm install

Then configure your environment with serverless tooling.

And finally deploy:

npx serverless deploy

To remove run:

npx serverless remove

License

MIT