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

= Insert a static Google Map as an image

== Description

This macro uses the [https://developers.google.com/maps/documentation/staticmaps/intro?csw=1&safe=on Google Map API] to include '''static''' images of maps.
'''Static''' means that it is only an image without any user interaction and not the usual feature-rich dynamic map on https://www.google.com/maps. 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 
[/newticket?component=GoogleStaticMapMacro new ticket].

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

== Download

Download the macro as a [export:googlestaticmapmacro/0.11 zipped file].

The plugin is also available on [pypi:TracGoogleStaticMapMacro PyPI].

== Source

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

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

To enable the macro put the following into your `trac.ini` file, which is located in the `config` directory of your Trac installation:

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

== Configuration ==#config

To configure this plugin, add the following to your `trac.ini` file:

{{{#!ini
[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
}}}

You need to restart Trac to reread the macro file and the configuration file.

== Upgrade from older Versions ==#Upgrade

The current version of the macro uses the Google Static Map API v2, while older versions used API v1. To upgrade see 
[https://developers.google.com/maps/documentation/staticmaps/upgrade?csw=1&safe=on here].
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 no longer required by Google. The API v1 still requires a Trac server specific Google Map API key which is [https://developers.google.com/maps/signup?csw=1&safe=on provided by Google for free].

== Usage and 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 [./@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 [https://developers.google.com/maps/documentation/staticmaps/intro?csw=1&safe=on Google Static Map argument] 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 is no longer supported in the new syntax. 

For example:
{{{
[[GoogleStaticMap(center="51.477222,0", zoom=14, size=400x400)]]
[[GoogleStaticMap(center="Greenwich", zoom=14, size=400x400)]]
}}}

will both result in the following map image:

[[Image(https://maps.googleapis.com/maps/api/staticmap?center=51.477222,0&zoom=14&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|...`
([https://developers.google.com/maps/documentation/staticmaps/intro?csw=1&safe=on]), for example: `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 the following example:
{{{
[[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 [https://developers.google.com/maps/documentation/staticmaps/intro?csw=1&safe=on 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:'''