NAME

Geo::Coder::Geocoder::US - Geocode a location using http://geocoder.us/

SYNOPSIS

 # (DEPRECATED)
 
 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: ",
             $rslt->response()->status_line();
     }
 }

RETRACTION NOTICE

This perl module makes use of the http://geocoder.us/ 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 (http://backpan.perl.org/authors/id/W/WY/WYANT/) or GitHub (https://github.com/trwyant/perl-Geo-Coder-Geocoder-US.)

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

DESCRIPTION

This module is RETRACTED. See the RETRACTION NOTICE above.

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

METHODS

This class supports the following public methods:

new

 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.

debug

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.

geocode

 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.

response

 print 'Previous operation returned ',
     $gc->response()->status_line();

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

ua

This method accesses or modifies the LWP::UserAgent object used to access http://geocoder.us/.

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

SEE ALSO

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

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

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2011-2017 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.