NAME

Travel::Status::MOTIS - An interface to the MOTIS routing service

SYNOPSIS

Blocking variant:

use Travel::Status::MOTIS;

my $status = Travel::Status::MOTIS->new(
	service => 'RNV',
	stop_id => 'rnv_241721',
);

for my $result ($status->results) {
	printf(
		"%s +%-3d %10s -> %s\n",
		$result->stopover->departure->strftime('%H:%M'),
		$result->stopover->delay,
		$result->route_name,
		$result->headsign,
	);
}

Non-blocking variant;

use Mojo::Promise;
use Mojo::UserAgent;
use Travel::Status::MOTIS;

Travel::Status::MOTIS->new_p(
	service => 'RNV',
	stop_id => 'rnv_241721',
	promise => 'Mojo::Promise',
	user_agent => Mojo::UserAgent->new
)->then(sub {
	my ($status) = @_;
	for my $result ($status->results) {
		printf(
			"%s +%-3d %10s -> %s\n",
			$result->stopover->departure->strftime('%H:%M'),
			$result->stopover->delay,
			$result->route_name,
			$result->headsign,
		);
	}
})->wait;

VERSION

version 0.03

DESCRIPTION

Travel::Status::MOTIS is an interface to the departures and trips provided by MOTIS routing services

METHODS

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

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

opt must contain exactly one of the following keys:

stop_id => $stop_id

Request stop board (departures) for the stop specified by $stop_id. Use stops_by_coordinate or stops_by_query to obtain a stop id. Results are available via $status->results.

stops_by_coordinate => { lat => latitude, lon => longitude }

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

stops_by_query => $query

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

trip_id => $trip_id

Request trip details for $trip_id. 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. stops_by_coordinate or stop_id.

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 (stop_id)

Only consider the modes of transit given in arrayref when listing departures. Accepted modes of transit are: TRANSIT (same as RAIL, SUBWAY, TRAM, BUS, FERRY, AIRPLANE, COACH), TRAM, SUBWAY, FERRY, AIRPLANE, BUS, COACH, RAIL (same as HIGHSPEED_RAIL, LONG_DISTANCE_RAIL, NIGHT_RAIL, REGIONAL_RAIL, REGIONAL_FAST_RAIL), METRO, HIGHSPEED_RAIL, LONG_DISTANCE, NIGHT_RAIL, REGIONAL_FAST_RAIL, REGIONAL_RAIL.

By default, Travel::Status::MOTIS uses TRANSIT.

json => \%json

Do not perform a request to MOTIS; load the prepared response provided in json instead. Note that you still need to specify stop_id, trip_id, etc. as appropriate.

time_zone => $time_zone

A timezone to normalize timestamps to, defaults to 'local'.

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

Return a promise yielding a Travel::Status::MOTIS 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 (stop_id, stops_by_query, stops_by_coordinate)

Returns a list of Travel::Status::MOTIS::Stop(3pm) or Travel::Status::MOTIS::TripAtStopover(3pm) objects, depending on the arguments passed to new.

$status->result (trip_id)

Returns a Travel::Status::MOTIS::Trip(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 MOTIS requests and responses on the standard output.

DEPENDENCIES

• DateTime(3pm)

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

• LWP::UserAgent(3pm)

• URI(3pm)

BUGS AND LIMITATIONS

This module is designed for use in travelynx (https://finalrewind.org/projects/travelynx/) and might not contain functionality needed otherwise.

REPOSITORY

TBD

AUTHOR

Copyright (C) 2025 networkException <git@nwex.de>

Based on Travel::Status::DE::DBRIS

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

LICENSE

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