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
    my $gd = $gmap->generate_gd();

    # or simply
    # my $gd = $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 $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.

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()

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

    if ( $gmap->error() ) {
        print "Error: ".$gmap->error()."\n";
    }
    else {
        open (FH, ">", "mymap.png");
        binmode FH;
        print FH $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?

• Put a water tile in places ourside the available data ranges?

• Develop the generate_html method

AUTHOR

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

BUGS

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.

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.

cpanm WebService::GoogleMaps

perl -MCPAN -e shell
install WebService::GoogleMaps