Perl Geocoding Tutorial

Topics covered in this tutorial

• General Background
• Agent Skill
• installing Geo::Coder::OpenCage
• Forward geocoding
• Reverse geocoding
• Geocoding a list of places
• Further reading

Background

Agent Skill / Working with AI

Are you developing with AI?

We offer an Agent Skill that includes a reference file specifically about developing code to access our API via Perl.

Install the OpenCage Perl geocoding module

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

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