NAME

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

• Get an account

  Go to <http://www.geonames.org/login>

• Respond to the email
• Login and enable your account for free access

  <http://www.geonames.org/enablefreewebservice>

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.

ua( $ua )

With a single argument, set the UserAgent to be used by all API calls and return that UserAgent object. Supports Mojo::UserAgent and LWP::UserAgent derivatives.

With no arguments, return the current UserAgent used.

username( $username )

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

default_ua

Returns the default UserAgent used a Mojo::UserAgent object that carps on errors.

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 method 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
        name_startsWith => $name_startsWith
        countryBias     => $countryBias
        cities          => $cities
        operator        => $operator
        searchlang      => $searchlang
        charset         => $charset
        fuzzy           => $fuzzy
        north           => $north
        west            => $west
        east            => $east
        south           => $south
        orderby         => $orderby
    

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

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 method.

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 method.

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 method.

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 method.

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 method.

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 method.

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 method 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 method.

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 method.

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 method.

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 method.

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 method.

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 method.

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 method.

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 method.

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

get(arg => $arg)

Returns information about a given place based on a geonameId.

        geonameId  => $geonameId
        lang       => $lang
        style      => $style (Seems to be ignored, although documented)
    

geonamesId must be supplied to this method. lang and style are optional.

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

hiearchy(arg => $arg)

Returns all GeoNames higher up in the hierarchy of a place based on a geonameId.

    geonameId => $geonameId
    style     => $style (Not documented, but seems to be respected)
    

geonamesId must be supplied to this method. style is optional.

For a thorough description of the arguments, see <http://www.geonames.org/export/place-hierarchy.html#hierarchy>

children(arg => $arg)

Returns the children (admin divisions and populated places) for a given geonameId.

    geonameId => $geonameId
    style     => $style (Not documented, but seems to be respected)
    

geonamesId must be supplied to this method. style is optional.

For a thorough description of the arguments, see <https://www.geonames.org/export/place-hierarchy.html>

RETURNED DATASTRUCTURE

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

Please report any bugs found or feature requests through GitHub issues <https://github.com/briandfoy/geo-geonames/issues>

SEE ALSO

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

SOURCE AVAILABILITY

AUTHOR

Currently maintained by brian d foy, "<brian.d.foy@gmail.com>" and Nicolas Mendoza, "<mendoza@pvv.ntnu.no>"

COPYRIGHT AND LICENSE

This library is available under the Artistic License 2.0.