NAME

WWW::Gazetteer::HeavensAbove - Find location of world towns and cities

SYNOPSIS

use WWW::Gazetteer::HeavensAbove;

my $atlas = WWW::Gazetteer::HeavensAbove->new;

# simple query using ISO 3166 codes
my @towns = $atlas->fetch( GB => 'Bacton' );
print $_->{name}, ", ", $_->{elevation}, $/ for @towns;

# simple query using heavens-above.com codes
my @towns = $atlas->query( UK => 'Bacton' );
print $_->{name}, ", ", $_->{elevation}, $/ for @towns;

# big queries can use a callback (and return nothing)
$atlas->fetch(
    GB => 'Bacton',
    sub { print $_->{name}, ", ", $_->{elevation}, $/ for @_ }
);

# the heavens-above.com site supports complicated queries
my @az = $atlas->fetch( FR => 'a*z' );

DESCRIPTION

A gazetteer is a geographical dictionary (as at the back of an atlas). The WWW::Gazetteer::HeavensAbove module uses the information at http://www.heavens-above.com/countries.asp to return geographical location (longitude, latitude, elevation) for towns and cities in countries in the world.

Once a WWW::Gazetteer::HeavensAbove objects is created, use the fetch() method to return lists of hashrefs holding all the information for the matching cities.

A city tructure looks like this:

$lesparis = {
    'latitude'   => '45.633',
    'regionname' => 'Region',
    'region'     => 'Rhône-Alpes',
    'alias'      => 'Les Paris',
    'elevation'  => '508 m',
    'longitude'  => '5.733',
    'name'       => 'Paris',
};

Note: the 'regioname' attribute is the local name of a region (this can change from country to country).

Methods

new()

Return a new WWW::Gazetteer::UserAgent, ready to fetch() cities for you.

fetch( $code, $city [, $callback ] )

Return a list of cities matching $city, within the country with ISO 3166 code $code (not all codes are supported by heavens-above.com).

This method always returns an array of city structures. If the request returns a lot of cities, you can pass a callback routine to fetch(). This routine receives the list of city structures as @_. If a callback method is given to fetch(), fetch() will return an empty list.

Note: heavens-above.com doesn't use ISO 3166 codes, but its own country codes. If you want to use those directly, please see the query() method. (And read the source for the full list of HA codes.)

query( $code, $searchstring [, $callback ] );

This method is the actual method called by fetch(). The only difference is that $code is the heavens-above.com specific country code, instead of the ISO 3166 code.

TODO

Allow the script to run correctly when a query returns more than 200 answers (stops at the 200 firsts for the moment).

Better network errors handling.

Find an appropriate interface with Leon, and adhere to it.

BUGS

WWW::Gazetteer::HeavensAbove does not work correctly yes with the US, since the database returns State and County. I suppose this is the only country that behaves this way, due to the way the database was created.

Bugs in the database are not from heavens-above.com, since they "put together and enhanced" data from the following two sources: US Geological Survey (http://geonames.usgs.gov/index.html) for the USA and dependencies, and The National Imaging and Mapping Agency (http://www.nima.mil/gns/html/index.html) for all other countries.

See also: http://www.heavens-above.com/ShowFAQ.asp?FAQID=100

AUTHOR

Philippe "BooK" Bruhat <book@cpan.org>.

This module was a script, before I found out about Leon Brocard's WWW::Gazetteer module. Thanks! And, erm, bits of the documentation were stolen from WWW::Gazetteer.

Thanks to Alain Zalmanski (from http://www.fatrazie.com/) for asking me for all that geographical data in the first place.

SEE ALSO

"How I captured thousands of Afghan cities in a few hours", one of my lightning talks at YAPC::Europe 2002 (Munich). Slides will be online someday.

WWW::Gazetteer, the original, by Léon Brocard.

The use Perl discussion that had me write this module from the original script: http://use.perl.org/~acme/journal/8079

COPYRIGHT

This module is free software; you can redistribute it or modify it under the same terms as Perl itself.

cpanm WWW::Gazetteer::HeavensAbove

perl -MCPAN -e shell
install WWW::Gazetteer::HeavensAbove