Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Geo::Coder::Multiple(3User Contributed Perl DocumentatiGeo::Coder::Multiple(3)

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

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.

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

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

perl v5.32.0			  2010-03-23	       Geo::Coder::Multiple(3)

NAME | SYNOPSIS | DESCRIPTION | METHOD | NOTES | Geo::Coder Interface | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Geo::Coder::Multiple&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help