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.06

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 }

Request carriage formation of train type number at 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. It should be configured for an expiry of one to two minutes.

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.