NAME

Net::GeoPlanet - Access Yahoo's GeoPlanet location service

SYNOPSIS

        use Net::GeoPlanet;
        use Data::Dumper;

        my $geoplanet = Net::GeoPlanet->new(api_key => $api_key);

        print Dumper($geoplanet->places(place => "Woodside, NY 11377"));

        print Dumper($geoplanet->place(
                                        woeid => "2507854",
                                        format => "json"
                                ));

        print Dumper($geoplanet->parent(
                                        woeid => "638242",
                                        select => "long",
                                        lang => "fr-CA"
                                ));

ABOUT

Yahoo! GeoPlanet helps bridge the gap between the real and virtual worlds by providing an open, permanent, and intelligent infrastructure for geo-referencing data on the Internet.

For more information see http://developer.yahoo.com/geo/

METHODS

new

Creates the object that will be used. It takes an arguement, which is the key assigned to you by Yahoo.

Returns a collection of places that match a specified place name, and optionally, a specified place type. The resources in the collection are long representations of each place (unless short representations are explicitly requested).

place

Returns a resource containing the long representation of a place (unless a short representation is explicitly requested).

parent

Returns a resource for the parent of a place. A place has only one parent. The resource is the short representation of the parent (unless a long representation is requested).

ancestors

Returns a collection of places in the parent hierarchy (the parent, the parent of parent, etc.). The resources in the collection are short representations of each place (unless a long representation is specifically requested).

belongtos

Returns a collection of places that have a place as a child or descendant (child of a child, etc). The resources in the collection are short representations of each place (unless a long representation is specifically requested).

neighbors

Returns a collection of places that neighbor of a place. The resources in the collection are short representations of each place (unless a long representation is requested).

Note that neighbors are not necessarily geographically contiguous.

siblings

Returns a collection of places that are siblings of a place. Siblings share the same parent and place type as the given place. The resources in the collection are short representations of each place (unless a long representation is requested).

children

Returns a collection of places that are children of a place. The resources in the collection are short representations of each place (unless a long representation is requested).

placetypes

Returns the complete collection of place types supported in GeoPlanet. The resources in the collection each describe a single place type.

placetype

Returns a resource that describes a single place type.

MATRIX PARAMETERS

GeoPlanet supports several parameters (name/value pairs) called "matrix parameters" that allow users to request small portions of potentially large collections. Matrix parameters follow the collection name or filter they refer to. The place, parent, ancestors and palcetype subroutines do not support these parameters.

start

Skip first 'N' results

        $geoplanet->places(place => "Woodside, NY 11377", start => 1);

count

Return a maximum of N results. A count of 0 is interpreted as 'no maximum'

        $geoplanet->children(woeid => "23424977", count => 5);

QUERY PARAMETERS

GeoPlanet supports several parameters (name/value pairs) called "query parameters" that allow users to specify a particular language or format for the response. Query parameters follow the resource/collection name, filter, and any matrix parameters.

lang

Return names in specified language (RFC 4646)

        $geoplanet->places(place => "Woodside, NY 11377", lang => "fr-CA");

format

Return results in specified format. Accepted values are "xml", "json", "geojson".

        $geoplanet->neighbors(woeid => "2347563", format =>"json");

callback

Return JSON results wrapped in a JavaScript function call. Only used when format=json or format=geojson

        $geoplanet->neighbors(
                woeid => "2347563",
                format =>"json",
                callback => "myfunction"
        );

select

Return results in specified representation. Accepted values are "short", "long".

        $geoplanet->belongtos(woeid => "23424900", select => "short");

BUGS

None known

DEVELOPERS

The latest code for this module can be found at

        http://www.exit2shell.com/cgi-bin/cvsweb.cgi/Net-GeoPlanet/

AUTHOR

Written by Steven Kreuzer <skreuzer@exit2shell.com>