You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Static Maps API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Static Maps API
  3. Create appropriate keys
Continue

Google Static Maps Developer Guide

The Google Static Maps API lets you embed a Google Maps image on your web page without requiring JavaScript or any dynamic page loading. The Google Static Maps API 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.

Note: The Google Static Maps API Usage Limits have changed. Creating an API key and including it in your request allows you to track usage in the Google API Console, and to purchase additional quota if required.

This document details the Google Static Maps API v2. To update your v1 URLs, please consult the Upgrade Guide.

A Quick Example

The following example contains the URL of a Google Static Maps API image of downtown New York City, which is displayed below:

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

Points of Interest in Lower Manhattan

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 Google Static Maps API anywhere on your webpage where you can place an image.

Audience

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

Overview

The Google Static Maps API returns an image (either GIF, PNG or JPEG) in response to an 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.

A Google Static Maps API image is embedded within an <img> tag's src attribute, or its equivalent in other programming languages. If a Google Static Maps API image is used outside of a web-based application (such as a browser) then a link must be included pointing to the displayed location in a web browser or native Google Maps application. (Google Maps APIs Premium Plan users are waived of this requirement.) Please refer to the Google Maps APIs Terms of Service, section 10.1.1(h), for the full and current language regarding this requirement.

This document describes the required format of Google 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:

https://maps.googleapis.com/maps/api/staticmap?parameters

If your website is accessed over HTTPS, you must load Google Static Maps API images over HTTPS as well in order to avoid browser security alerts. HTTPS is also recommended if your requests include sensitive user information, such as a user's location:

https://maps.googleapis.com/maps/api/staticmap?parameters

Whether using HTTP or HTTPS, certain URL 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.

Important: The discussion of URL parameters below use examples that for clarity are given in their pre-escaping form. Before sending any request to the API, its parameters should be properly URL encoded. For example, many parameters use a pipe character (|) as a separator, which should be encoded as %7C in the final URL, as in the quick example at the top of this document. For more information, see Building a Valid URL.

The Google 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 {horizontal_value}x{vertical_value}. For example, 500x400 defines a map 500 pixels wide by 400 pixels high. Maps smaller than 180 pixels in width will display a reduced-size Google logo. This parameter is affected by the scale parameter, described below; the final output size is the product of the size and scale values.
  • scale (optional) affects the number of pixels that are returned. scale=2 returns twice as many pixels as scale=1 while retaining the same coverage area and level of detail (i.e. the contents of the map don't change). This is useful when developing for high-resolution displays, or when generating a map for printing. The default value is 1. Accepted values are 2 and 4 (4 is only available to Google Maps APIs Premium Plan customers.) See Scale Values for more information.
  • format (optional) defines the format of the resulting image. By default, the Google 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 Google Static Maps API Maptypes 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.
  • region (optional) defines the appropriate borders to display, based on geo-political sensitivities. Accepts a region code specified as a two-character ccTLD ('top-level domain') value.

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 Google Static Maps API 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 Google Static Maps API 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 Google Static Maps API.
  • style (optional) defines a custom style to alter the presentation of a specific feature (roads, parks, and other features) of the map. This parameter takes feature and element arguments identifying the features to style, and a set of style operations to apply to the selected features. You can supply multiple styles by adding additional style parameters. For more information, see the guide to styled maps.

Key and Signature Parameters

  • key (required) allows you to monitor your application's API usage in the Google API Console, enables access to generous free daily quota, and ensures that Google can contact you about your application if necessary. For more information, see Get a Key and Signature.
  • signature (recommended) is a digital signature used to verify that any site generating requests using your API key is authorized to do so. Note: If you enable billing, the digital signature is required. If you exceed the free daily limit of map loads, additional map loads are billable for the remainder of that day. Billable map loads that do not include a digital signature will fail. For more information, see Get a Key and Signature.

Note: Google Maps APIs Premium Plan customers may use either an API key and digital signature, or a valid client ID and digital signature, in your Static Maps requests. Get more information on authentication parameters for Premium Plan customers.

Customers with a previous Google Maps APIs for Work license must include valid client and signature parameters with their requests, instead of a key. For more information, please refer to the Client IDs and signatures section of the Get a Key and Signature page.

URL Size Restriction

Google Static Maps API URLs are restricted to 8192 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. Note, however, that certain characters may be URL-encoded by browsers and/or services before sending them off to the API, resulting in increased character usage. For more information, see Building a Valid URL.

Parameter Usage

The Google 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 Google 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 Google 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

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:

Greenwich, England

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.

Addresses

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 Google Static Maps API 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 Google Static Maps API 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 "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 Google Static Maps API 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 Google Static Maps API for Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

Berkeley, CA

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) and 21+ (down to streets and individual buildings) are possible within the default roadmap view. Building outlines, where available, appear on the map around zoom level 17. This value differs from area to area and can change over time as the data evolves.

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 JavaScript 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 at which no map tiles are available, the Google Static Maps API will return a map showing the maximum zoom level available at that location.

The following list shows the approximate level of detail you can expect to see at each zoom level:

  • 1: World
  • 5: Landmass/continent
  • 10: City
  • 15: Streets
  • 20: Buildings

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

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

Manhattan Faraway  Manhattan Up Close

Image Sizes

The size parameter, in conjunction with center, defines the coverage area of a map. It also defines the output size of the map in pixels, when multiplied with the scale value (which is 1 by default).

The table below shows the maximum allowable values for the size parameter at each scale value.

API scale=1 scale=2 scale=4
Free 640x640 640x640 (returns 1280x1280 pixels) Not available.
Google Maps APIs Premium Plan 2048x2048 1024x1024 (returns 2048x2048 pixels) 512x512 (returns 2048x2048 pixels)

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

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

Equator

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

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

Small Equator Map

Scale Values

The size parameter of the Google Static Maps API defines the size of a map in pixels, so that a map with size=200x200 will be returned as 200 pixels by 200 pixels. On an LCD computer monitor, which typically displays about 100 pixels per inch (ppi), a 200x200 map will be about 2 inches in each dimension.

However, mobile devices increasingly include high resolution screens with pixel densities over 300ppi, which either:

  • Reduce the size of a 200x200 pixel image to only 0.7 of an inch, rendering labels and icons too small to read; or
  • Scale (zoom) the image to improve legibility, resulting in a fuzzy or pixelated image.
Too small Too fuzzy

When developing for mobile devices, use the API's scale parameter to return higher-resolution map images that solve the issues above. The scale value is multiplied with the size to determine the actual output size of the image in pixels, without changing the coverage area of the map. (Default scale value is 1; accepted values are 1, 2, and (for Google Maps APIs Premium Plan customers only) 4).

For example, a scale value of 2 will return the same map coverage area as a request with no scale specified, but with twice as many pixels in each dimension. This includes roads and labels, so that they're legible on high resolution, small size screens, as well as when scaled by the browser.

150x150 150x150&scale=2

Such an image will also perform well on desktop browsers, when inserted into an img or div tag with the height and width set using CSS. The browser will downsize the image to the correct size, without loss of quality.

The table below shows three different image requests.

  • The first is for a 100x100 image, with no scale value specified. It displays properly on the desktop, but is too small to read on a mobile device.
  • The second doubles the map size. On the desktop, the CSS fits it into the specified 100x100 img element, but in downsizing the image, roads and labels become too small. On the mobile device, the image is the right size, but again, roads and labels are illegible.
  • The third request is for a 100x100 map with scale=2. The image is returned with 200px of detail; the desktop scales it down perfectly, so that it's indistinguishable from the original 100x100 request, while the mobile browser benefits from the additional resolution returned by the API.
Device 100x100 200x200 100x100&scale=2
Desktop
(with height="100px" and
width="100px" on the
img tag)
High Resolution
(simulated)

Tip: Mobile platforms, such as Android and iOS, enable apps to support high resolution screens by specifying separate images for each resolution. The scale parameter makes it easy to request a map image for a standard resolution screen, and the matching map for a high resolution screen, simply by setting scale=1 and scale=2 respectively.

For more information about developing for mobile and high resolution displays, the following reading is recommended:

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:

  • 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.

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 Google 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.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

Manhattan Normal Map  Manhattan Terrain Map

Hybrid maps use satellite images and prominent roadmap features to create a combination map. The following examples show satellite and hybrid map types:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

Manhattan Satellite Map  Manhattan Terrain Map

Styled Maps

See the guide to styled maps.

Markers

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 (|).

Because both style information and location information is delimited via the pipe character, style information must appear first in any marker descriptor. Once the Google Static Maps API server encounters a location in the marker descriptor, all other marker parameters are assumed to be locations as well.

Marker Styles

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.

Note: instead of using these markers, you may wish to use your own custom icon. (For more information, see Custom Icons below.)

Marker Locations

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 Google Static Maps API 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:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

Three Brooklyn Zipcodes

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:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

Three Alaska Towns, Different Markers

Custom Icons

Rather than use Google's marker icons, you are free to use your own custom icons instead. Custom icons are specified using the following descriptor in the markers parameter:

  • icon specifies a URL to use as the marker's custom icon. Images may be in PNG, JPEG or GIF formats, though PNG is recommended.

The icon parameter must be specified using a URL (which should be URL-encoded). You can use URLs created by URL-shortening services such as https://goo.gl. Most URL-shortening services have the advantage of automatically encoding URLs. Icons are limited to sizes of 4096 pixels (64x64 for square images), and the Google Static Maps API service allows up to five unique custom icons per request. Note that each of these unique icons may be used multiple times within the Google Static Maps API.

The anchor point of a custom icon is set as the bottom center of the image.

The following example uses Google's Chart API to create custom markers, showing several coffee shops in New York City:

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Manhattan Coffee Shops

Note: The multiple levels of escaping above may be confusing. The Google Chart API uses the pipe character (|) to delimit strings within its URL parameters. Since this character is not legal within a URL (see the note above), when creating a fully valid chart URL it is escaped to %7C. Now the result is embedded as a string in an icon specification, but it contains a % character (from the %7C mentioned above), which cannot be included directly as data in a URL and must be escaped to %25. The result is that the URL contains %257C, which represents two layers of encoding. Similarly, the chart URL contains an & character, which cannot be included directly without being confused as a separator for Google Static Maps API URL parameters, so it too must be encoded.

Here are the steps of creating the Google Static Maps API URL:

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Google Static Maps API Paths

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 Google Static Maps API server encounters a location in the path descriptor, all other path parameters are assumed to be locations as well.

Path Styles

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 Google Static Maps API server will automatically join the first and last points. Note, however, that any stroke on the exterior of the filled area will not be closed unless you specifically provide the same beginning and end location.
  • geodesic: (optional) indicates that the requested path should be interpreted as a geodesic line that follows the curvature of the earth. When false, the path is rendered as a straight line in screen space. Defaults to false.

Some example path definitions appear below:

  • Thin blue line, 50% opacity: path=color:0x0000ff80|weight:1
  • Solid red line: path=color:0xff0000ff|weight:5
  • Solid thick white line: path=color:0xffffffff|weight:10

These 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).

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.

The following example defines a blue path with default 50% opacity from Union Square NY to Times Square, NY.

Path from Union Sq to Times Sq

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:

Path from Union Sq to Times Sq

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:

Path from Union Sq to Times Sq

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.

Encoded Polylines

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:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

Alaska Highway

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:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Brooklyn Encoded Polyline

Viewports

Images may specify a viewport by specifying visible locations using the visible parameter. The visible parameter instructs the Google Static Maps API 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:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

Cambridge Map

Implicit Positioning of the Map

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 Google 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 Google 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:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

Troubleshooting and support

For more information on using the Google Static Maps API, take a look at the support page.

The Google Static Maps API may issue an error or warning when something goes wrong. You should check for warnings in particular if you notice that something is missing from the map. It's also a good idea to check for warnings before launching a new application. Note that the warnings may not be immediately apparent because they appear in the HTTP header. For more information, see the guide to errors and warnings.

The Google Static Maps API previously required that you include the sensor parameter to indicate whether your application used a sensor to determine the user's location. This parameter is no longer required.

Send feedback about...

Google Static Maps API
Need help? Visit our support page.