Includes enterprise licensing and support
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.
New! The Google Static Maps service has been upgraded to a new version, supporting addresses, more customizable markers, encoded polylines and more. Please read through this documentation thoroughly to note the differences.
The previously existing Google Static Maps service at
http://maps.google.com/staticmap has been deprecated. We
encourage you to move your applications to use this new service instead.
Documentation for this previous version of the API is available in
the Static Maps V1
Developer's Guide.
If you just want to quickly change your existing Static Maps URLs to use the new API, consult this Upgrade Guide.
The following example contains the URL of a static map image of downtown New York City, which is displayed below:
# 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/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=14&size=512x512&maptype=roadmap &markers=color:blue|label:S|40.702147,-74.015794&markers=color:green|label:G|40.711614,-74.012318 &markers=color:red|color:red|label:C|40.718217,-73.998284&sensor=false&key=MAPS_API_KEY
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.
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.
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.
Static Map URLs are restricted to 2048 characters in size. In practice, you will probably not have need for URLs longer than this, unless you produce complicated maps with a high number of markers and paths.
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. Note that static maps
may only be displayed within browser content; use of static maps outside of the browser is not allowed.
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.
A Google Static Maps API URL must be of the following form:
http://maps.google.com/maps/api/staticmap?parameters
Certain parameters are required while some are optional. As is standard in URLs, 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:
Location Parameters:
center (required if markers not present) defines the center of the map, equidistant
from all edges of the map. This parameter takes a location as either a comma-separated {latitude,longitude}
pair (e.g. "40.714728,-73.998672") or a string address (e.g. "city hall, new york, ny") identifying a unique
location on the face of the earth. For more information, see Locations 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.Map Parameters:
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 PNG 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 roadmap, satellite, hybrid, and
terrain. For more information, see Static Maps API Maptypes below.
mobile (optional) specifies whether the map will be displayed on a mobile device. Valid
values are true or false. Maps displayed on mobile devices may use different
tilesets optimized for those devices. For more information, see Mobile Maps below.
language (optional) defines the language to use for display of labels on map tiles.
Note that this parameter 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 tileset will be used.Feature Parameters:
markers (optional) define one or more markers to attach to the image at specified locations.
This parameter takes a single marker definition with parameters separated by the pipe character (|).
Multiple markers may be placed within the same markers parameter as long as they exhibit the same
style; you may add additional markers of differing styles by adding additional markers parameters.
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 (|). You may supply additional paths by adding additional path parameters.
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.visible (optional) specifies one or more locations that
should remain visible on the map, though no markers or other indicators will be displayed. Use
this parameter to ensure that certain features or map locations are shown on the static map.Reporting Parameters:
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 required for all static map requests. For more
information, see Denoting Sensor Usage below.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.
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
numbers (latitude and longitude values) or strings (addresses) to specify these locations. These values
identify a geocoded location.
Several parameters (such as the markers and path parameters) take multiple
locations. In those cases, the locations are separated by the pipe (|) character.
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.
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 the Static Maps service can perform geocoding for you if you provide valid addresses.
In any parameter where you may provide a latitude/longitude, you may instead specify a string indicating an address. Google will geocode the address and provide the Static Map service with a latitude/longitude value to use in placing markers or specifying locations. The string should be URL-escaped, so addresses such as "City Hall, New York, NY" should be converted to vie Imp"City+Hall,New+York,NY", for example.
Note that addresses may reflect either precise locations, such as street addresses, polylines such as named routes, or polygonal areas such as cities, countries, or national parks. For polylinear and polygonal results, the Static Map server will use the center point of the line/area as the address center. If you have doubt about how an address may geocode, you can test out the address using this Geocoding Utility.
The following example generates a static map for Berkeley, CA:
http://maps.google.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&sensor=false\ &key=YOUR_API_KEY
Use of the Google Static Maps API requires that you indicate whether your application is using a "sensor" (such as a GPS locator) to determine the user's location. This is especially important for mobile devices. Applications must pass a required sensor parameter indicating whether or not your application is using a sensor device.
Applications that determine the user's location via a sensor must pass sensor=true within
your Static Maps API request URL. If your application does not use a sensor, pass sensor=false.
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 21+ (down to individual buildings) are possible
within the default roadmap 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 blank 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/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400\&key=MAPS_API_KEY&sensor=false http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=MAPS_API_KEY&sensor=false
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/maps/api/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:
Images may be returned in several common web graphics formats: GIF, JPEG and PNG. The
format parameter takes one of the following values:
png8 or png (default) specifies the 8-bit PNG format.png32 specifies the 32-bit PNG
format.gif specifies the GIF format.jpg specifies the JPEG compression format.jpg-baseline specifies a non-progressive JPEG compression format.jpg and jpg-baseline typically provide the smallest image size, though they do 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 coarser 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.
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.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 terrain types in the code example below.
http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=MAPS_API_KEY&sensor=true_or_false http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=MAPS_API_KEY&sensor=true_or_false
Hybrid maps use satellite images and prominent roadmap features to create a combination map. The following examples show satellite and hybrid map types:
http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=MAPS_API_KEY&sensor=true_or_false http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=MAPS_API_KEY&sensor=true_or_false
Maps on mobile devices present several challenges. Because the screen real estate is usually small, maps that are usable on a desktop may be too detailed to use on a mobile device. Additionally, many of the more robust mobile devices have high resolutions for their screen size, so text often appears in smaller font sizes, for example.
Google provides specialized tile sets for mobile devices for use cases such as this. To request these
specialized mobile tiles, set mobile to true.
The following map displays a normal (desktop) map of downtown Chicago and a mobile version of the same location:
http://maps.google.com/maps/api/staticmap?center=Chicago,IL&zoom=13&size=400x400&maptype=roadmap&key=MAPS_API_KEY&sensor=true_or_false http://maps.google.com/maps/api/staticmap?center=Chicago,IL&zoom=13&size=400x400&maptype=roadmap&mobile=true&key=MAPS_API_KEY&sensor=true_or_false
Note that some mobile devices, such as the iPhone and Android devices, have robust browsers which can display default tilesets
without loss of clarity or precision. In those cases, you may not wish to use mobile=true.
The markers parameter defines a set of one or more markers at a set of locations.
Each marker defined within a single markers declaration must exhibit the same visual
style; if you wish to display markers with different styles, you will need to supply multiple
markers parameters with separate style information.
The markers parameter takes set of value assignments (marker descriptors)
of the following format:
markers=markerStyles|markerLocation1|markerLocation2|... etc.
The set of markerStyles is declared at the beginning of the markers declaration and
consists of zero or more style descriptors separated by the pipe character (|), followed
by a set of one or more locations also separated by the pipe character (|). (The pipe character
is also %7C in ASCII if you are encoding your URLs.)
Because both style information and location information is delimited via the pipe character, style information must appear first in any marker descriptor. Once the Static Map server encounters a location in the marker descriptor, all other marker parameters are assumed to be locations as well.
The set of marker style descriptors is a series of value assignments separated by the pipe
(|) character. This style descriptor defines the visual attributes to use when
displaying the markers within this marker descriptor. These style descriptors contain the
following key/value assignments:
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 24-bit color (example:
color=0xFFFFCC) or a predefined color from the set {black, brown, green,
purple, yellow, blue, gray, orange, red, white}.
Note that transparencies (specified using 32-bit hex color values) are not supported in markers, though they are supported for paths.
label: (optional) specifies a single uppercase alphanumeric character
from the set {A-Z, 0-9}. (The requirement for uppercase characters is new to this version of the
API.) 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.Each marker descriptor must contain a set of one or more locations defining where to place the marker
on the map. These locations may be either specified as latitude/longitude
values or as addresses. These locations are separated using the
pipe character (|).
The location parameters define the marker's location on the map. If the location is off the map,
that marker will not appear in the constructed image provided that center and
zoom parameters are supplied. However, if these parameters are not supplied, the
static map server will automatically construct an image which contains the supplied markers. (See
Implicit Positioning below.)
A sample marker declaration is shown below. Note that we define one set of styles and three locations:
http://maps.google.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400& markers=color:blue|label:S|11211|11206|11222&key=YOUR_API_KEY&sensor=true_or_false
To define markers with differing styles, we need to supply multiple markers parameters. This set of
markers parameters defines three markers: one blue marker labeled "S" at 62.107733, -145.5419, one tiny green marker at
"Delta Junction, AK", and one mid-sized yellow marker labeled "C" at "Tok, AK". These markers are shown in the example below:
http://maps.google.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\ &markers=color:blue|label:S|62.107733,-145.541936&markers=size:tiny|color:green|Delta+Junction,AK\ &markers=size:mid|color:0xFFFF00|label:C|Tok,AK&sensor=false&key=YOUR_API_KEY" />
The path parameter defines a set of one or more
locations connected by a path to overlay on the map image. The path
parameter takes set of value assignments (path descriptors) of the
following format:
path=pathStyles|pathLocation1|pathLocation2|... etc.
Note that both path points are separated from each other using the pipe character (|).
Because both style information and point information is delimited via the pipe character, style
information must appear first in any path descriptor. Once the Static Map server encounters a
location in the path descriptor, all other path parameters are assumed to be locations as well.
The set of path style descriptors is a series of value assignments separated by the pipe
(|) character. This style descriptor defines the visual attributes to use when
displaying the path. These style descriptors contain the following key/value assignments:
weight: (optional) specifies the thickness of the path in pixels. If no
weight parameter is set, the path will appear in its default thickness (5 pixels).color: (optional) specifies a color either as a 24-bit (example:
color=0xFFFFCC) or 32-bit hexadecimal value (example: color=0xFFFFCCFF),
or from the set {black, brown, green, purple, yellow, blue, gray, orange, red,
white}.
When a 32-bit hex value is specified, the last two characters
specify the 8-bit alpha transparency value. This value varies between 00
(completely transparent) and FF (completely opaque). Note that
transparencies are supported in paths, though they are not supported for markers.
fillcolor: (optional) indicates both that the path marks off a polygonal
area and specifies the fill color to use as an overlay within that area. The set of locations
following need not be a "closed" loop; the static map server will automatically join the first
and last points.Some example path definitions appear below:
path=color:0x0000ff|weight:1path=color:0xff0000ff|weight:5path=color:0xffffffff|weight:10These path styles are 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 (location).
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.
The following example defines a blue path with default 50% opacity from Union Square NY to Times Square, NY.
The specifics of the path parameter appear below:
path=color: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=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
The example below defines a polygonal area within Manhattan, passed a series of intersections as locations:
The specifics of this path parameter appear below:
path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\ 8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\ Park+Ave+%26+34th+St,New+York,NY,NY
Note that we set the path itself to be invisible and the polygonal area to have a 15% opacity.
Instead of a series of locations, you may instead declare a path as an
encoded polyline by using
the enc: prefix within the location declaration of the path. Note
that if you supply an encoded polyline path for a map, you do not need
to specify the (normally required) center and zoom parameters.
The following example outlines the course of the Alaska Highway from Dawson Creek, BC to Delta Junction, AK with an encoded polyline:
http://maps.google.com/maps/api/staticmap?size=400x400&path=weight:3|color:orange|enc:polyline_data
As with standard paths, encoded polyline paths may also demarcate polygonal areas
if a fillcolor argument is passed to the path parameter.
The following example outlines a polygonal area for Brooklyn, NY:
http://maps.google.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033|color:0xFFFFFF00| enc:encoded_data
Images may specify a viewport by specifying visible locations using the visible
parameter. The visible parameter instructs the Static Map service to construct a map
such that the existing locations remain visible. (This parameter may be combined with existing markers
or paths to define a visible region as well.) Defining a viewport in this manner obviates the need to
specify an exact zoom level.
The example below requests a map centered on Boston, MA containing both MIT and Harvard Square in Cambridge, MA:
http://maps.google.com/maps/api/staticmap?center=Boston,MA &visible=77+Massachusetts+Ave,Cambridge,MA|Harvard+Square,Cambridge,MA&size=512x512&key=MAPS_API_KEY&sensor=true_or_false
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 markers, path, or
visible parameters, you can instead let the Static Maps API determine the correct center
and zoom level implicitly, based on evaluation of the position of these elements.
If supplying two or more elements, the Static Maps API will determine a proper center and zoom level, providing generous margins for the elements contained. The example below displays a map containing San Francisco, Oakland, and San Jose, CA:
http://maps.google.com/maps/api/staticmap?size=512x512&maptype=roadmap\ &markers=size:mid|color:red|San+Francisco,CA|Oakland,CA|San+Jose,CA&mobile=true&sensor=false&key=MAPS_API_KEY
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.