NAME

Geo::Coder::OpenCage - Geocode coordinates and addresses with the OpenCage Geocoding API

VERSION

version 0.36

SYNOPSIS

    my $Geocoder = Geo::Coder::OpenCage->new(api_key => $my_api_key);
    my $response = $Geocoder->geocode(location => "Donostia");

DESCRIPTION

This module provides an interface to the OpenCage geocoding service.

For full details of the API visit <https://opencagedata.com/api>

It is recommended you read the best practices for using the OpenCage geocoder <https://opencagedata.com/api#bestpractices> before you start.

METHODS

new

    my $Geocoder = Geo::Coder::OpenCage->new(api_key => $my_api_key);

Get your API key from <https://opencagedata.com>.

Optionally "http => 1" can also be specified in which case API requests will NOT be made via https

ua

    $ua = $geocoder->ua();
    $ua = $geocoder->ua($ua);

Accessor for the UserAgent object. By default HTTP::Tiny is used. Useful if for example you want to specify that something like LWP::UserAgent::Throttled for rate limiting. Even if a new UserAgent is specified the useragent string will be specified as "Geo::Coder::OpenCage $version"

geocode

Takes a single named parameter 'location' and returns a result hashref.

    my $response = $Geocoder->geocode(location => "Mudgee, Australia");

warns and returns undef if the query fails for some reason.

If you will be doing forward geocoding, please see the OpenCage query formatting guidelines <https://opencagedata.com/guides/how-to-format-your-geocoding-query>

You should check the always response status

  $response->{status}{code}

to ensure you have had a successful response, are not hitting rate limits, etc. Please see the OpenCage geocoding API response codes <https://opencagedata.com/api#codes>

The OpenCage Geocoder has a few optional parameters:

Supported Parameters: please see the OpenCage geocoder documentation <https://opencagedata.com/api>. Most of the various optional parameters <https://opencagedata.com/api#forward-opt> are supported. For example:

language: An IETF format language code (such as es for Spanish or pt-BR for Brazilian Portuguese); if this is omitted a code of en (English) will be assumed.
limit: Limits the maximum number of results returned. Default is 10.
countrycode: Provides the geocoder with a hint to the country that the query resides in. This value will help the geocoder but will not restrict the possible results to the supplied country.
The country code is a comma seperated list of 2 character code as defined by the ISO 3166-1 Alpha 2 standard.

Not Supported

jsonp: This module always parses the response as a Perl data structure, so the jsonp option is never used.

As a full example:

    my $response = $Geocoder->geocode(
        location => "Псковская улица, Санкт-Петербург, Россия",
        language => "ru",
        countrycode => "ru",
    );

reverse_geocode

Takes two named parameters 'lat' and 'lng' and returns a result hashref.

    my $response = $Geocoder->reverse_geocode(lat => -22.6792, lng => 14.5272);

This method supports the optional parameters in the same way that geocode() does.

ENCODING

All strings passed to and received from Geo::Coder::OpenCage methods are expected to be character strings, not byte strings.

For more information see perlunicode.

AUTHOR

Ed Freyfogle <cpan@opencagedata.com>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.