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

SYNOPSYS
      use WWW::Gazetteer;
      my $g = WWW::Gazetteer->new('calle');
      my @londons = $g->find(UK => 'London');
      my $london = $londons[0];
      print $london->{longitude}, ", ", $london->{latitude}, "\n";

DESCRIPTION
    A gazetteer is a geographical dictionary (as at the back of an atlas).
    The "WWW::Gazetteer" module is a generic interface to the
    "WWW::Gazetteer::*" modules which can return geographical location
    (longitude, latitude, elevation) for towns and cities in countries in
    the world.

    This is a factory module which dispatches to one of the many
    "WWW::Gazetteer::*" modules. This provides a simple interface and lets
    the subclasses actually provide an interface to the online gazetteers.
    You may think of this as the DBI and the subclasses as the DBDs.

    Valid subclasses as of this release are: "WWW::Gazetteer::Calle". To
    create a gazetteer object, pass the name of the subclass as the first
    argument to new:

      my $g = WWW::Gazetteer->new('calle');

    Calling find($country => $town) will return a list of hashrefs with the
    country, town, longitude, and latitude information. Additional
    information such as elevation may also be available. You should check
    the documentation of your subclass for the particular features that it
    supports.

      my @londons = $g->find(UK => 'London');
      my $london = $londons[0];
      print $london->{longitude}, ", ", $london->{latitude}, "\n";
      # prints -0.1167, 51.5000

METHODS
  new()

    This returns a new WWW::Gazetteer::* object. It has one argument, the
    name of the subclass (and optionally configuration for the subclass):

      use WWW::Gazetteer;
      my $g = WWW::Gazetteer->new('calle');

  find()

    The find method looks up geographical information and returns it to you.
    It takes in a country and a city, with the recommended syntax being ISO
    3166 code and city name.

    Note that there may be more than one town or city with that name in the
    country. You will get a list of hashrefs for each town/city.

      my @londons = $g->find("UK" => "London");

    Check the documentation of your subclass for which countries, which
    syntax it supports, and what information it returns.

SEE ALSO
    the WWW::Gazetteer::Calle manpage, the WWW::Gazetteer::HeavensAbove
    manpage.

COPYRIGHT
    Copyright (C) 2002, Leon Brocard

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

AUTHOR
    Leon Brocard, acme@astray.com. Thanks to Philippe 'BooK' Bruhat.