[[PageOutline(2-5,Contents,pullout)]]

= Insert a static Google Map as image

== Description

This macro uses the [http://code.google.com/apis/maps/documentation/staticmaps/ Google Map API] to include '''static''' images of maps.
'''Static''' means that is is only a simple image without any user interaction and not the usual feature-rich dynamic map on http://maps.google.com/. No Javascript is needed to display the map image.

For a dynamic Google map use the GoogleMapMacro.

Please note that the maximum size supported by Google is 640x640 pixels. If a bigger width or height is requested, it will be reduced to 640px.

The macro should work both with Trac 0.11 and 0.12. At the moment there is only a 0.11 directory which can also be used for Trac 0.12.
The AdvParseArgsPlugin is used to allow for quoted argument values and must also be installed.

== Bugs/Feature Requests

Existing bugs and feature requests for GoogleStaticMapMacro are 
[report:9?COMPONENT=GoogleStaticMapMacro here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=GoogleStaticMapMacro&owner=martin_s new ticket].

[[TicketQuery(component=GoogleStaticMapMacro&group=type,format=progress)]]

== Download

Download the macro as [download:googlestaticmapmacro/0.11 ZIP-file].

== Source

You can check out GoogleStaticMapMacro from [http://trac-hacks.org/svn/googlestaticmapmacro here] using Subversion, or [source:googlestaticmapmacro browse the source] with Trac.

== Installation & Configuration ==#config

Install the plugin [http://trac-hacks.org/#HowdoIinstallthesethings as usual].

To enable the macro put the following into your `trac.ini` file, which is located in the `config` directory of your trac installation.
You need to restart Trac to reread the macro file and the configuration file.

{{{#!ini
[components]
tracgooglestaticmap.* = enabled

[googlestaticmap]
api_key = <Your Google API key (long hex number)>  # not required for API v2
# Optional settings:
#default_size = 300x300
#default_language = de
#default_api_version = <1 or 2> # should be 2 for newer installations. Set to 1 if you want to keep older macros unchanged
}}}

== Upgrade from older Versions ==#Upgrade

The current version of the macro uses the [http://code.google.com/apis/maps/documentation/staticmaps/ Google Static Map API v2], while older versions used [http://code.google.com/apis/maps/documentation/staticmaps/v1/ API v1]
([http://code.google.com/apis/maps/documentation/staticmaps/upgrade.html Upgrade guide]).
The syntax provided by Google has changed between the API versions. To provide the newer features without breaking existing macros, both API versions are supported using the `api` key. 
The older syntax can still be used with newer versions of the macro by setting `api=1` either as a macro argument (`[[GoogleStaticMap(api=1,<old syntax>)]]`) or using the global [#config configuration] option `default_api_version`.

Please note, that since v2 an API key is not required anymore by Google. The API v1 still requires a trac server specific Google Map API key which is [http://code.google.com/apis/maps/signup.html provided by Google for free].

== Usage & Examples

This documentation describes the syntax for the macro v1.x which uses Google's API v2 (see [#Upgrade]). The older syntax is still supported using the `api=1` argument. See [./GoogleStaticMapMacro?version=18 an older version] of this wiki page for the old syntax. Mixing of older and newer syntax is not supported.

=== Parameters

The macro accepts the official [http://code.google.com/apis/maps/documentation/staticmaps/#URL_Parameters Google Static Map argument (see there)] as well as a few internal arguments:
 title:: Sets the HTML title of the map image.
 api:: Sets the API version to be used. By default set to "`2`". To reuse the older macros set `api=1` as mentioned earlier.
 key:: Sets the API key if not set globally in the config file. Deprecated for macro v1.x / Google API v2.

All map locations (center, markers, path) can now be given as address or geographic coordinates (latitude,longitude). Please note that addresses and coordinates __must__ be quoted using double-quotes (`"`) when they include a comma. This is always the case with coordinates. The old macro syntax used colons (`:`) as substitutes, which no longer supported in the new syntax. 

For example:
{{{
[[GoogleStaticMap(center="50.805935,10.349121",zoom=5,size=400x400)]]
[[GoogleStaticMap(center="Germany",zoom=5,size=400x400)]]
}}}

will both result in the following map image:

[[Image(http://maps.google.com/staticmap?center=50.805935%2C10.349121&zoom=5&size=400x400,nolink)]]

=== Markers

You can add markers to the static map using the '`markers`' argument. The format is '`markers=style settings|first location|next location|...`'
([http://code.google.com/apis/maps/documentation/staticmaps/#Markers details]),
e.g.: `markers="size:mid|label:A|color:blue|50.805935,10.349121"`, creates a blue marker labeled with 'A' at 50.805935,10.349121. Again also addresses can be used to specify locations.
The whole value must be quoted if any commas are included. Multiple `markers` arguments can be given to add markers with different styles.

So,
{{{
[[GoogleStaticMap(center="50.805935,10.349121",zoom=5,size=400x400,markers="color:blue|label:A|50.805935,10.349121",markers="color:green|label:B|50.000000,10.000000|Berlin,Germany",markers="color:yellow|label:C|Regensburg,Germany")]]
}}}
will result in the following map image:

[[Image(http://maps.google.com/maps/api/staticmap?center=50.805935%2C10.349121&zoom=5&markers=color%3Ablue%7Clabel%3AA%7C50.805935%2C10.349121&markers=color%3Agreen%7Clabel%3AB%7C50.000000%2C10.000000%7CBerlin%2CGermany&markers=color%3Ayellow%7Clabel%3AC%7CRegensburg%2CGermany&hl=en&sensor=false&size=400x400,nolink)]]

=== Paths

Paths between locations can be added using the `path` argument which has basically the same syntax as `markers`, except different styles are supported. See [http://code.google.com/apis/maps/documentation/staticmaps/#Paths the Google documentation] for details.

== Processor Syntax

While Tracs normal macro syntax (`[[Macro(key=value,key=value)]]`) is nice for smaller arguments lists, it is getting messy for longer lists. 
This macro now also supports the so called ''wiki processor syntax'' (`{{{ <linebreak> #!Macro <linebreak> content <linebreak> }}}`) to allow for multiple lines of arguments.
In this case a line break will be read as a comma:
{{{
{{{
#!GoogleStaticMap
key1=value1
key2="value 2, with comma"
key3=value3,key4=value4
}}}
}}}
is identical to:
{{{
[[GoogleStaticMap(key1=value1,key2="value 2, with comma",key3=value3,key4=value4)]]
}}}

'''Example:'''
{{{
{{{
#!GoogleStaticMap
center="Germany"
path="Munich|Berlin|Cologne|Munich"
markers="label:M|Munich"
markers="label:B|Berlin"
markers="label:K|Cologne"
markers="label:H|color:orange|Hamburg|Hannover"
markers="size:small|color:green|Mannheim|Straubing|Münster"
size=250x300
}}}
}}}

produces:

[[Image(http://maps.google.com/maps/api/staticmap?center=Germany&markers=label%3AM%7CMunich&markers=label%3AB%7CBerlin&markers=label%3AK%7CCologne&markers=label%3AH%7Ccolor%3Aorange%7CHamburg%7CHannover&markers=size%3Asmall%7Ccolor%3Agreen%7CMannheim%7CStraubing%7CM%C3%BCnster&hl=en&path=Munich%7CBerlin%7CCologne%7CMunich&sensor=false&size=250x300,nolink)]]

== Recent Changes

[[ChangeLog(googlestaticmapmacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:martin_s] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''