db-vendo-client

db-vendo-client

A client for the new "vendo"/"movas" Deutsche Bahn APIs, a drop-in replacement for hafas-client.

This is a very early version. What works:

• journeys(), refreshJourney() including tickets
• locations(), nearby(),
• departures(), arrivals() boards
• trip()

What doesn't work (yet, see TODO's scattered around the code):

• journeys() details like scheduledDays, stop/station groups, some line details ...
• loadFactor and other details in boards
• certain stop details like products for locations() and geopositions and remarks for boards – this can be remedied by turning on enrichStations in the config, enriching location info with db-hafas-stations.
• some query options/filters (e.g. routingMode for journeys, direction for boards)
• all other endpoints (tripsByName(), radar(), journeysFromTrip(), reachableFrom(), remarks(), lines(), station())

Depending on the configured profile, db-vendo-client will use multiple different DB APIs that offer varying functionality, so choose wisely:

	db Profile	dbnav Profile
no API key required	✅	✅
max duration boards	12h	1h
remarks	not for boards	only limited remarks for boards (still no remarks() endpoint)
cancelled trips	contained with cancelled flag in journeys, not contained in boards	contained with cancelled flag
tickets	only for refreshJourney(), mutually exclusive with polylines	only for refreshJourney(), mutually exclusive with polylines
polylines	only for refreshJourney() (mutually exclusive with tickets) and for trip() (only for HAFAS trip ids)	only for refreshJourney()/trip(), mutually exclusive with tickets
trip ids used	HAFAS trip ids for journeys, RIS trip ids for boards (static on train splits?)	HAFAS trip ids
line.id/fahrtNr used	unreliable/route id for journeys/trip(), actual fahrtNr for boards	actual fahrtNr for journeys, unreliable/route id for boards and trip()
adminCode/operator	adminCode only for boards	only for journeys
stop()	❌	✅
assumed backend API stability	less stable	more stable

Feel free to report anything that you stumble upon via Issues or create a PR :)

Also consult the documentation.

Background

After DB has switched to the new "vendo"/"movas" platform for bahn.de and DB Navigator, the old HAFAS API (see hafas-client) seems now to have been shut off. This project aims to enable easy switching to the new APIs. However, not all information will be available from the new APIs.

Actually, db-vendo-client is a wrapper around multiple different APIs, currently the bahn.de API for route planning and the regio-guide RIS API for boards for the db profile and the DB Navigator API for the dbnav profile. See some notes about the various new APIs at DB.

Strictly speaking, permission is necessary to use this library with the DB APIs.

Usage

Use it as a dependency, e.g. just replacing hafas-client:

npm i db-vendo-client

See an example in api.js. It shows how you can use db-vendo-client together with hafas-rest-api in order to run a FPTF API server. The Dockerfile serves this API (using the dbnav profile):

docker run \
    -e USER_AGENT=my-awesome-program \
    -e DB_PROFILE=dbnav \
    -p 3000:3000 \
    ghcr.io/public-transport/db-vendo-client

You may want to generate a client for your programming language for this REST API using the OpenAPI schema (open in Swagger Editor). Note that this is to be seen more as a starting point for implementation, e.g. some profile-specific details like tickets are missing from this API definition.

There are community-maintained TypeScript typings available as @types/hafas-client.

[!IMPORTANT] Depending on your use case, it is very important that you employ caching, either with a simple HTTP proxy cache in front of the REST API or by using cached-hafas-client (where, of course, you can just drop in a db-vendo-client instead of a hafas-client instance). Also see db-rest, which does this and some more plumbing.

Related Projects

• hafas-client – including further related projects
• hafas-rest-api – expose a hafas-client or db-vendo-client instance as a REST API
• db-rest – for the legacy DB HAFAS endpoint
• *.transport.rest – Public APIs wrapping some HAFAS endpoints.

Contributing

If you have a question, found a bug or want to propose a feature, please open an Issue.

This project needs help! Check the list of "help wanted" Issues.

If you're contributing code, please read the contribution guidelines.