The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Travel::Status::DE::HAFAS::StopFinder - Interface to HAFAS-based online stop finder services

SYNOPSIS

        use Travel::Status::DE::HAFAS::StopFinder;

        my $sf = Travel::Status::DE::HAFAS::StopFinder->new(
                url => 'https://reiseauskunft.bahn.de/bin/ajax-getstop.exe',
                input => 'Borbeck',
        );

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

        for my $candidate ($sf->results) {
                printf("%s (%s)\n", $candidate->{name}, $candidate->{id});
        }

VERSION

version 6.00

DESCRIPTION

Travel::Status::DE::HAFAS::StopFinder is an interface to the stop finder service of HAFAS based arrival/departure monitors, for instance the one available at https://reiseauskunft.bahn.de/bin/ajax-getstop.exe/dn.

It takes a string (usually a location or station name) and reports all stations and stops which are lexically similar to it.

StopFinder typically gives less coarse results than Travel::Status::DE::HAFAS(3pm)'s locationSearch method. However, it is unclear whether HAFAS instances will continue supporting it in the future.

METHODS

my $stopfinder = Travel::Status::DE::HAFAS::StopFinder->new(%opts)

Looks up stops as specified by opts and teruns a new Travel::Status::DE::HAFAS::StopFinder element with the results. Dies if the wrong opts were passed.

Supported opts are:

input => string

string to look up, e.g. "Borbeck" or "Koeln Bonn Flughafen". Mandatory.

url => url

Base url of the stop finder service, without the language and mode suffix ("/dn" and similar). Mandatory. See Travel::Status::DE::HAFAS(3pm)'s get_services method for a list of URLs.

language => language

Set language. Accepted arguments are deutsch, english, italian and n (dutch), depending on the used service.

It is unknown if this option has any effect.

lwp_options => \%hashref

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

my $stopfinder_p = Travel::Status::DE::HAFAS::StopFinder->new_p(%opt)

Return a promise that resolves into a list of Travel::Status::DE::HAFAS::StopFinder results ($stopfinder->results) on success and rejects with an error message ($stopfinder->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 implement a post_p function. Recommended: Mojo::UserAgent(3pm).

$stopfinder->errstr

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

$stopfinder->results

Returns a list of stop candidates. Each list element is a hash reference. The hash keys are id (IBNR / EVA / UIC station code) and name (stop name). Both can be used as input for the Travel::Status::DE::HAFAS(3pm) constructor.

If no matching results were found or the parser / HTTP request failed, returns the empty list.

DIAGNOSTICS

None.

DEPENDENCIES

  • LWP::UserAgent(3pm)

  • JSON(3pm)

BUGS AND LIMITATIONS

Unknown.

SEE ALSO

Travel::Status::DE::HAFAS(3pm).

AUTHOR

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

LICENSE

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