UdS Fahrplan Bot Development Log (1) -- Fetching data from HAFAS and its APIs through POST requests

This blog post is trying to tell you:

• My personal study notes on HAFAS, a public transport management system used around europe

What is HAFAS?

The HaCon Timetable Information System (HAFAS) is a software for timetable information from the company HaCon (Hannover Consulting). – Wikipedia

Basically, the entire Germany, Luxembourg, and the surrounding countries/regions use HAFAS to obtain depatures and stations details. This centralized software system can be visited using APIs. Different service providers may create their own HAFAS backend endpoint that exposes a public transport API over HTTP for customized usage. For example, you can send your HTTP requests to Deutsche Bahn (DB) if you have the access of their API, which can be found in DB API Marketplace.

What can we do with HAFAS?

There are four basic functions that the system has provided:

• TripSearch – return connections from location A to location B
• StationBoard – return all arrivals and departures of a certain station
• LocGeoPos – return list of stations in a give range of area
• LocMatch – return list of stations based on the keyword given

These includes most of the functionalities for users. For example, when we tried to plan our journey on DB navigator, the app uses TripSearch to show you connections; when we type the stations in the search box, the app LocMatch to give you related results.

Methods in detail

Since HAFAS is a enormous software system , there are a lot of attributes and setting provided to create a precise request. Here are some examples:

• departure time
• arrival time
• no. of trips/stations returned
• modes of transportations
• transfer time
• max. no. of transfer

How to perform a HTTP request

A HTTP request can be done by POST or GET as usual. For different regions or transportation providers, they set up their own server (API endpoint) that restrict what data and their format to return. Therefore users will not be overwhelmed with unrelated results. For example, when you are searching for stations in Luxembourg using Mobiliteit.lu, you may not want to see stations that share the same name, but are located in Berlin.

For each providers we need the corresponding profiles complete our request. Here is a python example to create a LocMatch request to SaarVV, the transportation provider in Saarland.

getTrip.py

import requests
import json

def LocMatch():
    url = "https://www.saarfahrplan.de/bin/mgate.exe"
    headers = {
        "Content-Type": "application/json",
        "Accept-Encoding": "gzip",
        "User-Agent": "HAFAS"
    }
    body = {
        "ver": "1.63",
        "lang": "en",
        "auth": {"type": "AID", "aid": "yCW9qZFSye1wIv3gCzm5r7d2kJ3LIF"},
        "client": {
            "id": "ZPS-SAAR",
            "type": "WEB",
            "name": "webapp",
            "l": "vs_webapp",
            "v": 10004
        },
        "formatted": False,
        "svcReqL": [{
            "meth": "LocMatch",
            "req": {
                "input": {
                    "field": "S",
                    "loc": {
                        "type": "ALL",
                        "name": keyword,
                    },
                    "maxLoc": 5
                }
            },
            "id": "1|3|"
        }]
    }

    try:
        res = requests.post(url, headers=headers, data=json.dumps(body))
        data = res.json()
        return data
    except Exception as e:
        print(f"❌ Error fetching location matches: {e}")
        return None

The whole request used a JSON format ("Content-Type": "application/json"), and the most important fields we need to connect to the API gateway/server-side application (URL) is a correct header, auth and client. With these we may establish the connection with the server and fetch the desired data.

Continue Reading: UdS Fahrplan Bot Development Log (2) – Planning for telegram bot

Reference

• hafas-client
• Deutsche Bahn
• SaarFahrplan
• Mobiliteit.lu
• Mobiliteit.lu (Github Repo)