Google Static Maps Helper

This gem provides a simple interface to the Google Static Maps V2 API (code.google.com/apis/maps/documentation/staticmaps/)

Installation

If you haven’t already, add gemcutter as a gem source

[sudo] gem sources --add http://gemcutter.org

Then install this gem

[sudo] gem install google_static_maps_helper

The easiest way of generating a Google Static Maps URL

GoogleStaticMapsHelper.url_for do
  marker :lng => 1, :lat => 2
  marker :lng => 3, :lat => 4
end

This will return the url for map with these markers. Please note that if you do use this approach you have to set key, size and sensor setting. You do this by:

GoogleStaticMapsHelper.key = 'your google key'
GoogleStaticMapsHelper.size = '300x600'
GoogleStaticMapsHelper.sensor = false

If you are on Rails you can put it in your environment configuration file and while you are there you can add the following line inside the configuration block:

Rails::Initializer.run do |config|
  config.gem 'google_static_maps_helper', :source => 'http://gemcutter.org'
  ...
end

It is also possible to create paths:

point1 = {:lng => 1, :lat => 2}
point2 = {:lng => 3, :lat => 4}

GoogleStaticMapsHelper.url_for do
  path point1, point2, :color => :red, :weight => 7
end

..and of course you can add paths and markers in the same map.

A bit more “low-level” approach instantiating objects yourself

Marker

A marker object is, not surprisingly, representing a marker in the Google static map. It is pushed into the Map object and is used to generate the URL for the static map. Markers which are of the same “type” (same color, label and size) are grouped together in the generated URL so that we obey the schema of URL which Google has defined as “markers=markerStyles|markerLocation1|markerLocation2|… etc.”

How to build a Marker?

The easiest way to build a marker is by simply sending in an object which responds to lng and lat, or by sending lng and lat in as a hash.

marker = GoogleStaticMapsHelper::Marker.new(location)
marker = GoogleStaticMapsHelper::Marker.new(:lng => 1, :lat => 2)

Google’s static maps supports some options on markers. You can change the color, the label and the size. (code.google.com/apis/maps/documentation/staticmaps/#MarkerStyles). You send in options as a second parameter to the new method if you gave a location object, or include it in the hash where lng and lat is.

marker = GoogleStaticMapsHelper::Marker.new(location, :color => 'blue')
marker = GoogleStaticMapsHelper::Marker.new(:lng => 1, :lat => 2, :color => 'blue')

Map

A Map holds many markers, pluss some additional options like the size of the static image, Google key, what zoom level and center point it should be fixed to etc. If no zoom or center point is give it will calculate the map view based on the markers. You can leave markers out, but then you have to supply zoom and center. More info can be found here: code.google.com/apis/maps/documentation/staticmaps/#URL_Parameters

How to build a map?

When building a map object you have to supply key, sensor and size. Other options are optional.

map = GoogleStaticMapsHelper::Map.new(:key => YOUR_GOOGLE_KEY, :sensor => false, :size => '200x300')

Or, if you have set default options on GoogleStaticMapsHelper, you can skip the required keys when creating a map

GoogleStaticMapsHelper.key = 'your google key'
GoogleStaticMapsHelper.size = '300x600'
GoogleStaticMapsHelper.sensor = false
map = GoogleStaticMapsHelper::Map.new

Generate static map URL

With the map object made, we are ready to add some markers to it:

map << marker
map << another_marker << yet_another_marker << and_one_more_marker

We can now ask the map for it’s URL to where we’ll get the requested map from. This URL can be used as src attribute on an image tag.

map.url

Another thing you might want to do is to override the center point and zoom level. This is done during map construction

map = GoogleStaticMapsHelper::Map.new(:key => YOUR_GOOGLE_KEY,
                                      :sensor => false,
                                      :size => '200x300',
                                      :center => '1,2',
                                      :zoom => 4)

Paths and Polygons

It is also possible to create Paths and Polygons and to use them together with markers. To create a Path you need two Points and a Path object:

path = GoogleStaticMapsHelper::Path.new
start_point = {:lat => 1, :lng => 2} # You can also use any object which responds to lat and lng here
end_point = {:lat => 1, :lng => 2}
path << start_point << end_point
map << path
map.url

To create a polygon you need one more point, and to set the fillcolor of the path to a valid color. Setting the fill color is what will trigger the creation of polygons for the static map API.

path = GoogleStaticMapsHelper::Path.new(:fillcolor => :red, :weight => 3, :color => :blue)
path << point1 << point2 << point3
map << path
map.url

If you feel like it, you can add points at construction time:

GoogleStaticMapsHelper::Path.new(:color => :red, :points => [point1, point2])
# ..or
GoogleStaticMapsHelper::Path.new(point1, point2, :color => :red)

TODO

Ruby 1.9 support