Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Geo::GeoNames(3)      User Contributed Perl Documentation     Geo::GeoNames(3)

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:

       o   Get an account

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

       o   Respond to the email

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

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	through	GitHub issues
       <https://github.com/briandfoy/geo-geonames/issues>

SEE ALSO
       o   <http://www.geonames.org/export>

       o   <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>" and
       Nicolas Mendoza,	"<mendoza@pvv.ntnu.no>"

COPYRIGHT AND LICENSE
       Copyright (C) 2007-2008 by Per Henrik Johansen

       This library is available under the Artistic License 2.0.

perl v5.24.1			  2017-04-16		      Geo::GeoNames(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | RETURNED DATASTRUCTURE | BUGS | SEE ALSO | SOURCE AVAILABILITY | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Geo::GeoNames&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help