NAME

NAME
Geo::Coder::Yahoo - Geocode addresses with the Yahoo! API

SYNOPSIS
Provides a thin Perl interface to the Yahoo! Geocoding API.

use Geo::Coder::Yahoo;

my $geocoder = Geo::Coder::Yahoo->new(appid => 'my_app' );
my $location = $geocoder->geocode( location => 'Hollywood and Highland, Los Angeles, CA' );

OFFICIAL API DOCUMENTATION
Read more about the API at
<http://developer.yahoo.net/maps/rest/V1/geocode.html>.

PROXY SETTINGS
We use the standard proxy setting environment variables via LWP. See the
LWP documentation for more information.

METHODS
new
Geo::Coder::Yahoo->new(appid => $appid)
Geo::Coder::Yahoo->new(appid => $appid, on_error => sub { ... })

Instantiates a new object.

appid specifies your Yahoo Application ID. You can register at
<http://api.search.yahoo.com/webservices/register_application>.

If you don't specify it here you must specify it when calling geocode.

on_error specifies an error handler to be called if the HTTP response
code does not indicate success. The subroutine is called with the
geocode object as the first argument and the HTTP::Response object as
the second. The return value from the subroutine is used as the return
value from "geocode".

geocode( location => $location )
Parameters are the URI arguments documented on the Yahoo API page
(location, street, city, state, zip). You usually just need one of them
to get results.

"geocode" returns a reference to an array of results (an arrayref). More
than one result may be returned if the given address is ambiguous.

Each result in the arrayref is a hashref with data like the following
example:

{
'country' => 'US',
'longitude' => '-118.3387',
'state' => 'CA',
'zip' => '90028',
'city' => 'LOS ANGELES',
'latitude' => '34.1016',
'warning' => 'The exact location could not be found, here is the closest match: Hollywood Blvd At N Highland Ave, Los Angeles, CA 90028',
'address' => 'HOLLYWOOD BLVD AT N HIGHLAND AVE',
'precision' => 'address'
}

precision
The precision of the address used for geocoding, from specific
street address all the way up to country, depending on the precision
of the address that could be extracted. Possible values, from most
specific to most general are:

address
street
zip+4
zip+2
zip
city
state
country

warning
If the exact address was not found, the closest available match will
be noted here.

latitude
The latitude of the location.

longitude
The longitude of the location.

address
Street address of the result, if a specific location could be
determined.

city
City in which the result is located.

state
State in which the result is located.

zip Zip code, if known.

country
Country in which the result is located.

AUTHOR
Ask Bjørn Hansen, "<ask at develooper.com>"

BUGS
Please report any bugs or feature requests to "bug-geo-coder-yahoo at
rt.cpan.org", or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Geo-Coder-Yahoo>. I will
be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

perldoc Geo::Coder::Yahoo

You can also look for information at:

* Git Repository

The latest code is available from the git repository at
<git://git.develooper.com/Geo-Coder-Yahoo.git>. You can browse it at
<http://git.develooper.com/?p=Geo-Coder-Yahoo.git;a=summary>.

It is also at <http://github.com/abh/geo-coder-yahoo/tree/master>.

* CPAN Ratings

<http://cpanratings.perl.org/d/Geo-Coder-Yahoo>

* RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Geo-Coder-Yahoo>

* Search CPAN

<http://search.cpan.org/dist/Geo-Coder-Yahoo>

ACKNOWLEDGEMENTS
Thanks to Yahoo for providing this free API.

COPYRIGHT & LICENSE
Copyright 2005-2010 Ask Bjoern Hansen, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.