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:

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.

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