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)
403   Unspecified failure

NOTES

All cache objects used must support 'get' and 'set' 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

SEE ALSO

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.

cpanm Geo::Coder::Multiple

perl -MCPAN -e shell
install Geo::Coder::Multiple