Author image Tom Wyant
and 1 contributors


Geo::Coder::Geocoder::US - Geocode a location using


 use Geo::Coder::Geocoder::US;
 use YAML;
 my $gc = Geo::Coder::Geocoder::US->new();
 foreach my $loc ( @ARGV ) {
     if ( my @rslt = $gc->geocode( $loc ) ) {
     } else {
         warn "Failed to geocode $loc: ",


This perl module makes use of the API to geocode addresses in the United States of America. This web site disappeared late in 2015, and has not been seen since. Without the underlying web site, this code does nothing, and does it slowly since the query must time out.

Consequently, I am putting this module through a retraction cycle. Currently, this module will warn with a stack trace when loaded, and on every call to new()|/new. With the first release after June 1 2018, loading this module will produce a fatal error. On or after the first of December 2018 I will delete this module from CPAN. It will still be available via BackPAN ( or GitHub (

If you are looking for a Perl geocoding module that does not need a product key, you might try Geo::Coder::OSM.


This module is RETRACTED. See the RETRACTION NOTICE above.

This package geocodes addresses by looking them up on the website. Because this site throttles access, this class does to, to one request every 15 seconds.


This class supports the following public methods:


 my $gc = Geo::Coder::Geocoder::US->new();

This static method instantiates a new Geo::Coder::Geocoder::US object. It takes named arguments debug and ua, each of which is handled by calling the same-named method. An attempt to use any other named argument will result in an exception.


This method accesses or modifies the debug attribute of the object. This attribute is unsupported in the sense that the author makes no commitment about what will happen if it is set to a true value.

At the moment, setting it to a true value causes the HTTP::Request and HTTP::Response objects to be dumped to standard error. But the author reserves the right to change this without notice.


 my @rslt = $gc->geocode(
     '1600 Pennsylvania Ave, Washington DC' );
 my $rslt = $gc->geocode(
     '1600 Pennsylvania Ave, Washington DC' );

This method geocodes the location given in its argument. It can also be called with named arguments:

 my @rslt = $gc->geocode(
     location => '1600 Pennsylvania Ave, Washington DC',

The only supported argument name is location; an attempt to use any other argument name will result in an exception.

The return is an array of zero or more hash references, each containing a geocoding of the location. Ambiguous locations will return more than one geocoding. A lookup failure results in a single hash with an {error} key. If called in scalar context you get the first geocoding (if any).

If there is a network problem of some sort, nothing is returned. Regardless of the success or failure of the operation, the HTTP::Response object that represents the status of the network call is accessible via the response() method.


 print 'Previous operation returned ',

This method returns the HTTP::Response object from the previous call to geocode(). If no such call has been made, the return is undefined.


This method accesses or modifies the LWP::UserAgent object used to access

If called as an accessor, it returns the object currently in use.

If called as a mutator, the argument must be an object of class LWP::UserAgent (or one of its subclasses).


The Geo-Coder-US distribution by Schuyler Erle and Jo Walsh (see geocodes U.S. addresses directly from the TIGER/Line database. I believe this underlies You should prefer Geo-Coder-US over this package for bulk or otherwise serious geocoding.

The Geo-Coder-OSM distribution by gray (see uses the Open Street Map API, and offers global coverage. Within the USA it seems to be more finicky about specifying addresses than, and tends to return multiple hits with a relevancy score.


Support is by the author. Please file bug reports at, or in electronic mail to the author.


Thomas R. Wyant, III wyant at cpan dot org


Copyright (C) 2011-2018 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.