cgn-appointments/README.md
2024-09-17 22:24:56 +02:00

179 lines
5.2 KiB
Markdown

# cgn-appointments
This programm allows you to scrape the appointments from the website of the city
of Cologne (Stadt Köln) and send a notification via ntfy if a new appointment is
available.
## Installation
A good way to install `cgn-appointments` is via [pipx](https://pipx.pypa.io/stable/).
```bash
pipx install --index-url https://git.pub.solar/api/packages/marc/pypi/simple/ --pip-args="--extra-index-url https://pypi.org/simple" cgn-appointments
```
## Configuration
Execute `cgn-appointments` for the first time to create the configuration file.
Then edit the configuration file and adapt it to your needs.
```yaml
---
# If this url does not work anymore, visit https://www.stadt-koeln.de/service/produkte/00416/index.html,
# copy the url of the "Termin Buchen" tile and replace the url below.
url: 'https://termine.stadt-koeln.de/m/kundenzentren/extern/calendar/?uid=b5a5a394-ec33-4130-9af3-490f99517071&wsid=e570a1ea-7b3d-43f6-bf43-3e60b3d7d888&lang=de&set_lang_ui=de&rev=rfOtF#top'
# Which services should be checked for free appointments?
# Copy the exact name of the service from the website.
services:
- 'Personalausweis - Antrag'
- 'Reisepass - Antrag (seit 01.01.2024 auch für Kinder unter 12 Jahren)'
# In which locations should the services be checked?
# Use the name as displayed on the website.
locations:
- Ehrenfeld
- Kalk
# Path to the CSV file to store the scraped appointments
# csv_path: ~/Termine.csv
# Name of the CSV file to store the scraped appointments
csv_name: 'appointments.csv'
# Regex to extract the date from the website
# There should be no need to change this
date_regex: '(\\d{2}\\.\\d{2}\\.\\d{4}\\s\\d{2}:\\d{2})'
# Date format to store the date in the CSV file (should match the date_regex)
# There should be no need to change this
date_format: '%d.%m.%Y %H:%M'
# ntfy configuration
# See https://ntfy.sh/ for more information
# Choose a topic name that is unique to you
ntfy:
server: https://ntfy.sh/
topic: public_cgn_appintments_83e0c8db1f51a7044b6431ddb2814c11
title: 'A new appointment is available!'
message: 'A new appointment is available in %s: %s'
tags:
- tada
priority: 3 # 1-5
# Configure logging
# Advanced users can change the logging configuration here
# The loglevel can be set to DEBUG, INFO, WARNING, ERROR, CRITICAL
logging:
version: 1
disable_existing_loggers: false
formatters:
simple:
format: '[%(levelname)s|%(module)s|L%(lineno)d] %(asctime)s: %(message)s'
datefmt: '%Y-%m-%dT%H:%M:%S%z'
json:
fmt_keys:
level: levelname
message: message
timestamp: timestamp
logger: name
module: module
function: funcName
line: lineno
thread_name: threadName
handlers:
stderr:
class: logging.StreamHandler
formatter: simple
stream: ext://sys.stderr
level: DEBUG
file:
class: logging.handlers.RotatingFileHandler
formatter: json
level: INFO
maxBytes: 10000000
backupCount: 3
queue_handler:
class: logging.handlers.QueueHandler
handlers:
- stderr
- file
respect_handler_level: true
loggers:
root:
handlers:
- queue_handler
level: DEBUG
```
## Usage
You can use `cg-appointments` with only the configuration file or with
additional command line arguments which will override the values set in the
configuration file.
Using the `--services` flag, make sure to use `"double quotes"` around the
service name if it contains spaces.
```bash
usage: cgn-appointments [-h] [-s SERVICES [SERVICES ...]]
[-l LOCATIONS [LOCATIONS ...]]
[--config-file CONFIG_FILE] [--csv-file CSV_FILE]
[--log-file LOG_FILE]
[--log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}]
Scrapes appointments from termine.stadt-koeln.de an sends a message to a ntfy
server.
options:
-h, --help show this help message and exit
-s SERVICES [SERVICES ...], --services SERVICES [SERVICES ...]
Services to check
-l LOCATIONS [LOCATIONS ...], --locations LOCATIONS [LOCATIONS ...]
Locations to check
--config-file CONFIG_FILE
Path to the configuration file
--csv-file CSV_FILE Path to the csv file, which stores the last fetched
dates
--log-file LOG_FILE Path to logfile
--log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
Logging Level
```
### Example
```bash
cgn-apppointments \
--services "Personalausweis - Antrag" "Reisepass - Antrag (seit 01.01.2024 auch für Kinder unter 12 Jahren)" \
--locations Ehrenfeld Kalk \
--config-file /path/to/config.yaml \
--csv-file /path/to/csvfile.csv \
--log-file /path/to/logfile.log \
--log-level INFO
```
## Scheduled Execution via `cron`
On linux systems you can use `cron` to schedule the execution of
`cgn-appointments`.
Find the path to the `cgn-appointments` executable
```bash
which cgn-appointments
```
Open the crontab file
```bash
crontab -e
```
Add the following line to the crontab file to execute `cgn-appointments` every
30 minutes
```bash
*/30 * * * * /path/to/cgn-appointments > /dev/null 2>&1
```