NAME

Travel::Status::DE::DBRIS - Interface to bahn.de / bahnhof.de departure monitors

SYNOPSIS

Blocking variant:

use Travel::Status::DE::DBRIS;

my $status = Travel::Status::DE::DBRIS->new(station => 8000098);
for my $r ($status->results) {
    printf(
        "%s +%-3d %10s -> %s\n",
        $r->dep->strftime('%H:%M'),
        $r->delay,
        $r->line,
        $r->dest_name
    );
}

Non-blocking variant;

use Mojo::Promise;
use Mojo::UserAgent;
use Travel::Status::DE::DBRIS;

Travel::Status::DE::DBRIS->new_p(
    station => 8000098,
    promise => 'Mojo::Promise',
    user_agent => Mojo::UserAgent->new
)->then(sub {
    my ($status) = @_;
    for my $r ($status->results) {
        printf(
            "%s +%-3d %10s -> %s\n",
            $r->dep->strftime('%H:%M'),
            $r->delay,
            $r->line,
            $r->dest_name
        );
    }
})->wait;

VERSION

version 0.15

DESCRIPTION

Travel::Status::DE::DBRIS is an unofficial interface to bahn.de departure monitor and train information APIs.

METHODS

my $status = Travel::Status::DE::DBRIS->new(%opt)

Requests item(s) as specified by opt and returns a new Travel::Status::DE::DBRIS element with the results. Dies if the wrong opt were passed.

opt must contain exactly one of the following keys:

station => $location

Request station board (departures) for the station specified by $location, which must be either a Travel::Status::DE::DBRIS::Location(3pm) instance or a hashref containing { eva => eva, id => id }. Use geoSearch or locatiorSearch to obtain a location. Results are available via $status->results.

geoSearch => { latitude => latitude, longitude => longitude }

Search for stations near latitude, longitude. Results are available via $status->results.

locationSearch => query

Search for stations whose name is equal or similar to query. Results are available via $status->results and include the station ID needed for station board requests.

journey => journeyID

Request trip details for journeyID. The result is available via $status->result.

formation => { eva => eva, train_type => type, train_number => number, departure => datetime }

Request carriage formation of train type number, scheduled to depart from eva at datetime. eva is an eva number as returned by, e.g., $location->eva. The result is available via $status->result.

The following optional keys may be set. Values in brackets indicate keys that are only relevant in certain request modes, e.g. geoSearch or station.

cache => $obj

A Cache::File(3pm) object used to cache realtime data requests. Will be used to associate HTTP URLs with raw JSON output as returned by bahn.de. The object should be configured for an expiry of one to two minutes.

failure_cache => $obj

A Cache::File(3pm) object used to cache failed requests. Will be used to associate HTTP URLs with the string n, indicating a failed request. The object should be configured for an expiry of one to two minutes. May be identical with the $obj specified as cache.

Careful: setting this will cause both (possibly permanent) HTTP failure codes and (likely ephemeral) failed connection attempts (e.g. timeouts due to spotty network reception) to be cached.

lwp_options => \%hashref

Passed on to LWP::UserAgent->new. Defaults to { timeout => 10 }, you can use an empty hashref to unset the default.

modes_of_transit => \@arrayref (station)

Only consider the modes of transit given in arrayref when listing departures. Accepted modes of transit are: ICE, EC_IC, IR, REGIONAL, SBAHN, BUS, SCHIFF, UBAHN, TRAM, ANRUFPFLICHTIG.

By default, Travel::Status::DE::DBRIS considers all modes of transit.

json => \%json

Do not perform a request to bahn.de; load the prepared response provided in json instead. Note that you still need to specify station, journey, etc. as appropriate.

my $promise = Travel::Status::DE::DBRIS->new_p(%opt)

Return a promise yielding a Travel::Status::DE::DBRIS instance ($status) on success, or an error message (same as $status->errstr) on failure.

In addition to the arguments of new, the following mandatory arguments must be set:

promise => promises module

Promises implementation to use for internal promises as well as new_p return value. Recommended: Mojo::Promise(3pm).

user_agent => user agent

User agent instance to use for asynchronous requests. The object must support promises (i.e., it must implement a get_p function). Recommended: Mojo::UserAgent(3pm).

$status->errstr

In case of a fatal HTTP request or backend error, returns a string describing it. Returns undef otherwise.

$status->results (station, locationSearch, geoSearch)

Returns a list of Travel::Status::DE::DBRIS::Location(3pm) or Travel::Status::DE::DBRIS::JourneyAtStop(3pm) objects, depending on the arguments passed to new.

$status->result (journey, formation)

Return a Travel::Status::DE::DBRIS::Journey(3pm) or Travel::Status::DE::DBRIS::Formation(3pm) object, depending on the arguments passed to new.

DIAGNOSTICS

Calling new or new_p with the developer_mode key set to a true value causes this module to print bahn.de requests and responses on the standard output.

DEPENDENCIES

• DateTime(3pm)

• DateTime::Format::Strptime(3pm)

• LWP::UserAgent(3pm)

BUGS AND LIMITATIONS

This module is very much work-in-progress.

REPOSITORY

https://github.com/derf/Travel-Status-DE-DBRIS

AUTHOR

Copyright (C) 2024-2025 Birte Kristina Friesel <derf@finalrewind.org>

LICENSE

This module is licensed under the same terms as Perl itself.