NAME
Geo::Google::StaticMaps - API for generating URLs for static Google Maps
SYNOPSIS
use Geo::Google::StaticMaps;
my $url = Geo::Google::StaticMaps->url(
key => "your Google Maps API key",
size => [ 400, 300 ],
center => [ 51.855970, 0.958499 ],
zoom => 13,
);DESCRIPTION
This module provides a simple wrapper around generating URLs for Google's Static Maps API. You can find out more about the Static Maps API here: http://code.google.com/apis/maps/documentation/staticmaps/.
At the time of writing this module supports all features supported by the Static Maps API, but arguments are provided as a data structure rather than as the (rather inconsistent) string representations required by the API.
There is a single public static method, called url, which will return a string containing a static map URL given a data structure of arguments. The various properties and their structures are given below.
DATA STRUCTURES
The Static Maps API has several concepts that are represented by data structures. These are described in the following sections, along with how they can be represented in this API.
Maps
The foremost entity is the map itself. It is given as a set of name-value pairs (i.e. a hash) passed into the url method. The properties supported are:
format
The image format that will be used for the resulting map.
Takes a string containing either "png", "gif" or "jpeg". The default is "png".
maptype
The tileset used to generate the map.
This can be either "roadmap", which is the standard Google Maps road map, or "mobile", which is the variation used on Google Maps For Mobile. The default is "roadmap".
size
The size in pixels of the resulting map. This property is required.
Given either as a reference to a list containing a (width, height) pair, or as a reference to a hash containing "width" and "height" members. No other members can be present in the hash.
markers
A list of markers to include on the map.
Given as a list of marker structures (described below), or as a single marker structure.
Note that due to an ambiguity the shorthand whereby a marker is given simply as a pair of coordinates in an array ref is not allowed when using the single marker shorthand. Enclose that array ref in a further array ref to create a single-element list.
paths
A list of paths (polygons) to draw on the map.
Given as a list of path structures (described below) or as a single path structure.
center
The geographic coordinates which will be at the center of the resulting map.
Given as a point structure (described below).
zoom
The zoom level of the resulting map.
This is an integer between 0 and 19, where 0 is zoomed out enough to show the whole world given an appropriate map size. Not all zoom levels are supported for the whole world. See the Static Maps API documentation on zoom levels for more information.
span
The amount of the world that the map will show in the horizontal and vertical axes.
Given as a point structure (described below) containing the number of degrees latitude and longitide that will be shown on the map. Where the aspect ratio doesn't match that of the map itself, additional map data may be shown.
It doesn't make much sense to use zoom and span at the same time.
frame
Whether to draw a frame around the resulting map image.
Given as a boolean. (Usually 1 for true, 0 for false. However, anything that can be evaluated as a boolean is accepted.)
hl
A preferred language to use for the map captions.
Given as a string containing a language code. This will not necessarily be supported for all parts of the world.
key
Your Google Maps API key. This is required.
Given as a string. You must sign up for an API key from the Maps API website before you can use this API.
Points
A point is a (latitude, longitude) pair.
It can be given either as a reference to a list containing the pair (with latitude first) or a reference to a hash containing "lat" and "lon" members, and no other members.
Points are used as part of all of the other geographical structures.
Markers
A marker is an icon placed at a particular point on the map. Google provides for a few different icon sizes and colors, and for some marker sizes allows the markers to be annotated with a letter of the alphabet. See the Static Maps API documentation for more information.
As a shorthand, wherever it is not ambiguous, a marker can be represented simply as a point. In this case, all of the default display settings will be used for the marker.
A marker is normally represented as a reference to a hash containing the following properties:
point
The point at which the marker will be placed on the map. These coordinates can alternatively be given as separate "lat" and "lon" properties on the marker itself, if you wish to avoid creating a separate point structure.
size
A keyword which determines what size marker will be used.
This is a string containing either "normal", "tiny", "mid" or "small", where "normal" is the largest and the default.
color
A keyword which determines what color marker will be used.
This is a string containing one of the following color names: "black", "brown", "green", "purple", "yellow", "blue", "gray", "orange", "red" or "white".
letter
If the marker is either "normal" or "mid", this gives a letter to be displayed within the marker.
This is a string containing a single uppercase letter.
Paths
A path is essentially a polyline drawn on the map. A path is formed from a sequence of joined points along with a color and a weight.
A path is represented as a reference to a hash containing the following properties:
points
The vertices of the path. The visible lines of the path will connect these vertices.
Given as a reference to a list of point structures, as described above.
weight
How wide the drawn lines will be, as an integer number of pixels.
color
The color of the lines making up the path.
Given as a color structure, as described below.
Colors
A color is an RGB triple with an optional alpha channel.
Colors are represented either as a list with three or four elements (the latter being for an alpha channel) or as a reference to a hash containing "red", "green", "blue" and "alpha" properties and no other properties. Each channel value is an integer between 0 and 255 inclusive. For alpha, 0 is completely transparent and 255 is complete opaque. If an alpha channel is not given, it will default to 255.
Colors can also be represented as a simple string containing something that's valid as per the Google Maps API, including the "rgb:" or "rgba:" prefix.
CAVEATS
Although this module will do some basic sanity checks to make sure that you have all of the required arguments, it intentionally avoids itself checking for many of the limits currently imposed by the Static Maps API, since those limits may be altered by Google in future.
You should consult the Google Static Maps API documentation to discover the range of values supported for each property.
POSSIBLE FUTURE ENHANCEMENTS
It was planned for this module to offer also an object-oriented API where the data structure can be built up in stages by successive method calls. However, in the interests of keeping things simple the author decided to support in this version only the static method which takes all arguments in a single data structure.
In future, particularly if the Static Maps API becomes more complicated, it may be desirable to support an extended OO version of this API.
AUTHOR
Copyright 2008 Martin Atkins <mart@degeneration.co.uk>
LICENCE
This module may be distributed under the same terms as Perl itself.