Geo::Coder::Geocoder::US - Geocode a location using http://geocoder.us/
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(); } }
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.
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.
Geo::Coder::Geocoder::US
debug
ua
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.
HTTP::Request
HTTP::Response
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.
location
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).
{error}
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 ', $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.
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).
The Geo-Coder-US distribution by Schuyler Erle and Jo Walsh (see http://search.cpan.org/dist/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.
Geo-Coder-US
The Geo-Coder-TomTom distribution by gray (see http://search.cpan.org/dist/Geo-Coder-TomTom) 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.
Geo-Coder-TomTom
Support is by the author. Please file bug reports at http://rt.cpan.org, 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.
To install Geo::Coder::Geocoder::US, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Geo::Coder::Geocoder::US
CPAN shell
perl -MCPAN -e shell install Geo::Coder::Geocoder::US
For more information on module installation, please visit the detailed CPAN module installation guide.