View on
MetaCPAN
Per Henrik Johansen > Geo-GeoNames-0.03 > Geo::GeoNames

Download:
Geo-GeoNames-0.03.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.03   Source   Latest Release: Geo-GeoNames-1.12

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.

syntax highlighting: