Geo::Coder::Multiple - Module to tie together multiple Geo::Coder::* modules
# for Geo::Coder::Jingle and Geo::Coder::Bells use Geo::Coder::Jingle; use Geo::Coder::Bells; use Geo::Coder::Multiple; my $options = { stats_cache => $stats_cache, results_cache => $results_cache, }; 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( $geocoder_options ); my $bells = Geo::Coder::Jingle->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"; };
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.
Geo::Coder::Multiple
Constructs a new Geo::Coder::Multiple object and returns it. If no options are specified, caching for the geocoder source statistics will be done in memory for the life of the object and no caching will be done for the geocoding results.
KEY VALUE ----------- -------------------- stats_cache cache object reference (optional) results_cache cache object reference (optional)
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
my $options = { location => $location, results_cache => $cache, }; my $found_location = $geocoder_multi->geocode( $options );
The arguments to the geocode method are:
geocode
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 cached (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').
geocoder
The response_code key will contain the response code. The possible values are:
response_code
200 Success 210 Success (from cache) 401 Unable to find location 402 All geocoder limits reached (not yet implemented)
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().
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
Alistair Francis, <alistair.francis@lokku.com>
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.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install Geo::Coder::Multiple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Geo::Coder::Multiple
CPAN shell
perl -MCPAN -e shell install Geo::Coder::Multiple
For more information on module installation, please visit the detailed CPAN module installation guide.