derhuerst · traines-source · Jan 20, 2025 · Jan 20, 2025 · Jan 27, 2025
diff --git a/api.js b/api.js
@@ -5,10 +5,8 @@ const require = createRequire(import.meta.url)
 
 import {dirname, join as pathJoin} from 'node:path'
 import {fileURLToPath} from 'node:url'
-import {
-	createDbHafas as createHafas,
-	defaults as dbHafasDefaults,
-} from 'db-hafas'
+import {createClient} from 'db-vendo-client'
+import {profile as dbnavProfile} from 'db-vendo-client/p/dbnav/index.js'
 import {createWriteStream} from 'node:fs'
 import {createHafasRestApi} from 'hafas-rest-api'
 import createHealthCheck from 'hafas-client-health-check'
@@ -17,7 +15,7 @@ import {createCachedHafasClient} from 'cached-hafas-client'
 import {createRedisStore} from 'cached-hafas-client/stores/redis.js'
 import serveStatic from 'serve-static'
 import {parseBoolean, parseInteger} from 'hafas-rest-api/lib/parse.js'
-import {loyaltyCardParser} from './lib/loyalty-cards.js'
+import {loyaltyCardParser, parseLoyaltyCard} from './lib/loyalty-cards.js'
 import {route as stations} from './routes/stations.js'
 import {route as station} from './routes/station.js'
 import {parseRoutingMode} from './lib/parse.js'
@@ -31,7 +29,7 @@ const docsRoot = pathJoin(__dirname, 'docs')
 const berlinHbf = '8011160'
 
 const customDbProfile = {
-	...dbHafasDefaults.profile,
+	...dbnavProfile,
 }
 
 // todo: DRY env var check with localaddress-agent/random-from-env.js
@@ -60,10 +58,10 @@ if (process.env.HAFAS_REQ_RES_LOG_FILE) {
 	}
 }
 
-// todo: use process.env.HAFAS_USER_AGENT if defined
-let hafas = createHafas(pkg.name, {
-	profile: customDbProfile,
-})
+let hafas = createClient(
+	customDbProfile,
+	process.env.USER_AGENT || process.env.HAFAS_USER_AGENT || pkg.name
+)
 let healthCheck = createHealthCheck(hafas, berlinHbf)
 
 if (process.env.REDIS_URL) {
@@ -88,11 +86,20 @@ if (process.env.REDIS_URL) {
 	)
 }
 
+const parseArrayOr = (parseEntry) => {
+	return (key, val) => {
+		if (Array.isArray(val)) {
+			return val.map(e => parseEntry(key, e));
+		}
+		return parseEntry(key, val);
+	}
+}
+
 const mapRouteParsers = (route, parsers) => {
 	if (route !== 'journeys') return parsers
 	return {
 		...parsers,
-		loyaltyCard: loyaltyCardParser,
+		loyaltyCard: {...loyaltyCardParser, parse: parseArrayOr(parseLoyaltyCard)},
 		firstClass: {
 			description: 'Search for first-class options?',
 			type: 'boolean',
@@ -103,7 +110,7 @@ const mapRouteParsers = (route, parsers) => {
 			description: 'Age of traveller',
 			type: 'integer',
 			defaultStr: '*adult*',
-			parse: parseInteger
+			parse: parseArrayOr(parseInteger)
 		},
 		routingMode: {
 			description: 'HAFAS routing mode, see the "Routing Mode" section',

diff --git a/architecture.svg b/architecture.svg
diff --git a/docs/readme.md b/docs/readme.md
@@ -2,29 +2,43 @@
 
 [`v6.db.transport.rest`](https://v6.db.transport.rest/) is a [REST API](https://restfulapi.net) for the public transportation system in Germany.
 
-## The API is currently unavailable!
-
-**The underlying [DB HAFAS API is currently not available](https://github.com/public-transport/hafas-client/issues/331)**, and it seems like it has been shut off permanently. We're considering changing `db-rest` to use [`db-vendo-client`](https://github.com/public-transport/db-vendo-client), **please follow [Issue #60](https://github.com/derhuerst/db-rest/issues/60) for updates**.
-
-You can also use [`db-vendo-client`](https://github.com/public-transport/db-vendo-client) yourself as a replacement, it covers most of the use cases served by `db-rest`, but [the underlying APIs seem to have a **much lower rate limit**](https://github.com/public-transport/db-vendo-client/issues/10).
+The [DB HAFAS API is currently not available](https://github.com/public-transport/hafas-client/issues/331), and it seems like it has been shut off permanently. `db-rest` now uses [`db-vendo-client`](https://github.com/public-transport/db-vendo-client) as a backend. It covers most of the use cases served by `db-rest`, notably except for `/stops/reachable-from` and `/radar`. Please also note some further limitations and caveats over in the readme and documentation of [`db-vendo-client`](https://github.com/public-transport/db-vendo-client). Also, [the underlying APIs seem to have a **much lower rate limit**](https://github.com/public-transport/db-vendo-client/issues/10). ⚠️ Hence, make sure [that you cannot obtain the data needed for your use case in a more efficient manner, e.g. using the available GTFS feeds](#why-not-to-use-this-api).
 
 [![API status](https://badgen.net/uptime-robot/status/m793274556-25c5e9bbab0297d91cda7134)](https://stats.uptimerobot.com/57wNLs39M/793274556)
 
 ## How it works
 
-Because it wraps [an API](https://github.com/public-transport/hafas-client/blob/6/readme.md#background) of [Deutsche Bahn](https://de.wikipedia.org/wiki/Deutsche_Bahn), it **includes most of the long-distance and regional traffic, as well as some international trains and local buses**. Essentially, it returns whatever data the [*DB Navigator* app](https://www.bahn.de/p/view/service/mobile/db-navigator.shtml) shows*, **including realtime delays and disruptions**.
+Because it wraps [an API](https://github.com/public-transport/db-vendo-client/blob/main/docs/db-apis.md) of [Deutsche Bahn](https://de.wikipedia.org/wiki/Deutsche_Bahn), it **includes most of the long-distance and regional traffic, as well as some international trains and local buses**. Essentially, it returns whatever data the [*DB Navigator* app](https://www.bahn.de/p/view/service/mobile/db-navigator.shtml) shows*, **including realtime delays and disruptions**.
 
-*When comparing results from this API to what the DB Navigator app shows there might be occasional differences due to them utilizing different, not 100% identical backends.*
+*When comparing results from this API to what the DB Navigator app shows there might be occasional differences due to them utilizing different, not 100% identical backends.* 
 
 - [Getting Started](getting-started.md)
 - [API documentation](api.md) (run `npm run build` to generate)
 - [OpenAPI playground with API documentation](https://petstore.swagger.io/?url=https%3A%2F%2Fv6.db.transport.rest%2F.well-known%2Fservice-desc%0A)
 
+## Why not to use this API?
+
+### Low rate limits
+
+[The underlying APIs seem to have a **much lower rate limit**](https://github.com/public-transport/db-vendo-client/issues/10) than before, i.e. you should not use this service to send many requests in an automated manner. Instead, you may:
+
+### Use GTFS and GTFS-RT
+
+[GTFS](https://gtfs.org) and [GTFS-RT](https://gtfs.org/documentation/realtime/reference/) are file format/feed specifications for scheduled timetables and realtime updates like delays, respectively. They enable you to download datasets for entire transport associations, regions or even countries in one go, for local querying (e.g. with [MOTIS](https://github.com/motis-project/motis) or [OTP](https://github.com/opentripplanner/OpenTripPlanner/)) and analysis (e.g. with [gtfs-via-postgres](https://github.com/public-transport/gtfs-via-postgres) and [print-gtfs-rt-cli](https://github.com/derhuerst/print-gtfs-rt-cli)). For Germany, [GTFS](https://www.opendata-oepnv.de/ht/de/organisation/delfi/startseite?tx_vrrkit_view%5Baction%5D=details&tx_vrrkit_view%5Bcontroller%5D=View&tx_vrrkit_view%5Bdataset_name%5D=deutschlandweite-sollfahrplandaten-gtfs&cHash=af4be4c0a9de59953fb9ee2325ef818f) and [GTFS-RT](https://mobilithek.info/offers/755009281410899968) feeds are provided by [DELFI e.V.](https://www.delfi.de/) Refined, publicly available feeds based on these and other sources can be obtained from [gtfs.de](https://gtfs.de) and [stc.traines.eu](https://stc.traines.eu/mirror/). I.e. by using these you do not need to make any excessive API requests, however, the data quality and coverage of these feeds will currently in many cases still be inferior to what is provided by Deutsche Bahn.
+
+### Use other APIs
+
+[transitous.org](https://transitous.org) may be another option, even with worldwide coverage based on GTFS/RT-feeds, however, as with any other APIs, it should not be flooded with requests.
+
+### Run your own instance of this API
+
+It may help to distribute the load by running your own instance of `db-rest`/[`db-vendo-client`](https://github.com/public-transport/db-vendo-client/). Both provide Dockerfiles/Docker images for easy setup of the REST API server. `db-rest` additionally includes a caching layer (if configured correctly), serves the OpenAPI specification, and does some more plumbing.
+
 ## Why use this API?
 
 ### Realtime Data
 
-This API returns realtime data whenever it is upstream. The [API for DB's mobile app](https://github.com/public-transport/hafas-client/blob/6/p/db/readme.md) provides it.
+This API returns realtime data whenever it is available upstream, as the API for DB's mobile app provides it.
 
 *Note: Different endpoints might remove realtime data like delays and cancellations at different times, i.e. after a journey's arrival.*
 

diff --git a/lib/loyalty-cards.js b/lib/loyalty-cards.js
@@ -18,6 +18,7 @@ const types = Array.from(typesByName.keys())
 
 const parseLoyaltyCard = (key, val) => {
 	if (typesByName.has(val)) return typesByName.get(val)
+	if (!val) return null;
 	throw new Error(key + ' must be one of ' + types.join(', '))
 }
 

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -35,9 +35,9 @@
 	"dependencies": {
 		"cached-hafas-client": "^5.0.1",
 		"cli-native": "^1.0.0",
-		"db-hafas": "^6.0.0",
 		"db-stations": "^5.0.0",
 		"db-stations-autocomplete": "^4.0.0",
+		"db-vendo-client": "^6.3.3",
 		"etag": "^1.8.1",
 		"hafas-client-health-check": "^2.1.1",
 		"hafas-rest-api": "^5.1.0",

diff --git a/readme.md b/readme.md
@@ -5,8 +5,8 @@
 [**API Documentation**](docs/readme.md)
 
 > [!IMPORTANT]
-> The [DB HAFAS API is currently not available](https://github.com/public-transport/hafas-client/issues/331), and it seems like it has been shut off permanently. We're considering changing `db-rest` to use [`db-vendo-client`](https://github.com/public-transport/db-vendo-client), please follow [Issue #60](https://github.com/derhuerst/db-rest/issues/60) for updates.
-> You can also use [`db-vendo-client`](https://github.com/public-transport/db-vendo-client) yourself as a replacement, it covers most of the use cases served by `db-rest`, but [the underlying APIs seem to have a **much lower rate limit**](https://github.com/public-transport/db-vendo-client/issues/10). ⚠️
+> The [DB HAFAS API is currently not available](https://github.com/public-transport/hafas-client/issues/331), and it seems like it has been shut off permanently. `db-rest` now uses [`db-vendo-client`](https://github.com/public-transport/db-vendo-client) as a backend. It covers most of the use cases served by `db-rest`, notably except for `/stops/reachable-from` and `/radar`. Please also note some further limitations and caveats over in the readme and documentation of [`db-vendo-client`](https://github.com/public-transport/db-vendo-client). Also, [the underlying APIs seem to have a **much lower rate limit**](https://github.com/public-transport/db-vendo-client/issues/10). ⚠️ Hence, make sure [that you cannot obtain the data needed for your use case in a more efficient manner, e.g. using the available GTFS feeds](docs#why-not-to-use-this-api).
+
 
 ![db-rest architecture diagram](architecture.svg)