NAME

Geo::Google - Perform geographical queries using Google Maps

SYNOPSIS

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

  #Allen's office
  my $gonda_addr = '695 Charles E Young Dr S, Los Angeles, Los Angeles, California 90024, United States';
  #Stan's Donuts
  my $stans_addr = '10948 Weyburn Ave, Westwood, CA 90024';
  #Roscoe's House of Chicken and Waffles
  my $roscoes_addr = "5006 W Pico Blvd, Los Angeles, CA 90019";

  #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 );
  my ( $roscoes ) = $geo->location( address => $roscoes_addr );
  print $gonda->latitude, " / ", $gonda->longitude, "\n";
  print $stans->latitude, " / ", $stans->longitude, "\n";
  print $roscoes->latitude, " / ", $roscoes->longitude, "\n";

  #Create a Geo::Google::Path object from $gonda to $roscoes
  #by way of $stans.
  my ( $donut_path ) = $geo->path($gonda, $stans, $roscoes);

  #A path contains a series of Geo::Google::Segment objects with
  #text labels representing turn-by-turn driving directions between
  #two or more locations.
  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;

  # Export a location as XML for part of a Google Earth KML file
  my $strStansDonutsXML = $stans->toXML();
 
  # Export a location as JSON data to use with Google Maps
  my $strRoscoesJSON = $roscoes->toJSON();

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>, Michael Trowbridge <michael.a.trowbridge@gmail.com>

COPYRIGHT AND LICENSE

BUGS / TODO

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

Lack of documentation.
JSON exporting is not exactly identical to the original Google JSON response. Some of the Google Maps-specific data is discarded during parsing, and the perl JSON module does not allow for bare keys while exporting to a JSON string. It should still be functionally interchangeable with a Google JSON reponse.

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, $OptionalWaypoints, $to );
 Function : get driving directions between two points
 Returns  : a Geo::Google::Path object
 Args     : 1. a Geo::Google::Location object (from)
            2. optional Geo::Google::Location waypoints
            3. a Geo::Google::Location object (final destination)

INTERNAL FUNCTIONS AND METHODS

_decode_word()

 Usage    : my $float = _decode_word($encoded_quintet_word);
 Function : turn a quintet word into a float for the _decode() function
 Returns  : a float
 Args     : one data word made of ASCII characters carrying
            a five-bit number per character from an encoded 
            Google polyline string

_decode()

 Usage    : my @points = _decode($encoded_points);
 Function : decode a polyline into its composite lat/lon pairs
 Returns  : an array of floats (lat1, long1, lat2, long2 ... )
 Args     : an encoded google polyline string

_encode()

 Usage    : my $encoded_points = _encode(@points);
 Function : encode lat/lon pairs into a polyline string
 Returns  : a string
 Args     : an array of coordinates [38.47823, -118.48571, 38.47845, -118.48582, ...]

_encode_word()

 Usage    : my $encoded_quintet_word = _encode_word($signed_floating_point_coordinate);
 Function : turn a signed float (either a full coordinate 
            or a delta) for the _encode() function
 Returns  : a string containing one encoded coordinate that
            will be added to a polyline string
 Args     : one data word made of ASCII characters carrying
            a five-bit number per character from an encoded 
            Google polyline string

_html_unescape()

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

_obj2location()

 Usage    : my $loc = _obj2location($obj);
 Function : converts a perl object generated from a Google Maps 
                JSON response to a Geo::Google::Location object
 Returns  : a Geo::Google::Location object
 Args     : a member of the $obj->{overlays}->{markers}->[] 
                anonymous array that you get when you read google's 
                JSON response and parse it using JSON::jsonToObj()

_JSONrenderSkeleton()

 Usage    : my $perlvariable = _JSONrenderSkeleton();
 Function : creates the skeleton of a perl data structure used by 
                the Geo::Google::Location and Geo::Google::Path for 
                rendering to Google Maps JSON format
 Returns  : a mildly complex multi-level anonymous hash/array 
                perl data structure that corresponds to the Google 
                Maps JSON data structure
 Args     : none

CPAN RT