docs

docs/db-apis.md

@@ -0,0 +1,74 @@
+# New DB Board and Route Planning APIs (beyond HAFAS and IRIS)
+
+(Beware that a DB journey is what you usually call a trip (a vehicle travelilng at a certain time) and a DB trip is what you usually call a journey (result of a route search from A to B).)
+
+## RIS::Boards
+https://apis.deutschebahn.com/db/apis/ris-boards/v1/public/
+
+EPs:
+* departures/<evaNo>
+* arrivals/<evaNo>
+
+Notes:
+* docs (also helpful for other RIS-based APIs below): https://developers.deutschebahn.com/db-api-marketplace/apis/product/ris-boards-transporteure/api/ris-boards-transporteure#/RISBoards_151/overview
+* needs an API Key
+* provides remarks
+* does not provide loadFactor
+* no route planning
+* uses RIS trip IDs
+* boards up to 12 hours
+
+## bahnhof.de RIS
+https://www.bahnhof.de/api/boards/departures?evaNumbers=8000105&filterTransports=BUS&duration=60&locale=de
+
+Notes:
+* no API Key needed
+* provides remarks
+* uses RIS trip IDs
+* no route planning
+* boards up to 6 hours, only from current time (or unknown parameter)
+
+## Regio Guide RIS
+https://regio-guide.de/@prd/zupo-travel-information/api/public/ri/
+
+EPs:
+* departure/8000105?modeOfTransport=HIGH_SPEED_TRAIN,REGIONAL_TRAIN,CITY_TRAIN,INTER_REGIONAL_TRAIN,UNKNOWN,BUS,TRAM,SUBWAY&timeStart=2024-12-11T15:08:25.678Z&timeEnd=2024-12-12T01:53:25.678&expandTimeFrame=TIME_END&&occupancy=true
+* board/arrival/<evaNo>
+* routing-search (with POST body, see regio-guide.de)
+* trip/<tripId-from-routing-search>
+* journey/<journeyId-from-trip>
+
+Notes:
+* no API Key needed
+* no remarks in boards (or with unknown param), only some in journey
+* uses RIS trip IDs, does not expose them directly in the routing-search response
+* loadFactor for some regional services, not for long distance services
+* boards up to 12 hours
+
+## Vendo Navigator API
+https://app.vendo.noncd.db.de/mob/
+
+EPs:
+* bahnhofstafel/abfahrt
+* angebote/fahrplan (for route planning)
+
+Notes:
+* no API Key needed
+* used by new DB Navigator
+* to be investigated, reverse engineering of DB Navigator needed
+* probably uses HAFAS trip IDs
+
+## Vendo bahn.de API
+https://int.bahn.de/web/api/
+
+EPs:
+* angebote/fahrplan (for route planning)
+* reiseloesung/orte
+* reiseloesung/orte/nearby
+
+Notes:
+* no API Key needed
+* uses HAFAS trip IDs
+* provides loadFactor
+* no boards (?)
+

readme.md

@@ -9,14 +9,14 @@ This is a very early version. What works:
 
 * rudimentary `/journeys` including lowest prices
 * `/locations`, `/locations/nearby`
-* `/departures`, `/arrivals` (requires a DB API Key for RIS::Boards, maybe you find one somewhere ;)
+* `/departures`, `/arrivals`
 
 What doesn't work (yet, see TODO's scattered around the code):
 
 * `/journeys` details like scheduledDays, stop/station groups, tickets, some line details ...
 * `/journeys` uses different tripIds compared to departure and arrival boards...
 * certain stop details like products for `/locations` and geopositions for departures and arrivals
-* some query options like BahnCards etc. 
+* some query options like BahnCards etc., certain filters for boards 
 * all other endpoints
 
 Feel free report anything that you stumble upon via Issues or create a PR :)
@@ -28,16 +28,16 @@ Also consult the relevant **[documentation](https://github.com/public-transport/
 
 After DB has switched to the new "vendo" platform for bahn.de and DB Navigator, the old [HAFAS](https://de.wikipedia.org/wiki/HAFAS) API (see [hafas-client](https://github.com/public-transport/hafas-client/)) seems to become less and less reliable (server unreachable, missing prices, etc.) This project aims to enable easy switching to the new APIs. However, not all information will be available from the new APIs.
 
-Strictly speaking, permission is necessary to use this library with the bahn.de 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. See some [notes about the various new APIs at DB](docs/db-apis.md).
+
+Strictly speaking, permission is necessary to use this library with the DB APIs.
 
 ## Usage
 
 See an example in [api.js](api.js). It shows how you can use `db-vendo-client` together with `hafas-rest-api` in order to run a [FPTF](https://github.com/public-transport/friendly-public-transport-format) API server.
 
 There are [community-maintained TypeScript typings available as `@types/hafas-client`](https://www.npmjs.com/package/@types/hafas-client). 
 
-For the `/departures` and `/arrivals` endpoints, `DB_API_KEY` and `DB_CLIENT_ID` environment variables for RIS::Boards have to be set.
-
 ## Related Projects
 
 - [hafas-client](https://github.com/public-transport/hafas-client/) – including further related projects