NAME

Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors.

SYNOPSIS

Blocking variant:

    use Travel::Status::DE::IRIS;
    
    my $status = Travel::Status::DE::IRIS->new(station => "Essen Hbf");
    for my $r ($status->results) {
        printf(
            "%s %s +%-3d %10s -> %s\n",
            $r->date, $r->time, $r->delay || 0, $r->line, $r->destination
        );
    }

Non-blocking variant (EXPERIMENTAL):

    use Mojo::Promise;
    use Mojo::UserAgent;
    use Travel::Status::DE::IRIS;
    use Travel::Status::DE::IRIS::Stations;
    
    Travel::Status::DE::IRIS->new_p(station => "Essen Hbf",
            promise => 'Mojo::Promise', user_agent => Mojo::UserAgent->new,
            get_station => \&Travel::Status::DE::IRIS::Stations::get_station,
            meta => Travel::Status::DE::IRIS::Stations::get_meta())->then(sub {
        my ($status) = @_;
        for my $r ($status->results) {
            printf(
                "%s %s +%-3d %10s -> %s\n",
                $r->date, $r->time, $r->delay || 0, $r->line, $r->destination
            );
        }
    })->wait;

VERSION

version 1.81

DESCRIPTION

Travel::Status::DE::IRIS is an unofficial interface to IRIS based web departure monitors such as https://iris.noncd.db.de/wbt/js/index.html?typ=ab&style=qrab&bhf=EE&SecLang=&Zeilen=20&footer=0&disrupt=0.

METHODS

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

Requests schedule and realtime data for a specific station at a specific point in time. Returns a new Travel::Status::DE::IRIS object.

Arguments:

datetime => datetime-obj

A DateTime(3pm) object specifying the point in time. Optional, defaults to the current date and time.

iris_base => url

IRIS base url, defaults to http://iris.noncd.db.de/iris-tts/timetable.

keep_transfers => bool

A train may change its ID and number at a station, indicating that although the previous logical train ends here, the physical train will continue its journey under a new number to a new destination. A notable example is the Berlin Ringbahn, which travels round and round from Berlin Südkreuz to Berlin Südkreuz. Each train number corresponds to a single revolution, but the actual trains just keep going.

The IRIS backend returns two results for each transfer train: An arrival-only result using the old ID (linked to the new one) and a departure-only result using the new ID (linked to the old one). By default, this library merges these into a single result with both arrival and departure time. Train number, ID, and route are taken from the departure only. The original train ID and number are available using the old_train_id and old_train_no accessors.

In case this is not desirable (e.g. because you intend to track a single train to its destination station and do not want to implement special cases for transfer trains), set keep_transfers to a true value. In this case, backend data will be reported as-is and transfer trains will not be merged.

lookahead => int

Compute only results which are scheduled less than int minutes in the future. Default: 120 (2 hours).

Note that the DeutscheBahn IRIS backend only provides schedules up to four to five hours into the future. So in most cases, setting this to a value above 240 minutes will have little effect. However, as the IRIS occasionally contains unscheduled departures or qos messages known far in advance (e.g. 12 hours from now), any non-negative integer is accepted.

lookbehind => int

Also check trains whose scheduled departure lies up to int minutes in the past. Default: 0.

This is useful when requesting departures shortly after a full hour. If, for example, a train was scheduled to depart on 11:59 and has 5 minutes delay, it will not be shown when requesting departures on or after 12:00 unless lookbehind is set to a value greater than zero.

Note that trains with significant delay (e.g. +30) may still be shown in this case regardless of the setting of lookbehind, since these receive special treatment by the IRIS backend.

lwp_options => \%hashref

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

main_cache => $ojj

A Cache::File(3pm) object used to cache station and timetable requests. Optional.

realtime_cache => $ojj

A Cache::File(3pm) object used to cache realtime data requests. Optional.

station => stationcode

Mandatory: Which station to return departures for. Note that this is not a station name, but a station code, such as "EE" (for Essen Hbf) or "KA" (for Aachen Hbf). See Travel::Status::DE::IRIS::Stations(3pm) for a name to code mapping.

with_related => bool

Sometimes, Deutsche Bahn splits up major stations in the IRIS interface. For instance, "Köln Messe/Deutz" actually consists of "Köln Messe/Deutz" (KKDZ), "Köln Messe/Deutz Gl. 9-10" (KKDZB) and "Köln Messe/Deutz (tief)" (KKDT).

By default, Travel::Status::DE::IRIS only returns departures for the specified station. When this option is set to a true value, it will also return departures for all related stations.

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

Return a promise yielding a Travel::Status::DE::IRIS instance ($status) on success, or an error message (same as $status->errstr) on failure. This function is experimental and may be changed or remove without warning.

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

get_station => get_station ref

Reference to Travel::Status::DE::IRIS::Stations::get_station().

meta => meta dict

The dictionary returned by Travel::Status::DE::IRIS::Stations::get_meta().

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 IRIS error, returns a string describing it. Returns undef otherwise.

$status->related_stations

Returns a list of hashes describing related stations whose arrivals/departures are included in results. Only useful when setting with_related to a true value, see its documentation above for details.

Each hash contains the keys uic (EVA number; often same as UIC station ID), name (station name), and ds100 (station code). Note that stations returned by related_stations are not necessarily known to Travel::Status::DE::IRIS::Stations(3pm).

$status->results

Returns a list of Travel::Status::DE::IRIS::Result(3pm) objects, each one describing one arrival and/or departure.

$status->warnstr

In case of a (probably) non-fatal HTTP request or IRIS error, returns a string describing it. Returns undef otherwise.

DIAGNOSTICS

None.

DEPENDENCIES

• DateTime(3pm)

• List::Util(3pm)

• LWP::UserAgent(3pm)

• XML::LibXML(3pm)

BUGS AND LIMITATIONS

Some backend features are not yet exposed.

SEE ALSO

db-iris(1), Travel::Status::DE::IRIS::Result(3pm), Travel::Status::DE::IRIS::Stations(3pm)

REPOSITORY

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

AUTHOR

Copyright (C) 2013-2020 by Daniel Friesel <derf@finalrewind.org>

LICENSE

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