NAME
    WebService::GoogleMaps - Automated interface to Google Maps

SYNOPSIS
        use WebService::GoogleMaps;

        # Set up a new object with a viewport of 640 x 480 pixels
        my $gmap = WebService::GoogleMaps->new( 640, 480 );

        # Specify a location to view
        $gmap->set(
            latitude   => 40.750275,
            longitude  => -73.993034,
            zoom_level => 4,          # valid values are 0..14, lower value is more zoomed
            cache_dir  => "/tmp",     # optional, but recommended!  Helps speed up future requests
            pan_x      => 0,          # move viewport to the east  (+) or west  (-) a number of pixels
            pan_y      => 0,          # move viewport to the south (+) or north (-) a number of pixels
        );

        # create a GD object containing our bitmapped map object
        $gmap->generate_gd();

        # or simply
        # $gmap->generate_gd(40.750275, -73.993034, 4);  # latitude, longitude, zoom_level

        my $error = $gmap->error();
        $error && print "Error: $error\n";
    
        open (FH, ">", "mymap.png");
        binmode FH;
        print FH $gmap->{gd}->png;
        close(FH);

DESCRIPTION
    WebService::GoogleMaps provides an automated interface to Google Maps
    <http://maps.google.com/>, which provides free street maps of locations
    in the USA and Canada. This module allows you to specify an image size,
    latitude, longitude, and zoom level and returns a GD object containing a
    street level map.

METHODS
  new()
    The constructor. You can pass it an image width and height in pixels, or
    nothing to let it default to 640 x 480 pixels. Or instead, pass it a
    list of initial options and values.

        # set up our object to create a 320 x 240 pixel image
        my $gmap = WebService::GoogleMaps->new( 800, 600 );

        # use the default 640 x 480 image size
        my $gmap = WebService::GoogleMaps->new();

        # specify several options and values
        my $gmap = WebService::GoogleMaps->new(
            width      => 800,
            height     => 600,
            latitude   => 40.750275,
            longitude  => -73.993034,
            zoom_level => 3,
            agent      => "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)",  # optional, default is a Firefox agent.
            cache_dir  => "/tmp",     # optional, but helps speed up future requests
            pan_x      => 100,        # move viewport 100 pixels east
            pan_y      => 100,        # move viewport 100 pixels south
        );

  set()
    Use this method to add or change any of the map options after you have
    created the object.

        # Create our object, using the default 640 x 480 image size
        my $gmap = WebService::GoogleMaps->new();
    
        # Set width, height, latitude, longitude, zoom level and cache directory when requesting map data
        $gmap->set(
            width      => 800,
            height     => 600,
            latitude   => 40.750275,
            longitude  => -73.993034,
            zoom_level => 9,
            cache_dir  => "/tmp",
        );

  get()
    Use this method to retrieve the value of any of the current options

        # Find out what the current zoom level is set to
        my $zoom_level = $gmap->get("zoom_level");

  error()
    Use this to retrieve any errors generated by this module.

  center_viewport_on_coordinates()
    Pass it a list of array references, each array must contain at least two
    elements, a latitude and longitude of a place on the map.

    The method will set the center of the viewport to the middle of all the
    passed coordinates, and set a zoom level that will keep all the
    coordinates inside the viewport.

        my @markerlist=(
            [40.725464,  -74.002289, "H!Hiroko's Place"],
            [40.748199,  -74.031575, "=!The Bagel Smashery"],
            [40.8161293, -73.979786, "+!Taiyaki"]
        );
    
        $gmap->center_viewport_on_coordinates(@markerlist);

  generate_gd()
    This performs the retrieval of the image from Google Maps. If the images
    are not found in the cache, (assuming you have specified a directory to
    use for the cache), this may take a little extra time to complete.

    It will return a GD object, which you may then use as you please. It is
    useful to save it to a file.

    If there is a problem creating the image, an error message will be set.
    You may retrieve this error message at $gmap->error()

  insert_latlon_marker_gd()
    After you use generate_gd() to draw the map, you may add a number of
    labeled points to the map.

    Pass this method a list of array references. Each array reference must
    contain at least two elements, the latitude and longitude of a
    coordinate that you want to be marked. Optionally, each array reference
    may have a third element, a label for the point.

    The syntax for this point may be:

    * A single letter A-J for a red pin with that letter
    * A single period character (.) for a red pin with a black dot
    * An plus sign (+) for a green pin with a black triangle
    * An equals sign (=) for a red pin with a black square
    * A string of text, for a labeled red pin with a black dot
    * A string of text in the format "x!Label", where "x" is one of the
    characters that specifies the pin type, "!" is simply an exclamation
    mark, and "Label" is any text you want to appear beside the pin.

        use WebService::GoogleMaps;
    
        my $gmap = WebService::GoogleMaps->new(640, 480);
    
        $gmap->set(
            cache_dir  => "/tmp",     # optional, but helps speed up future requests
        );
    
        my @markerlist=(
            [40.725464,  -74.002289, "H!Hiroko's Place"],
            [40.748199,  -74.031575, "=!The Bagel Smashery"],
            [40.8161293, -73.979786, "+!Taiyaki"]
        );
    
        $gmap->center_viewport_on_coordinates(@markerlist);
    
        $gmap->generate_gd();
    
        $gmap->insert_latlon_marker_gd(@markerlist);
    
        $gmap->{error} && die "Error: $gmap->{error}\n";
    
        open (FH, ">", "goodeats.png");
        binmode FH;
        print FH $gmap->{gd}->png;
        close(FH);

  generate_html()
    Not available in this version. The plan is to have this return HTML code
    that will reference images on the Google Maps server to render the map
    image.

TODO
    * Improve caching method. Maybe use subdirectories to separate cached
    images into geographic areas?
    * Develop the generate_html method
    * Method to draw paths on the map?

AUTHOR
    Karl Lohner, <karllohner+googlemaps@gmail.com>

BUGS
    I am sure there is a few in here...

    Please report any bugs or feature requests to
    <karllohner+googlemaps@gmail.com>.

    Really, I would like to know how you are using this module and what you
    would like to see to make it better.

REFERENCES
    * Google Maps Hacking: http://69.90.152.144/collab/GoogleMapsHacking
    * Google Maps Live for Firefox:
    http://ted.mielczarek.org/code/mozilla/gmaplive/
    * Mapping Google:
    http://jgwebber.blogspot.com/2005/02/mapping-google.html
    * Google Maps Hacking and Bookmarklets:
    http://libgmail.sourceforge.net/googlemaps.html

ACKNOWLEDGEMENTS
    Thanks to Joel Webber and his blog article at
    http://jgwebber.blogspot.com/2005/02/mapping-google.html as well as to
    the many people who added comments there, particularly the anonymous
    comments that detailed the algorithm used to map latitude/longitude to
    specific tiles.

COPYRIGHT AND LICENSE
    Copyright 2005 by Karl Lohner, All Rights Reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.