NAME
Geo::Coder::Geocoder::US - Geocode a location using http://geocoder.us/
SYNOPSIS
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();
}
}DESCRIPTION
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 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.
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.
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-2014 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.