OpenCage Geocoding API Perl Tutorial

Topics covered in this tutorial

Background

The code examples below will use your geocoding API key once you log in.

Install the OpenCage Perl geocoding module

# install with cpanm
$ cpanm Geo::Coder::OpenCage

Please note: by default Geo::Coder::OpenCage makes all requests via https. Please ensure you are able to make https requests, or specify the optional http => 1 parameter to the new method when creating the Geo::Coder::OpenCage object to make http rather than https requests.

Forward Geocoding - address to coordinates

use Geo::Coder::OpenCage;

my $Geocoder = Geo::Coder::OpenCage->new(
    api_key => 'YOUR-API-KEY',
);

# see the full list of optional parameters:
# https://opencagedata.com/api#optional-params
#
# note: no need to URI encode location, module does that for you
#
my $response = $Geocoder->geocode(
    location => "Псковская улица, Санкт-Петербург, Россия",
    language => "ru",
    countrycode => "ru",
);

Reverse Geocoding - coordinates to address

use Geo::Coder::OpenCage;

my $Geocoder = Geo::Coder::OpenCage->new(
    api_key => 'YOUR-API-KEY',
    abbrv => 1,
);

my $response = $Geocoder->reverse_geocode(lat => -22.6792, lng => 14.5272);
# get first result
my $result = $response->{results}[0];

my $nicename = $result->{formatted};
# $nicename is now "Beryl's Restaurant, Woermann St, Swakopmund, Namibia"

# see full list of all the annotations
# https://opencagedata.com/api#annotations

my $geohash = $result->{annotations}->{geohash};
# $geohash is now "k7fqfx6h5jbq5tn8tnpn"

Batch geocode addresses

use Geo::Coder::OpenCage;

my @places = ('London', 'Paris', 'Berlin');
my %results;

# loop through the list, geocoding each individually
foreach my $place (@places){
    my $response = $Geocoder->geocode(
        location => $place
    );
    # $response is a hashref
    # see format:
    # https://opencagedata.com/api#response

    my $msg = $response->{status}->{message};
    if ($msg eq 'OK'){
        $results{$place} = $response->{results};
    } else {
        warn "failed to geocode $place : $msg";
    }
}