view release on metacpan or  search on metacpan

lib/Geo/Coder/Ovi.pm  view on Meta::CPAN

    return unless $res->is_success;

    # Change the content type of the response from 'application/json' so
    # HTTP::Message will decode the character encoding.
    $res->content_type('text/plain');

    my $data = eval { from_json($res->decoded_content) };
    return unless $data;
    return $data if $raw;

    my @results = @{ $data->{results} || [] };
    return wantarray ? @results : $results[0];
}


1;

__END__

=head1 NAME

Geo::Coder::Ovi - Geocode addresses with the Ovi Maps API

=head1 SYNOPSIS

    use Geo::Coder::Ovi;

    my $geocoder = Geo::Coder::Ovi->new(
        appid => 'Your App ID',
        token => 'Your token',
    );
    my $location = $geocoder->geocode(
        location => '102 Corporate Park Dr, Harrison, NY'
    );

=head1 DESCRIPTION

The C<Geo::Coder::Ovi> module provides an interface to the geocoding service
of the Ovi Maps API.

=head1 METHODS

=head2 new

    $geocoder = Geo::Coder::Ovi->new(
        appid => 'Your App ID',
        token => 'Your token',
        # debug => 1,
    )

Creates a new geocoding object.

Accepts the following named arguments:

=over

=item * I<appid>

=item * I<token>

Authentication credentials. (optional, for now)

Credentials can be obtained here: L<https://api.developer.nokia.com/ovi-api>

Note: performance and/or access may be limited without credentials.

=item * I<compress>

Enable compression. (default: 1, unless I<debug> is enabled)

=item * I<debug>

Enable debugging. This prints the headers and content for requests and
responses. (default: 0)

=item * I<ua>

A custom LWP::UserAgent object. (optional)

=back

=head2 geocode

    $location = $geocoder->geocode(location => $location)
    @locations = $geocoder->geocode(location => $location)

Accepts the following named arguments:

=over

=item * I<location>

The free-form, single line address to be located. (required)

=item * I<language>

The preferred language of the response. The language may be specified as the
ISO639-1 language code (e.g. C<en>) or the language code and the ISO3166-1
alpha-2 country code (e.g. C<en-US>). (default: '')

=item * I<raw>

Returns the raw data structure converted from the response, not split into
location results. (optional)

=back

In scalar context, this method returns the first location result; and in
list context it returns all location results.

Example of the data structure representing a location result:

    {
        categories => [ { id => 9000284 } ],
        properties => {
            addrAreaotherName => "West Harrison",
            addrCityName      => "Harrison",
            addrCountryCode   => "USA",
            addrCountryName   => "United States of America",
            addrCountyName    => "Westchester",
            addrHouseAlpha    => "",
            addrHouseNumber   => 102,
            addrPopulation    => 0,
            addrPostalCode    => 10604,
            addrStateName     => "New York",