NAME

Travel::Routing::DE::HAFAS - Interface to HAFAS itinerary services

SYNOPSIS

use Travel::Routing::DE::HAFAS;

my $hafas = Travel::Routing::DE::HAFAS->new(
	from_stop => 'Eichlinghofen H-Bahn, Dortmund',
	to_stop => 'Essen-Kupferdreh',
);

if (my $err = $hafas->errstr) {
	die("Request error: ${err}\n");
}

for my $con ( $hafas->connections ) {
	for my $sec ($con->sections) {
		if ( $sec->type eq 'JNY' ) {
			printf("%s -> %s\n%s ab %s\n%s an %s\n\n",
				$sec->journey->name,
				$sec->journey->direction,
				$sec->dep->strftime('%H:%M'),
				$sec->dep_loc->name,
				$sec->arr->strftime('%H:%M'),
				$sec->arr_loc->name,
			);
		}
	}
	print "\n\n";
}

VERSION

version 0.05

DESCRIPTION

Travel::Routing::DE::HAFAS is an interface to HAFAS itinerary services using the mgate.exe interface. It works best with the legacy instance of Deutsche Bahn, but supports other transit services as well.

METHODS

$hafas = Travel::Routing::DE::HAFAS->new(%opt)

Request connections as specified by %opt and return a new Travel::Routing::DE::HAFAS instance with the results. Dies if the wrong %opt were passed. %opt must contain from_stop and to_stop and supports the following additional flags:

from_stop => stop (mandatory)

Origin stop, e.g. "Essen HBf" or "Alfredusbad, Essen (Ruhr)". The stop must be specified either by name or by EVA ID (e.g. 8000080 for Dortmund Hbf).

to_stop => stop (mandatory)

Destination stop, e.g. "Essen HBf" or "Alfredusbad, Essen (Ruhr)". The stop must be specified either by name or by EVA ID (e.g. 8000080 for Dortmund Hbf).

via_stops => [stop1, stop2, ...]

Only return connections that pass all specified stops. Individual stops are identified by name or by EVA ID (e.g. 8000080 for Dortmund Hbf).

arrival => bool

If true: request connections that arrive at the destination before the specified time. If false (default): request connections that leave at the origin after the specified time.

cache => Cache::File object

Store HAFAS replies in the provided cache object. This module works with real-time data, so the object should be configured for an expiry of one to two minutes.

datetime => DateTime object

Date and time for itinerary request. Defaults to now.

excluded_mots => [mot1, mot2, ...]

By default, all modes of transport (trains, trams, buses etc.) are considered. If this option is set, all modes appearing in mot1, mot2, ... will be excluded. The supported modes depend on service, use get_services or get_service to get the supported values.

exclusive_mots => [mot1, mot2, ...]

If this option is set, only the modes of transport appearing in mot1, mot2, ... will be considered. The supported modes depend on service, use get_services or get_service to get the supported values.

language => language

Request text messages to be provided in language. Supported languages depend on service, use get_services or get_service to get the supported values. Providing an unsupported or invalid value may lead to garbage output.

lwp_options => \%hashref

Passed on to LWP::UserAgent->new. Defaults to { timeout => 10 }, pass an empty hashref to call the LWP::UserAgent constructor without arguments.

max_change => count

Request connections with no more than count changeovers.

service => service

Request results from service, defaults to "DB". See get_services (and hafas-m --list) for a list of supported services.

$hafas_p = Travel::Routing::DE::HAFAS->new_p(%opt)

Return a promise that resolves into a Travel::Routing::DE::HAFAS instance ($hafas) on success and rejects with an error message on failure. If the failure occured after receiving a response from the HAFAS backend, the rejected promise contains a Travel::Routing::DE::HAFAS instance as a second argument. 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 implement a post_p function. Recommended: Mojo::UserAgent(3pm).

$hafas->errcode

In case of an error in the HAFAS backend, returns the corresponding error code as string. If no backend error occurred, returns undef.

$hafas->errstr

In case of an error in the HTTP request or HAFAS backend, returns a string describing it. If no error occurred, returns undef.

$hafas->connections

Returns a list of Travel::Routing::DE::HAFAS::Connection(3pm) objects, each of which describes a single connection from origin to destination.

Returns a false value if no connections were found or the parser / http request failed.

$hafas->messages

Returns a list of Travel::Status::DE::HAFAS::Message(3pm) objects with service messages. Each message belongs to at least one connection, connection section, or stop along a section's journey.

$hafas->get_active_service

Returns a hashref describing the active service when a service is active and nothing otherwise. The hashref contains the keys url (URL to the station board service), and productbits (arrayref describing the supported modes of transport, may contain duplicates).

Travel::Routing::DE::HAFAS::get_services()

Returns an array containing all supported HAFAS services. Each element is a hashref and contains all keys mentioned in get_active_service. It also contains a shortname key, which is the service name used by the constructor's service parameter.

Travel::Routing::DE::HAFAS::get_service($service)

Returns a hashref describing the service $service. Returns nothing if $service is not supported. See get_active_service for the hashref layout.

DIAGNOSTICS

None.

DEPENDENCIES

• Class::Accessor(3pm)

• DateTime(3pm)

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

• LWP::UserAgent(3pm)

• Travel::Status::DE::HAFAS::Message(3pm)

BUGS AND LIMITATIONS

The non-default services (anything other than DB) are not well tested.

SEE ALSO

Travel::Routing::DE::HAFAS::Connection(3pm)

AUTHOR

Copyright (C) 2023 by Birte Kristina Friesel <derf@finalrewind.org>

LICENSE

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