NAME
Geo::Coder::OpenCage - Geocode coordinates and addresses with the OpenCage Geocoding API
VERSION
version 0.38
SYNOPSIS
my $Geocoder = Geo::Coder::OpenCage->new(api_key => $my_api_key);
# forward geocoding
my $response = $Geocoder->geocode(location => "Berlin");
# reverse geocoding
my $response = $Geocoder->reverse_geocode(lat => 52.5432379, lng => 13.4142133 );
if ($response->{status}{code} == 200) {
foreach my $r (@{ $response->{results} }) {
print $r->{formatted}, "\n";
print 'lat: ' . $r->{geometry}{lat}, "\n";
print 'lng: ' . $r->{geometry}{lng}, "\n";
}
}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 before you start.
DEVELOPING WITH AI
Please note there is an AI SKILL.md for working with the OpenCage Geocoding API which includes a reference file for developing in Perl using this module.
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.
Regardless of which UserAgent object is used, the User-Agent HTTP header will always be set to 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
You should always check the 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
my $response = $geocoder->geocode(location => "Berlin");
unless (defined $response) {
die "Geocoding failed";
}
if ($response->{status}{code} != 200) {
warn "API error: " . $response->{status}{message};
}- Supported Parameters
-
The OpenCage Geocoder has a few optional parameters.
Please see the OpenCage geocoder documentation. Most of the various optional parameters are supported.
The most commonly useful parameters are:
- 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 countrycode is a comma separated list of 2 character code as defined by the ISO 3166-1 Alpha 2 standard.
As a full example:
my $response = $Geocoder->geocode( location => "Псковская улица, Санкт-Петербург, Россия", language => "ru", countrycode => "ru", ); - Not Supported
- jsonp
-
This module always parses the response as a Perl data structure, so the jsonp option is never used.
All other API parameters are passed through directly
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.
SEE ALSO
Please see the Perl tutorial on the OpenCage site. Many other languages and frameworks are also available.
For full details of the API visit https://opencagedata.com/api
This module was featured in the 2016 Perl Advent Calendar.
AUTHOR
Ed Freyfogle <cpan@opencagedata.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by OpenCage GmbH.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.