NAME

Geo::Coder::Multiple - Module to tie together multiple Geo::Coder::* modules

SYNOPSIS

  # for Geo::Coder::Jingle and Geo::Coder::Bells
  use Geo::Coder::Jingle;
  use Geo::Coder::Bells;
  use Geo::Coder::Multiple;
  
  my $options = {
    cache   => $cache_object,
  };

  my $geocoder_multi = Geo::Coder::Multiple->new( $options );

  my $jingle = Geo::Coder::Jingle->new( apikey => 'Jingle API Key' );

  my $jingle_options = {
    geocoder    => $jingle,
    daily_limit => 25000,
  };

  my $geocoder_multi->add_geocoder( $jingle_options );

  my $bells = Geo::Coder::Bells->new( apikey => 'Bells API Key' );

  my $bells_options = {
    geocoder    => $bells,
    daily_limit => 4000,
  };

  my $geocoder_multi->add_geocoder( $bells_options );

  my $location = $geocoder_multi->geocode( { location => '82 Clerkenwell Road, London, EC1M 5RF' } );

  if( $location->{response_code} == 200 ) {
    print $location->{address} ."\n";
  };

DESCRIPTION

Geo::Coder::Multiple is a wrapper for multiple Geo::Coder::* modules.

Most free geocoding datasource specify a limit to the number of queries which can be sent from an IP or made using an API key in a 24 hour period. This module balances the incoming requests across the available sources to ensure individual limits are exceeded only when the total limit is exceeded.

The algorithm for load balancing takes into account the limit imposed by the source per 24 hour period.

Any network or source outages are handled by "Geo::Coder::Multiple".

METHOD

new

Constructs a new "Geo::Coder::Multiple" object and returns it. If no options are specified, no caching will be done for the geocoding results.

The 'normalize_code_ref' is a code reference which is used to normalize location strings to ensure that all cache keys are normalized for correct lookup.

  KEY                   VALUE
  -----------           --------------------
  cache                 cache object reference  (optional)
  normalize_code_ref    A normalization code ref (optional)

add_geocoder

  my $jingle = Geo::Coder::Jingle->new( apikey => 'Jingle API Key' );
  my $jingle_limit = 25000;

  my $options = {
    geocoder    => $jingle,
    daily_limit => $jingle_limit,
  };

  my $geocoder_multi->add_geocoder( $options );

In order to load balance geocode queries across multiple sources, these sources must be added to the list of available sources.

Before any geocoding can be performed, at least one geocoder must be added to the list of available geocoders.

If the same geocoder is added twice, only the instance added first will be used. All other additions will be ignored.

  KEY                   VALUE
  -----------           --------------------
  geocoder              geocoder reference object
  limit                 geocoder source limit per 24 hour period

geocode

  my $options = {
    location        => $location,
    results_cache   => $cache,
  };

  my $found_location = $geocoder_multi->geocode( $options );

The arguments to the "geocode" method are:

  KEY                   VALUE
  -----------           --------------------
  location              location string to pass to geocoder
  results_cache         reference to a cache object, will over-ride the default
  no_cache              if set, the result will not be retrieved or set in cache (off by default)

This method is the basis for the class, it will retrieve result from cache first, and return if cache hit.

If the cache is missed, the "geocode" method is called, with the location as the argument, on the next available geocoder object in the sequence.

If called in an array context all the matching results will be returned, otherwise the first result will be returned.

A matching address will have the following keys in the hash reference.

  KEY                   VALUE
  -----------           --------------------
  response_code         integer response code (see below)
  address               matched address
  latitude              latitude of matched address
  longitude             longitude of matched address
  country               country of matched address (not available for all geocoders)
  geocoder              source used to lookup address

The "geocoder" key will contain a string denoting which geocoder returned the results (eg, 'jingle').

The "response_code" key will contain the response code. The possible values are:

  200   Success 
  210   Success (from cache)
  401   Unable to find location
  402   All geocoder limits reached (not yet implemented)

NOTES

All cache objects used must support 'get', 'set' and 'remove' methods.

The input (location) string is expected to be in utf-8. Incorrectly encoded strings will make for unreliable geocoding results. All strings returned will be in utf-8. returned latitude and longitude co-ordinates will be in WGS84 format.

In the case of an error, this module will print a warning and then may call die().

Geo::Coder Interface

The Geo::Coder::* modules added to the geocoding source list must have a "geocode" method which takes a single location string as an argument.

Currently supported Geo::Coder::* modules are:

  Geo::Coder::Bing
  Geo::Coder::Google
  Geo::Coder::Multimap
  Geo::Coder::Yahoo

AUTHOR

Alistair Francis, http://search.cpan.org/~friffin/

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10 or, at your option, any later version of Perl 5 you may have available.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 306:: You forgot a '=back' before '=head2'