Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  GEO::CODER::GEOCODER::US (3)

.ds Aq ’


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 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-TomTom distribution by gray (see <>) uses the undocumented REST interface to the TomTom route planner. It seems to offer coverage in the U.S. approximately equivalent to this package, but without the enforced delay between queries.


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-2016 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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 GEO::CODER::GEOCODER::US (3) 2016-01-10

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.