brian d foy > Geo-GeoNames > Geo::GeoNames

Download:
Geo-GeoNames-1.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.01   Source   Latest Release: Geo-GeoNames-1.01_01

NAME ^

Geo::GeoNames - Perform geographical queries using GeoNames Web Services

SYNOPSIS ^

        use Geo::GeoNames;
        my $geo = Geo::GeoNames->new( username => $username );

        # make a query based on placename
        my $result = $geo->search(q => 'Fredrikstad', maxRows => 2);

        # print the first result
        print " Name: " . $result->[0]->{name};
        print " Longitude: " . $result->[0]->{lng};
        print " Lattitude: " . $result->[0]->{lat};

        # Make a query based on postcode
        my $result = $geo->postalcode_search(
                postalcode => "1630", maxRows => 3, style => "FULL"
                );

DESCRIPTION ^

Before you start, get a free GeoNames account and enable it for access to the free web service:

Provides a perl interface to the webservices found at http://api.geonames.org. That is, given a given placename or postalcode, the module will look it up and return more information (longitude, lattitude, etc) for the given placename or postalcode. Wikipedia lookups are also supported. If more than one match is found, a list of locations will be returned.

METHODS ^

new
        $geo = Geo::GeoNames->new( username => '...' )
        $geo = Geo::GeoNames->new( username => '...', url => $url )

Constructor for Geo::GeoNames. It returns a reference to an Geo::GeoNames object. You may also pass the url of the webservices to use. The default value is http://api.geonames.org and is the only url, to my knowledge, that provides the services needed by this module. The username parameter is required.

username( $username )

With a single argument, set the GeoNames username and return that username. With no arguments, return the username.

default_url

Returns http://api.geonames.org.

url( $url )

With a single argument, set the GeoNames url and return that url. With no arguments, return the url.

geocode( $placename )

This function is just an easy access to search. It is the same as saying:

        $geo->search( q => $placename );
search( arg => $arg )

Searches for information about a placename. Valid names for arg are as follows:

        q              => $placename
        name           => $placename
        name_equals    => $placename
        maxRows        => $maxrows
        startRow       => $startrow
        country        => $countrycode
        continentCode  => $continentcode
        adminCode1     => $admin1
        adminCode2     => $admin2
        adminCode3     => $admin3
        fclass         => $fclass
        featureClass   => $fclass,
        featureCode    => $code
        lang           => $lang
        type           => $type
        style          => $style
        isNameRequired => $isnamerequired
        tag            => $tag

One, and only one, of q, name, or name_equals must be supplied to this function.

fclass is deprecated.

For a thorough description of the arguments, see http://www.geonames.org/export/geonames-search.html

find_nearby_placename( arg => $arg )

Reverse lookup for closest placename to a given coordinate. Valid names for arg are as follows:

        lat     => $lat
        lng     => $lng
        radius  => $radius
        style   => $style
        maxRows => $maxrows

Both lat and lng must be supplied to this function.

For a thorough descriptions of the arguments, see http://www.geonames.org/export

find_nearest_address(arg => $arg)

Reverse lookup for closest address to a given coordinate. Valid names for arg are as follows:

        lat => $lat
        lng => $lng

Both lat and lng must be supplied to this function.

For a thorough descriptions of the arguments, see http://www.geonames.org/maps/reverse-geocoder.html

US only.

find_nearest_intersection(arg => $arg)

Reverse lookup for closest intersection to a given coordinate. Valid names for arg are as follows:

        lat => $lat
        lng => $lng

Both lat and lng must be supplied to this function.

For a thorough descriptions of the arguments, see http://www.geonames.org/maps/reverse-geocoder.html

US only.

find_nearby_streets(arg => $arg)

Reverse lookup for closest streets to a given coordinate. Valid names for arg are as follows:

        lat => $lat
        lng => $lng

Both lat and lng must be supplied to this function.

For a thorough descriptions of the arguments, see http://www.geonames.org/maps/reverse-geocoder.html

US only.

postalcode_search(arg => $arg)

Searches for information about a postalcode. Valid names for arg are as follows:

        postalcode => $postalcode
        placename  => $placename
        country    => $country
        maxRows    => $maxrows
        style      => $style

One, and only one, of postalcode or placename must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

find_nearby_postalcodes(arg => $arg)

Reverse lookup for postalcodes. Valid names for arg are as follows:

        lat     => $lat
        lng     => $lng
        radius  => $radius
        maxRows => $maxrows
        style   => $style
        country => $country

Both lat and lng must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

postalcode_country_info

Returns a list of all postalcodes found on GeoNames. This function takes no arguments.

country_info(arg => $arg)

Returns country information. Valid names for arg are as follows:

        country => $country
        lang    => $lang

For a thorough description of the arguments, see http://www.geonames.org/export

find_nearby_wikipedia(arg => $arg)

Reverse lookup for Wikipedia articles. Valid names for arg are as follows:

        lat     => $lat
        lng     => $lng
        radius  => $radius
        maxRows => $maxrows
        lang    => $lang
        country => $country

Both lat and lng must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

find_nearby_wikipediaby_postalcode(arg => $arg)

Reverse lookup for Wikipedia articles. Valid names for arg are as follows:

        postalcode => $postalcode
        country    => $country
        radius     => $radius
        maxRows    => $maxrows

Both postalcode and country must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

wikipedia_search(arg => $arg)

Searches for Wikipedia articles. Valid names for arg are as follows:

        q       => $placename
        maxRows => $maxrows
        lang    => $lang
        title   => $title

q must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

wikipedia_bounding_box(arg => $arg)

Searches for Wikipedia articles. Valid names for arg are as follows:

        south   => $south
        north   => $north
        east    => $east
        west    => $west
        lang    => $lang
        maxRows => $maxrows

south, north, east, and west and must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

cities(arg => $arg)

Returns a list of cities and placenames within the bounding box. Valid names for arg are as follows:

        south   => $south
        north   => $north
        east    => $east
        west    => $west
        lang    => $lang
        maxRows => $maxrows

south, north, east, and west and must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

country_code(arg => $arg)

Return the country code for a given point. Valid names for arg are as follows:

        lat    => $lat
        lng    => $lng
        radius => $radius
        lang   => $lang

Both lat and lng must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

earthquakes(arg => $arg)

Returns a list of cities and placenames within the bounding box. Valid names for arg are as follows:

        south        => $south
        north        => $north
        east         => $east
        west         => $west
        date         => $date
        minMagnitude => $minmagnitude
        maxRows      => $maxrows

south, north, east, and west and must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

find_nearby_weather(arg => $arg)

Return the country code for a given point. Valid names for arg are as follows:

        lat => $lat
        lng => $lng

Both lat and lng must be supplied to this function.

For a thorough description of the arguments, see http://www.geonames.org/export

RETURNED DATASTRUCTURE ^

The datastructure returned from methods in this module is an array of hashes. Each array element contains a hash which in turn contains the information about the placename/postalcode.

For example, running the statement

        my $result = $geo->search(
                q => "Fredrikstad", maxRows => 3, style => "FULL"
                );

yields the result:

        $VAR1 = {
                'population' => {},
                'lat' => '59.2166667',
                'elevation' => {},
                'countryCode' => 'NO',
                'adminName1' => "\x{d8}stfold",
                'fclName' => 'city, village,...',
                'adminCode2' => {},
                'lng' => '10.95',
                'geonameId' => '3156529',
                'timezone' => {
                        'dstOffset' => '2.0',
                        'content' => 'Europe/Oslo',
                        'gmtOffset' => '1.0'
                        },
                'fcode' => 'PPL',
                'countryName' => 'Norway',
                'name' => 'Fredrikstad',
                'fcodeName' => 'populated place',
                'alternateNames' => 'Frederikstad,Fredrikstad,Fredrikstad kommun',
                'adminCode1' => '13',
                'adminName2' => {},
                'fcl' => 'P'
                };

The elements in the hashes depends on which style is passed to the method, but will always contain name, lng, and lat except for postalcode_country_info(), find_nearest_address(), find_nearest_intersection(), and find_nearby_streets().

BUGS ^

Not a bug, but the GeoNames services expects placenames to be UTF-8 encoded, and all data received from the webservices are also UTF-8 encoded. So make sure that strings are encoded/decoded based on the correct encoding.

Please report any bugs found or feature requests to https://rt.cpan.org//Dist/Display.html?Queue=geo-geonames

SEE ALSO ^

http://www.geonames.org/export http://www.geonames.org/export/ws-overview.html

SOURCE AVAILABILITY ^

The source code for this module is available from Github at https://github.com/briandfoy/geo-geonames

AUTHOR ^

Per Henrik Johansen, <per.henrik.johansen@gmail.com>.

Currently maintained by brian d foy, <brian.d.foy@gmail.com>.

COPYRIGHT AND LICENSE ^

Copyright (C) 2007-2008 by Per Henrik Johansen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: