Static Maps API Developer's Guide

Welcome to the developer documentation for the Google Static Maps API! The Google Static Maps API lets you embed a Google Maps image on your webpage without requiring JavaScript or any dynamic page loading. The Google Static Map service creates your map based on URL parameters sent through a standard HTTP request and returns the map as an image you can display on your web page.

The Google Static Maps API requires a Maps API key. If you haven't already done so, sign up for a free API key.

A Quick Example

The following example contains the URL of a static map image, which is displayed below:

# Note that this URL wraps at the '\' character.
# You can copy the URL from the image below, however.
# For clarity, we don't write the actual API key in use.
#
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=14&size=512x512&maptype=mobile\
&markers=40.702147,-74.015794,blues%7C40.711614,-74.012318,greeng%7C40.718217,-73.998284,redc\
&key=MAPS_API_KEY&sensor=false

Notice that you don't need to do anything "special" to get this image to show up on the page. No JavaScript is required. All we needed to do was create a URL, and place it within an <img> tag. You can place a Google static map anywhere on your webpage where you can place an image.

Contents

Audience Usage Limits Overview URL Parameters Parameter Usage Specifying Locations Latitudes and Longitudes Geocoding Zoom Levels Image Sizes Viewport Image Formats Map Types Adding Markers Marker Descriptors Implicit Positioning of the Map Using Markers Static Map Paths Path Attributes Specifying Path Points More Information

Audience

This document is intended for website and mobile developers who want to include Google Static Maps API images within a webpage. It provides an introduction to using the API and reference material on the available parameters.

Usage Limits

Use of the Static Maps API requires registration of a free Maps API key. The Maps API key allows you to use the Static Maps API, as well as the standard Maps API.

Use of the Google Static Maps API is also subject to a query limit of 1000 unique (different) image requests per viewer per day. Since this restriction is a quota per viewer and not per key, most developers should not need to worry about exceeding their quota. Additionally, note that requests of identical images, in general, do not count towards this limit beyond the original request.

If a user exceeds the limit as proscribed above, the following image will be displayed indicating that the quota has been exceeded:

This limit is enforced to prevent abuse and/or repurposing of the Static Maps API, and this limit may be changed in the future without notice. If you exceed the 24-hour limit or otherwise abuse the service, the Static Maps API may stop working for you temporarily. If you continue to exceed this limit, your access to the Static Maps API may be blocked.

Overview

The Google Static Maps API returns an image (either GIF, PNG or JPEG) in response to a HTTP request via a URL. For each request, you can specify the location of the map, the size of the image, the zoom level, the type of map, and the placement of optional markers at locations on the map. You can additionally label your markers using alphanumeric characters, so that you can refer to them in a "key."

You embed a Static Maps API image within a webpage inside an <img> tag's src attribute. When the webpage is displayed, the browser requests the image from the the Static Maps API and it renders within the image location.

This document describes the required format of Static Maps API URLs and the available parameters. It also points out some tips and tricks in specifying your URLs.

URL Parameters

A Google Static Maps API URL must be of the following form:

http://maps.google.com/staticmap?parameters

Certain parameters are required while some are optional. As is standard in HTTP requests, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

The Static Maps API defines map images using the following URL parameters:

• center (required if markers not present) defines the center of the map, equidistant from all edges of the map. This parameter takes a comma-separated {latitude,longitude} pair (e.g. "40.714728,-73.998672") identifying a unique location on the face of the earth. For more information, see latitudes and longitudes below.
• zoom (required if markers not present) defines the zoom level of the map, which determines the magnification level of the map. This parameter takes a numerical value corresponding to the zoom level of the region desired. For more information, see zoom levels below.
• size (required) defines the rectangular dimensions of the map image. This parameter takes a string of the form valuexvalue where horizontal pixels are denoted first while vertical pixels are denoted second. For example, 500x400 defines a map 500 pixels wide by 400 pixels high. If you create a static map that is 100 pixels wide or smaller, the "Powered by Google" logo is automatically reduced in size.
• format (optional) defines the format of the resulting image. By default, the Static Maps API creates GIF images. There are several possible formats including GIF, JPEG and PNG types. Which format you use depends on how you intend to present the image. JPEG typically provides greater compression, while GIF and PNG provide greater detail. For more information, see Image Formats.
• maptype (optional) defines the type of map to construct. There are several possible maptype values, including satellite, terrain, hybrid, and mobile. For more information, see Static Maps API Maptypes below.
• markers (optional) define one or more markers to attach to the image at specified locations. This parameter takes a string of marker definitions separated by the pipe character (|). Note that if you supply markers for a map, you do not need to specify the (normally required) center and zoom parameters. For more information, see Static Map Markers below.
• path (optional) defines a single path of two or more connected points to overlay on the image at specified locations. This parameter takes a string of point definitions separated by the pipe character (|). Note that if you supply a path for a map, you do not need to specify the (normally required) center and zoom parameters. For more information, see Static Map Paths below.
• span (optional) defines a minimum viewport for the map image expressed as a latitude and longitude pair. The static map service takes this value and produces a map of the proper zoom level to include the entire provided span value from the map's center point. Note that the resulting map may include larger bounds for either latitude or longitude depending on the rectangular dimensions of the map. If zoom is specified, span is ignored.
• frame (optional) specifies that the resulting image should be framed with a colored blue border. The frame consists of a 5 pixel, 55% opacity blue border.
• hl (optional) defines the language to use for display of labels on map tiles. Note that this paramater is only supported for some country tiles; if the specific language requested is not supported for the tile set, then the default language for that tilset will be used.
• key (required) identifies the Maps API key for the domain on which this URL request takes place. If you don't have a Maps API key, you can sign up for one free.
• sensor (required) specifies whether the application requesting the static map is using a sensor to determine the user's location. This parameter is now required for all static map requests. For more information, see Sensors below.

Parameter Usage

The Static Maps API is relatively easy to use, as it consists solely of a parameterized URL. This section explains how to use these parameters to construct your URLs.

Specifying Locations

The Static Maps API must be able to precisely identify locations on the map, both to focus the map at the correct location (using the center parameter) and/or to place any optional placemarks (using the markers parameter) at locations on the map. The Static Maps API uses latitude and longitude values to specify these locations. These values together identify a geocoded location.

If your device uses a "sensor" (such as a GPS device) to determine the location of a device or user, you must also pass sensor=true within your Static Maps API request URL. If your application does not use a sensor, pass sensor=false.

Latitudes and Longitudes

Latitudes and longitudes are defined using numerals within a comma-separated text string that have a precision to 6 decimal places. For example, "40.714728,-73.998672" is a valid geocode value. Precision beyond the 6 decimal places is ignored.

Longitude values are based on their distance from Greenwich, England, home of the prime meridian. Since Greenwich is situated at 51.477222 latitude, we can enter a center value of 51.477222,0 to center the map on Greenwich:

Latitude and longitude values must correspond to a valid location on the face of the earth. Latitudes can take any value between -90 and 90 while longitude values can take any value between -180 and 180. If you specify an invalid latitude or longitude value, your request will be rejected as a bad request.

Geocoding

Most people don't speak in latitudes and longitudes; they denote locations using addresses. The process of turning an address into a geographic point is known as geocoding and is discussed in detail in the Google Maps API Services section. Note that to use the Geocoding service directly, you will need to use a Maps API key.

You can obtain geocoded latitude and longitude values using a variety of services other than this Geocoding service, including Google Maps itself. For example, you can enter an address into Google Maps and determine its geocoded location by clicking on the Link to this page link in the upper right of the map. A popup dialog box will appear where you can copy the URL. If you copy that URL into a browser, you will be able to find the geocoded values contained within the ll parameter.

Zoom Levels

Maps on Google Maps have an integer "zoom level" which defines the resolution of the current view. Zoom levels between 0 (the lowest zoom level, in which the entire world can be seen on one map) to 19 (the highest zoom level, down to individual buildings) are possible within the normal maps view.

Google Maps sets zoom level 0 to encompass the entire earth. Each succeeding zoom level doubles the precision in both horizontal and vertical dimensions. More information on how this is done is available in the Google Maps API documentation.

Note: not all zoom levels appear at all locations on the earth. Zoom levels vary depending on location, as data in some parts of the globe is more granular than in other locations.

If you send a request for a zoom level in which no map tiles exist, the Static Maps API will return a black image instead.

The example below requests two maps of Manhattan at the same center value but at zoom levels 12 and 14, respectively:

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=MAPS_API_KEY&sensor=true_or_false

  

Image Sizes

Images may be retrieved in sizes up to 640 by 640 pixels. The size parameter takes a string with two values separated by the x character. 640x640 is the largest image size allowed. Note that the center parameter, combined with the size parameter implicitly defines the coverage area of the map image.

The example below requests a "slice" of the earth at the equator at zoom level 1:

http://maps.google.com/staticmap?center=0,0&zoom=1&size=400x50&key=MAPS_API_KEY&sensor=true_or_false

The example below requests a small map, of size 100 x 100 pixels centered on the same region. Note the smaller Google logo:

Viewports

Images may specify a viewport (defined by latitude and longitude values expressed as degrees) to display around a provided center point by passing a span parameter. Defining a minimum viewport in this manner obviates the need to specify an exact zoom level. The static map service uses the span parameter in conjunction with the size parameter to construct a map of the proper zoom level which includes at least the given viewport constraints.

The example below requests a square map centered on 0 degrees longitude and 0 degrees latitude of width and height of 20 degrees:

http://maps.google.com/staticmap?center=0,0&span=20,20&size=512x512&key=MAPS_API_KEY&sensor=true_or_false

The example below requests a map centered on Manhattan that shows 1 degree of arc in both directions. Note that since this map is horizontally shaped that it extends 4 degrees horizontally so that it can extend the minimum 1 degree vertically.

http://maps.google.com/staticmap?center=40.714728,-73.998672&span=1,1&size=512x128&key=MAPS_API_KEY&sensor=true_or_false

Image Formats

Images may be returned in several common web graphics formats: GIF, JPEG and PNG. The format parameter takes one of the following values:

• gif (default) specifies the GIF format.
• jpg specifies the JPEG compression format.
• jpg-baseline specifies a non-progressive JPEG compression format.
• png8 specifies the 8-bit PNG format.
• png32 specifies the 32-bit PNG format.

jpg and jpg-baseline typically provide the smallest image size, though it does so through "lossy" compression which may degrade the image. gif, png8 and png32 provide lossless compression.

Most JPEG images are progressive, meaning that they load a courser image earlier and refine the image resolution as more data arrives. This allows images to be loaded quickly in webpages and is the most widespread use of JPEG currently. However, some uses of JPEG (especially printing) require non-progressive (baseline) images. In such cases, you may want to use the jpg-baseline format, which is non-progressive.

Map Types

The Google Static Maps API creates maps in several formats, listed below:

• roadmap (default) specifies a standard roadmap image, as is normally shown on the Google Maps website. If no maptype value is specified, the Static Maps API serves roadmap tiles by default.
• mobile specifies a mobile roadmap map image, which contains larger features and text fonts to enable easier visual display at the high resolutions and small screen sizes of mobile devices.
• satellite specifies a satellite image.
• terrain specifies a physical relief map image, showing terrain and vegetation.
• hybrid specifies a hybrid of the satellite and roadmap image, showing a transparent layer of major streets and place names on the satellite image.

You can see the difference between roadmap and mobile types in the code example below. Note that these maps also have frame=true.

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=mobile&key=MAPS_API_KEY&sensor=true_or_false

  

The following examples show satellite and terrain map types:

http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=MAPS_API_KEY&sensor=true_or_false
http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=MAPS_API_KEY&sensor=true_or_false

  

Markers

The markers parameter defines a set of one or more markers to attach to the map image. This parameter takes a list of up to 50 markers defined by a set of value assignments:

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|... etc.

Note that marker descriptors are separated from each other using the pipe character (|). (Note: the pipe character is also %7C in ASCII if you are encoding your URLs.)

Marker Descriptors

Each marker descriptor contains a string defining the location to place the marker and the visual attributes to use when displaying the marker. These strings contain the following variable values:

• {latitude} (required) specifies a latitudinal value with precision to 6 decimal places.
• {longitude} (required) specifies a longitudinal value with precision to 6 decimal places.
• {size} (optional) specifies the size of marker from the set {tiny, mid, small}. If no size parameter is set, the marker will appear in its default (normal) size.
• {color} (optional) specifies a color from the set {black, brown, green, purple, yellow, blue, gray, orange, red, white}.
• {alphanumeric-character} (optional) specifies a single lowercase alphanumeric character from the set {a-z, 0-9}. Note that default and mid sized markers are the only markers capable of displaying an alphanumeric-character parameter. tiny and small markers are not capable of displaying an alphanumeric-character.

The latitude and longitude values define the marker's location on the map. If the location is off the map, that marker will not appear in the constructed image.

The size, color and alphanumeric-character values define the visual appearance of the marker. If no size value is given, a marker displays in its default (normal) size. Additionally, normal-sized markers are the only markers capable of displaying alphanumeric characters. If no value (or an incorrect value) is given, the marker appears as a default dotted red marker:

An example marker declaration is of the form {latitude},{longitude},{size}{color}{alphanumeric-character}. Note in particular that the size, color and alphanumeric-character values of the string are not separated by commas. A sample marker declaration is shown below.

markers=40.702147,-74.015794,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc&key=MAPS_API_KEY&sensor=true_or_false

This markers parameter defines three markers (separated by the "|" character): one blue marker labeled "S" at 40.702147,-74.015794, one tiny green marker at 40.711614,-74.012318, and one mid-sized red marker labeled "C" at 40.713504,-74.005607 (City Hall). These markers are shown in the example below:

Implicit Positioning of the Map Using Markers

Normally, you need to specify center and zoom URL parameters to define the location and zoom level of your generated map. However, if you supply a markers parameter, you can instead let the Static Maps API determine the correct center and zoom level implicitly, based on evaluation of the position of these markers.

If supplying two or more markers, the Static Maps API will determine a proper center and zoom level, providing generous margins for display of the markers contained within the markers parameter. The example below contains the same markers as shown above, but removes the center and zoom parameters, allowing the map to center more closely on the two markers of interest.

Static Map Paths

The path parameter defines a set of one or more paths to overlay on the map image. This parameter takes a list of paths defined by a set of value assignments:

path=pathColorType:pathColorValue,weight:pathWeight|pathPoint1|pathPoint2|pathPoint3|... etc.

Note that path points are separated from each other using the pipe character (|). (The pipe character is also %7C in ASCII if you are encoding your URLs.)

Path Attributes

Each path parameter may begin with an optional string specifying the attributes of the path, consisting of a pathColorType and a value for that type separated by a colon. If default path attributes are desired instead, the path attribute prefix may be omitted from the path descriptor; the first argument to the path descriptor in this case then describes the first point in the path declaration. (See Path Points below.)

There are two possible pathColorTypes:

• rgb specifies a standard RGB color scheme using a 24-bit hex color value of the form 0xffffff as the pathColorValue. The default opacity for rgb paths is 50%.
• rgba specifies a 32-bit hex color value of the form 0xffffffff as the pathColorValue, where the fourth byte (the last two characters) specifies an alpha channel transparency. Using rgba allows you to vary the transparency of any paths you create.

In addition to the color, weight specifies the thickness of the given path, in pixels.

Some example path definitions appear below:

• Thin blue line, 50% opacity: path=rgb:0x0000ff,weight:1
• Solid red line: path=rgba:0xff0000ff,weight:5
• Solid thick black line: path=rgba:0xffffffff,weight:10

The specification of path attributes in the path descriptor is optional. If default attributes are desired, you may skip defining the path attributes; in that case, the path descriptor's first "argument" will consist instead of the first declared point.

Path Points

In order to draw a path, the path parameter must also be passed two or more points. The Google Static Maps API will then connect the path along those points, in the specified order. Each pathPoint is denoted in the pathDescriptor separated by the | (pipe) character. As with markers, the Google Static Maps API will attempt to determine the default center and zoom of the map based on implicit positioning of the supplied path. Currently, there is a limit of 100 points for any given path.

The following example defines a blue path with default 50% opacity from Union Square NY to Times Square, NY. Note that we did not need to supply a center or zoom parameter.

The specifics of the path parameter appear below:

path=rgb:0x0000ff,weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

The following example defines the same path instead defining a solid red line with 100% opacity:

The specifics of this path parameter appear below:

path=rgba:0xff0000ff,weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

More Information

If the concept of "coding" gives you a headache, a Google Static Map Wizard provides a simple UI-driven way to generate static maps via a simple UI interface.

For more information on using the Static Maps API, or other Google Maps API products, be sure to check out the Maps API Google Group.