Perl Geocoding Tutorial

Before we dive in to the tutorial ...

This is a tutorial for using the OpenCage Geocoding API in Perl. Before you can query the API you will need to sign up for an OpenCage API key.

Once you've done that we recommend you spend five minutes on:

• playing with the demo page, so that you see the actual response the API returns.

• browsing the API documentation, so you understand the various optional parameters, possible response codes, and the rate limiting on free trial accounts

Ok, ready?

Install the OpenCage Perl geocoding library

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

Geocode an address

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#forward-opt
my $result = $Geocoder->geocode(
    location => "Псковская улица, Санкт-Петербург, Россия",
    language => "ru",
    countrycode => "ru",
);

Batch geocode addresses

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

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

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

Geocode coordinates

use Geo::Coder::OpenCage;

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

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

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"