Sends realtime public transport data from a VDV-453/VDV-454 API to a NATS message broker, so that it can be easily consumed by other applications. Uses vdv-453-client underneath.
npm install -g OpenDataVBB/vdv-453-nats-adapterPlease note the limitations imposed by the underlying library vdv-453-client:
A client for VDV-453 v2.3.2b/VDV-454 v1.2.2 (from 2013) systems. Can be used to connect to German public transport realtime data backends (Datendrehscheiben).
Note: This client supports neither the latest 2.x spec versions (VDV-453 v2.6.1/VDV-454 v2.2.1) nor the latest 3.x spec versions (VDV-453 v3.0/VDV-454 v3.0).
With the organisation providing the VDV 453 API, you will have to agree upon a Leitstellenkennung you'll use, which is a bit like an HTTP User-Agent:
6.1.3 Leitstellenkennung
Um Botschaften verschiedener Kommunikationspartner innerhalb eines Dienstes unterscheiden zu können, enthält jede Nachricht eine eindeutige Leitstellenkennung (Attribut
Sender) des nachfragenden Systems. […]
Then, configure access to the VDV-453 system, and run the adapter:
send-vdv-453-data-to-nats \
# must have a trailing `/`
--endpoint 'http://example.org:1234/api/' \
# your Leitstellenkennung, as agreed-upon between the VDV-453 API's operator and you
--leitstelle '…' \
# their Leitstellenkennung, as agreed-upon between the VDV-453 API's operator and you
--their-leitstelle '…'Usage:
send-vdv-453-data-to-nats [options] <service>
Notes:
Valid values for `service`:
- `AUS` subscribes to the VDV-454 AUS service containing network-wide realtime data.
Options:
--leitstelle -l VDV-453 Leitstellenkennung, a string identifying this
client, a bit like an HTTP User-Agent. Must be agreed-
upon with the provider of the VDV-453 API.
Default: $VDV_453_LEITSTELLE
--their-leitstelle -L VDV-453 Leitstellenkennung of the server. Must be agreed-
upon with the provider of the VDV-453 API.
Default: $VDV_453_THEIR_LEITSTELLE
--endpoint -e HTTP(S) URL of the VDV-453 API.
Default: $VDV_453_ENDPOINT
--port -p Port to listen on. VDV-453 requires the *client* to run
an HTTP server that the VDV-453 API can call.
Default: $PORT, otherwise 3000
--expires Set the subscription's expiry date & time. Must be an
ISO 8601 date+time string or a UNIX epoch/timestamp.
Default: now + 1h
--aus-manual-fetch-interval How often to *manually* fetch the data of an AUS
subscription, in milliseconds.
Usually, the server should notify the client about new
data, but some may not.
Default: 30_000
--nats-servers NATS server(s) to connect to.
Default: $NATS_SERVERS
--nats-user User to use when authenticating with NATS server.
Default: $NATS_USER
--nats-client-name Name identifying the NATS client among others.
Default: vdv453-1-${randomHex(4)}
Exit Codes:
1 – generic and/or unexpected error
2 – operation canceled
3 – VDV-453 API error
Examples:
send-vdv-453-data-to-nats --expires never AUS
vdv-453-nats-adapter writes pino-formatted log messages to stdout, so you can use pino-compatible tools to process them.
vdv-453-nats-adapter exposes Prometheus-compatible metrics via HTTP. By default, the metrics server will listen on a random port. You can configure a permanent port using $METRICS_SERVER_PORT.
The following kinds of metrics will be exported:
- domain-specific metrics, e.g.
- the number of active subscriptions set up
- the number of
AUSIstFahrts retrieved per fetch - the VDV API's
StartDienstZst
- technical details about the Node.js process, e.g. the current state of garbage collection
Refer to the Grafana dashboard in VBB's deployment for an example how to visualize vdv-453-nats-adapter's metrics.
- vdv-453-client – A client for VDV-453/VDV-454 systems.
If you have a question or need support using vdv-453-nats-adapter, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, use the issues page.