GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Geo::Coder::Multiple(3) User Contributed Perl Documentation Geo::Coder::Multiple(3)

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 = {
    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";
  };

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".

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)

  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:

  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)

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

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

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

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.

Hey! The above document had some coding errors, which are explained below:
Around line 306:
You forgot a '=back' before '=head2'
2010-03-23 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.