/ 
Geo-Google-0.02
River stage zero No dependents
/ Geo::Google

NAME

Geo::Google - Perform geographical queries using Google Maps

SYNOPSIS

use strict;
use Data::Dumper;
use Geo::Google;

#My office
my $gonda_addr = '695 Charles E Young Dr S, Westwood, CA 90024';
#Stan's Donuts
my $stans_addr = '10948 Weyburn Ave, Westwood, CA 90024';

#Instantiate a new Geo::Google object.
my $geo = Geo::Google->new();

#Create Geo::Google::Location objects.  These contain
#latitude/longitude coordinates, along with a few other details
#about the locus.
my ( $gonda ) = $geo->location( address => $gonda_addr );
my ( $stans ) = $geo->location( address => $stans_addr );
print $gonda->latitude, " / ", $gonda->longitude, "\n";
print $stans->latitude, " / ", $stans->longitude, "\n";

#Create a Geo::Google::Path object.
my ( $donut_path ) = $geo->path($gonda,$stans);

#A path contains a series of Geo::Google::Segment objects with
#text labels representing turn-by-turn driving directions between
#the two loci.
my @segments = $donut_path->segments();

#This is the human-readable directions for the first leg of the
#journey.
print $segments[0]->text(),"\n";

#Geo::Google::Segment objects contain a series of
#Geo::Google::Location objects -- one for each time the segment
#deviates from a straight line to the end of the segment.
my @points = $segments[1]->points;
print $points[0]->latitude, " / ", $points[0]->longitude, "\n";

#Now how about some coffee nearby?
my @coffee = $geo->near($stans,'coffee');
#Too many.  How about some Coffee Bean & Tea Leaf?
@coffee = grep { $_->title =~ /Coffee.*?Bean/i } @coffee;

#Still too many.  Let's find the closest with a little trig and
#a Schwartzian transform
my ( $coffee ) = map { $_->[1] }
                 sort { $a->[0] <=> $b->[0] }
                 map { [ sqrt(
                          ($_->longitude - $stans->longitude)**2
                            +
                          ($_->latitude - $stans->latitude)**2
                         ), $_ ] } @coffee;

DESCRIPTION

Geo::Google provides access to the map data used by the popular Google Maps web application.

WHAT IS PROVIDED

Conversion of a street address to a 2D Cartesian point (latitude/longitude)
Conversion of a pair of points to a multi-segmented path of driving directions between the two points.
Querying Google's "Local Search" given a point and one or more query terms.

WHAT IS NOT PROVIDED

Documentation of the Google Maps map data XML format
Documentation of the Google Maps web application API
Functionality to create your own Google Maps web page.

AUTHOR

Allen Day <allenday@ucla.edu>

Copyright (c) 2004-2005 Allen Day. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS / TODO

Report documentation and software bugs to the author, or better yet, send a patch. Known bugs/issues:

Polyline decoding needs to be cleaned up.
Lack of documentation.

SEE ALSO

http://maps.google.com
http://www.google.com/apis/maps/
http://libgmail.sourceforge.net/googlemaps.html

CONSTRUCTOR

new()

Usage    : my $geo = Geo::Google->new();
Function : constructs and returns a new Geo::Google object
Returns  : a Geo::Google object
Args     : n/a

OBJECT METHODS

error()

Usage    : my $error = $geo->error();
Function : Fetch error messages produced by the Google Maps XML server.
           Errors can be produced for a number of reasons, e.g. inability
           of the server to resolve a street address to geographical
           coordinates.
Returns  : The most recent error string.  Calling this method clears the
           last error.
Args     : n/a

location()

Usage    : my $loc = $geo->location( address => $address );
Function : creates a new Geo::Google::Location object, given a
           street address.
Returns  : a Geo::Google::Location object, or undef on error
Args     : an anonymous hash:
           key       required?   value
           -------   ---------   -----
           address   yes         address to search for
           id        no          unique identifier for the
                                 location.  useful if producing
                                 XML.
           icon      no          image to be used to represent
                                 point in Google Maps web
                                 application
           infoStyle no          unknown.  css-related, perhaps?

near()

Usage    : my @near = $geo->near( $loc, $phrase );
Function : searches Google Local for records matching the
           phrase provided, with the constraint that they are
           physically nearby the Geo::Google::Location object
           provided.  search phrase is passed verbatim to Google.
Returns  : a list of Geo::Google::Location objects
Args     : 1. A Geo::Google::Location object
           2. A search phrase.

path()

Usage    : my $path = $geo->path( $from, $to );
Function : get driving directions between two points
Returns  : a Geo::Google::Path object
Args     : 1. a Geo::Google::Location object (from)
           2. a Geo::Google::Location object (to)

INTERNAL FUNCTIONS AND METHODS

_decode()

Usage    : my @points = _decode($encoded_points);
Function : decode a polyline into its composite lat/lon pairs
Returns  : an array
Args     : a string

_encode()

Usage    : my $encoded_points = _encode(@points);
Function : encode lat/lon pairs into a polyline string
Returns  : a string
Args     : an array

_html_unescape()

Usage    : my $clean = _html_unescape($dirty);
Function : does HTML unescape of & > < " special characters
Returns  : an unescaped HTML string
Args     : an HTML string.

_xml2location()

Usage    : my $loc = _xml2location($xml);
Function : converts a Google Maps XML document to a Geo::Google::Location object
Returns  : a Geo::Google::Location object
Args     : a Google Maps XML document.