NAME

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

SYNOPSIS

  use Geo::GeoNames;
  use Data::Dumper;
  my $geo = new Geo::GeoNames();
  
  # 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};
  
  # Dump the data structure into readable form
  # This also will show the attributes to each found location
  Data::Dumper->Dump()
  
  # Make a query based on postcode
  $result = $geo->postalcode_search(postalcode => "1630", maxRows => 3, style => "FULL"); 

DESCRIPTION

Provides a perl interface to the webservices found at http://ws.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. If more than one match is found, a list of locations will be returned.

METHODS

new

  $geo = Geo::GeoNames->new()
  $geo = Geo::GeoNames->new(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://ws.geonames.org and is the only url, to my knowledge, that provides the services needed by this module.

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
  adminCode1 => $admin1
  adminCode2 => $admin2
  adminCode3 => $admin3
  fclass => $fclass
  lang => $lang
  type => $type
  style => $style

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

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

Both lat and lng must be supplied to this function.

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

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.

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 (after doing a Data::Dumper->Dump($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().

BUGS

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

SEE ALSO

http://www.geonames.org/export

SOURCE AVAILABILITY

The source code for this module is available from SVN at http://code.google.com/p/geo-geonames

AUTHOR

Per Henrik Johansen, <perhenrik@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 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.