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

DEPRECATION NOTICE

As of May 2024, the backend service that this module relies on is deprecated and may cease operation in the near future. There is no immediate successor. Hence, Travel::Status::DE::IRIS is no longer actively maintained. There is no promise that issues and merge requests will be reviewed or merged.

The Travel::Status::DE::HAFAS(3pm) module provides similar features. However, its default "DB" backend is also deprecated. There is no migration path to a Deutsche Bahn departure monitor that is not deprecated at the moment.

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 eva (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-2024 by Birte Kristina Friesel <derf@finalrewind.org>

LICENSE

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