ePages 7.27.0 - DE_EPAGES/Address/API/GeoData.pm

Package DE_EPAGES::Address::API::GeoData

Wrapper for Google Geocoding API.

Use function GetGeoData to query Google using this function expect an hash with address data and an output filter as arguments. Two output filter are part of this API : FilterAll and FilterLocation

Example Request constructed by function GetGeoData: http://maps.googleapis.com/maps/api/geocode/json?address=Leutragraben+1+07749+Jena+Germany&sensor=false

For convenience function GetGeoLocation is provided, which returns Longitude and latitude for given address. It uses internaly output filter FilterLocation to achieve this.
Word of caution the number of calls are limited 2500 per 24h. Repeatedly exceeding the limit may lead to temporary blocking or banning your IP.

Example
# return latitude and longitude in hash
my $hGeoLocation = GetGeoLocation($hAddress)

# return custom data from Google's response
sub FilterLocation ($) {
    my ($Response) = @_;
    TestObject( 'Response', $Response, 'HTTP::Response' );
    my $hResult   = from_json( $Response->decoded_content );
    my $Status    = $hResult->{status};
    my $hLocation = undef;

    if ( $Status eq 'OK' || scalar $hResult->{results} == 1 ) {
    ($hLocation) = map { $_->{geometry}{location} } @{ $hResult->{results} };
    }
    return $hLocation;
}

my $hGeoLocation = GetGeoData($hAddress, \&FilterLocation);
@EXPORT_OK
BuildAddress
GetGeoData
GetGeoLocation
FilterAll
FilterLocation

Functions

BuildAddress
FilterAll
FilterLocation
GetGeoData
GetGeoLocation

BuildAddress

Build up google geo location request param string.

Syntax
BuildAddress( $hAddr );
Input
$hAddr (ref.hash.)
address like GetGeoData
Return
$Áddress (string)
address string

FilterAll

Output filter for GetGeoData. Return data as hash. ref. from HTTP::Response of Google Geocoding API.

Syntax
$hLocation = FilterAll( $Response );
Input
$Response (HTTP::Response)
goole response
Return
$hLocation (hash.ref. or undef)
contain key lat, lng

FilterLocation

Output filter for GetGeoData. Extract location information from HTTP::Response of Google Geocoding API. This function assumes only one location is in the result.

Syntax
$hLocation = FilterLocation( $Response );
Input
$Response (HTTP::Response)
google response
Return
$hLocation (hash.ref. or undef)
contain key lat, lng

GetGeoData

Query Google Geo Coding API with $hAddress as address parameters. Google's response will be validated by checking decoded body, the status key must be 'OK' or 'ZERO_RESULTS' indicating that the request was correctly processed, otherwise an error will be raised. As final step $cOutputFilter is executed to to extract the components of interest.

Example request: http://maps.googleapis.com/maps/api/geocode/json?address=Leutragraben+1+07743+Jena+Germany&sensor=false

List of errors:

Syntax
$hCustomData = GetGeoData( $hAddress, $cOutputFilter );
Input
$hAddress (hash.ref.)
Following address contains following keys:
  • Street - Leutragraben 1
  • Zipcode - 07743
  • City - Jena
  • Country - Germany (english country name)

$cOutputFilter (sub)
sub to handle Google's response; input is HTTP::Response
with JSON structure as body, output must be a scalar value
Return
$hLocation (any)
output depend on $cCustomFilter

GetGeoLocation

Convenience function wrapping GetGeoData. Return longitude (lng) and latitude (lat) for given address. Uses output filter FilterLocation

Syntax
GetGeoLocation( $hAddress );
Input
$hAddress (ref.hash.)
address like GetGeoData
Return
$ReturnVariable (ref.hash.)
hash with keys lng & lat