Perl Geocoding Tutorial

This is a tutorial for using the OpenCage geocoding API in Perl.

Before we dive in to the tutorial ...

You will need to sign up for an OpenCage geocoding API key.

Then please spend two minutes ...

Ok, ready?

Install the OpenCage Perl geocoding library

# 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#forward-opt
#
# note: no need to URI encode location, module does that for you
#
my $response = $Geocoder->geocode(
    location => "Псковская улица, Санкт-Петербург, Россия",
    language => "ru",
    countrycode => "ru",
);

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";
    }
}

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"

Further Reading

Start your free trial

2,500 geocoding API requests per day.

No credit card required.