static maps api v2 developer guide - google maps image apis — google developers
TRANSCRIPT
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Static Maps API V2 Developer Guide
Developers
›
Google Maps API
›WebiOSAndroidShowcaseSupportBlog
GDGLive
The Google Static Maps API lets you embed a Google Maps image on your web page without requiring JavaScript or anydynamic page loading. The Google Static Map service creates your map based on URL parameters sent through a standardHTTP request and returns the map as an image you can display on your web page.
New! The Google Static Maps API Usage Limits have changed. Creating an API key and including it in your requestallows you to track usage in the APIs Console, and to purchase additional quota if required.
This document details the Static Maps API v2. To update your v1 URLs, please consult the Upgrade Guide.
A Quick ExampleAudienceAPI KeyUsage LimitsOverviewURL ParametersParameter Usage
Specifying LocationsLatitudes and LongitudesAddresses
Denoting Sensor UsageGoogle Maps Visual RefreshZoom LevelsImage SizesScale ValuesImage FormatsMap TypesStyled Maps
Feature SelectionStyle Operations
Adding MarkersMarker StylesMarker LocationsCustom Icons
Static Map PathsPath StylesSpecifying Path PointsEncoded Polylines
ViewportsImplicit Positioning of the Map Using Markers
More Information
A Quick Example
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
The following example contains the URL of a static map image of downtown New York City, which is displayed below:
Notice that you don't need to do anything "special" to get this image to show up on the page. No JavaScript is required. Allwe needed to do was create a URL, and place it within an <img> tag. You can place a Google static map anywhere on yourwebpage where you can place an image.
AudienceThis document is intended for website and mobile developers who want to include Google Static Maps API images within awebpage or mobile application. It provides an introduction to using the API and reference material on the availableparameters.
API Key
Note: Maps for Business users must include a client and signature parameters with their requests instead of a key.Please refer to the Maps API for Business Web Services chapter for more information.
The Static Maps API uses an API key to identify your application. API keys are managed through the Google APIs console.To activate the Static Maps API and create your key:
1. Visit the APIs console at https://code.google.com/apis/console and log in with your Google Account.2. Click the Services link from the left-hand menu, then activate the Static Maps API service.3. Once the service has been activated, your API key is available from the API Access page, in the Simple API
Access section. Static Maps API applications use the Key for browser apps.
By default, a key can be used on any site. We strongly recommend that you restrict the use of your key to domains that youadminister. You can specify which domains are allowed to use your API key by clicking the Edit allowed referers... link inthe API console.
Including a key in your request allows you to track usage of the API in the APIs Console, and to purchase additional quota ifrequired. To specify a key in your request, include it as the value of a key parameter:
Note that the use of a key is not required, though it is recommended. Examples in this document do not include the keyparameter so that they will work for all users who cut-and-paste the code.
Usage Limits
Google Maps API for Business customers have different quotas than those listed below. A static map request isconsidered a 'page view' for the purposes of Google Maps API for Business quota management and is applied againstthe total number of page views purchased with the Google Maps API for Business license.
The Google Static Maps API has the following usage limits:
25 000 free static map requests per application per 24 hour period.
Additional image requests can be purchased on a per application basis at the rate currently listed in the FAQ. Additionalquota is purchased through the API Console and requires the use of an API key.
If a user exceeds these limits, the server will return an HTTP 403 status and display the below image to indicate that thequota has been exceeded:
URL Size Restriction
http://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%7Ccolor:red%7Clabel:C%7C40.718217,-73.998284&sensor=false
http://maps.googleapis.com/maps/api/staticmap?center=New+York,NY&zoom=13&size=600x300&key={API_KEY}
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Static Map URLs are restricted to 2048 characters in size. In practice, you will probably not have need for URLs longer thanthis, unless you produce complicated maps with a high number of markers and paths. Note, however, that certain charactersmay be URL-encoded by browsers and/or services before sending them off to the Static Map service, resulting in increasedcharacter usage. For more information, see Building a Valid URL.
OverviewThe Google Static Maps API returns an image (either GIF, PNG or JPEG) in response to an HTTP request via a URL. Foreach request, you can specify the location of the map, the size of the image, the zoom level, the type of map, and theplacement of optional markers at locations on the map. You can additionally label your markers using alphanumericcharacters.
A Static Maps API image is embedded within an <img> tag's src attribute, or its equivalent in other programming languages.If a Static Maps API image is used outside of a web-based application (such as a browser) then a link must be includedpointing to the displayed location in a web browser or native Google Maps application. (Google Maps API for Business usersare waived of this requirement.) Please refer to the Google Maps/Google Earth Terms of Service, section 10.1.1(h), for thefull and current language regarding this requirement.
This document describes the required format of Static Maps API URLs and the available parameters. It also points out sometips and tricks in specifying your URLs.
URL ParametersA Google Static Maps API URL must be of the following form:
If your website is accessed over HTTPS, you must load Static Map images over HTTPS as well in order to avoid browsersecurity alerts. HTTPS is also recommended if your requests include sensitive user information, such as a user's location:
Note that the Static Maps API does not support custom icon URLs that use HTTPS; the default icon will be displayed.
Whether using HTTP or HTTPS, certain URL parameters are required while some are optional. As is standard in URLs, allparameters are separated using the ampersand (&) character. The list of parameters and their possible values areenumerated 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 parametersuse a pipe character (|) as a separator, which should be encoded as %7C in the final URL, as in the quick example atthe top of this document.
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. Thisparameter takes a location as either a comma-separated {latitude,longitude} pair (e.g. "40.714728,-73.998672") or astring address (e.g. "city hall, new york, ny") identifying a unique location on the face of the earth. For moreinformation, see Locations below.zoom (required if markers not present) defines the zoom level of the map, which determines the magnification level ofthe map. This parameter takes a numerical value corresponding to the zoom level of the region desired. For moreinformation, 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 thescale parameter, described below; the final output size is the product of the size and scale values.visual_refresh (optional) when true, applies the latest Google Maps look to your image. This will change the basemap tiles, and markers.
http://maps.googleapis.com/maps/api/staticmap?parameters
https://maps.googleapis.com/maps/api/staticmap?parameters
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
scale (optional) affects the number of pixels that are returned. scale=2 returns twice as many pixels as scale=1while retaining the same coverage area and level of detail (i.e. the contents of the map don't change). This is usefulwhen developing for high-resolution displays, or when generating a map for printing. The default value is 1. Acceptedvalues are 2 and 4 (4 is only available to Maps API for Business customers.) See Scale Values for more information.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 youintend 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, includingroadmap, satellite, hybrid, and terrain. For more information, see Static Maps API Maptypes below.language (optional) defines the language to use for display of labels on map tiles. Note that this parameter is onlysupported for some country tiles; if the specific language requested is not supported for the tile set, then the defaultlanguage for that tileset will be used.region (optional) defines the appropriate borders to display, based on geo-political sensitivities. Accepts a regioncode 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 asingle marker definition with parameters separated by the pipe character (|). Multiple markers may be placed withinthe same markers parameter as long as they exhibit the same style; you may add additional markers of differingstyles by adding additional markers parameters. Note that if you supply markers for a map, you do not need tospecify 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 additionalpaths 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 otherindicators will be displayed. Use this parameter to ensure that certain features or map locations are shown on thestatic map.style (optional) defines a custom style to alter the presentation of a specific feature (road, park, etc.) of the map.This parameter takes feature and element arguments identifying the features to select and a set of style operationsto apply to that selection. You may supply multiple styles by adding additional style parameters. For moreinformation, see Styled Maps below.
Reporting Parameters
sensor (required) specifies whether the application requesting the static map is using a sensor to determine theuser's location. This parameter is required for all static map requests. For more information, see Denoting SensorUsage below.
Maps API for Business users must include valid client and signature parameters with their requests. Please refer to theMaps API for Business Web Services chapter for more information.
Parameter UsageThe Static Maps API is relatively easy to use, as it consists solely of a parameterized URL. This section explains how to usethese 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 themap. 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 areseparated 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 decimalplaces. For example, "40.714728,-73.998672" is a valid geocode value. Precision beyond the 6 decimal places is ignored.
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Longitude values are based on their distance from Greenwich, England, home of the prime meridian. Since Greenwich issituated 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 valuebetween -90 and 90 while longitude values can take any value between -180 and 180. If you specify an invalid latitude orlongitude 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 anaddress into a geographic point is known as geocoding and the Static Maps service can perform geocoding for you if youprovide valid addresses.
In any parameter where you may provide a latitude/longitude, you may instead specify a string indicating an address. Googlewill geocode the address and provide the Static Map service with a latitude/longitude value to use in placing markers orspecifying locations. The string should be URL-escaped, so addresses such as "City Hall, New York, NY" should beconverted 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, orpolygonal areas such as cities, countries, or national parks. For polylinear and polygonal results, the Static Map server willuse the center point of the line/area as the address center. If you have doubt about how an address may geocode, you cantest out the address using this Geocoding Utility.
The following example generates a static map for Berkeley, CA:
Denoting Sensor Usage
Use of the Google Static Maps API requires that you indicate whether your application is using a "sensor" (such as a GPSlocator) to determine the user's location. This is especially important for mobile devices. Applications must pass a requiredsensor 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 requestURL. If your application does not use a sensor, pass sensor=false.
Google Maps Visual Refresh
The Google Maps visual refresh is an aesthetic upgrade that aligns the Google Maps API user experience with recentchanges to the Google Maps website. The base map tiles, as well as the default marker image, have been redesigned.Below you can see the two modes side-by-side — the map on the left shows a default Google Map, while the map on theright has Visual Refresh enabled.
For now, the Static Maps API will display maps with the classic look and feel by default. If you wish to opt-in to the newVisual Refresh mode, set the visual_refresh URL parameter to true.
Note: With Styled Maps you can apply custom coloring to many of your maps features. Because the stylers hue,lightness, saturation, and gamma apply changes relative to the base map tiles you may wish to revisit any customstyles in use on your site when the Visual Refresh mode is enabled.
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 21+ (down to individual buildings) are possiblewithin the default roadmap maps view.
Google Maps sets zoom level 0 to encompass the entire earth. Each succeeding zoom level doubles the precision in bothhorizontal and vertical dimensions. More information on how this is done is available in the Google Maps JavaScript API
http://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&sensor=false
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
documentation.
Note: not all zoom levels appear at all locations on the earth. Zoom levels vary depending on location, as data in some partsof 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:
Image Sizes
The size parameter, in conjunction with center, defines the coverage area of a map. It also defines the output size of themap 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 API forBusiness
2048x2048 1024x1024 (returns 2048x2048pixels)
512x512 (returns 2048x2048pixels)
The example below requests a "slice" of the earth at the equator at zoom level 1:
The example below requests a small map, of size 100 x 100 pixels centered on the same region. Note the smaller Googlelogo:
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 willbe 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; orScale (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 theissues above. The scale value is multiplied with the size to determine the actual output size of the image in pixels, withoutchanging the coverage area of the map. (Default scale value is 1; accepted values are 1, 2, and (for Maps API for Businesscustomers only) 4).
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&sensor=false
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&sensor=false
http://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&sensor=true_or_false
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
For example, a scale value of 2 will return the same map coverage area as a request with no scale specified, but with twiceas many pixels in each dimension. This includes roads and labels, so that they're legible on high resolution, small sizescreens, 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 widthset 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 toread on a mobile device.The second doubles the map size. On the desktop, the CSS fits it into the specified 100x100 img element, but indownsizing the image, roads and labels become too small. On the mobile device, the image is the right size, butagain, 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 scalesit down perfectly, so that it's indistinguishable from the original 100x100 request, while the mobile browser benefitsfrom the additional resolution returned by the API.
Device 100x100 200x200 100x100&scale=2
Desktop(with height="100px" andwidth="100px" on theimg tag)
High Resolution(simulated)
Tip: Mobile platforms, such as Android and iOS, enable apps to support high resolution screens by specifying separateimages 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:
Supporting Multiple Screens in the Android developer documentation.Webkit.org's recommendations for developing High DPI Web Sites.Supporting High-Resolution Screens in the iOS Developer Library.
Image Formats
Images may be returned in several common web graphics formats: GIF, JPEG and PNG. The format parameter takes one ofthe 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 maydegrade 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 moredata 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 wantto use the jpg-baseline format, which is non-progressive.
Map Types
The Google Static Maps API creates maps in several formats, listed below:
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
roadmap (default) specifies a standard roadmap image, as is normally shown on the Google Maps website. If nomaptype 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 placenames on the satellite image.
You can see the difference between roadmap and terrain types in the code example below.
Hybrid maps use satellite images and prominent roadmap features to create a combination map. The following examplesshow satellite and hybrid map types:
Styled Maps
Styled maps allow you to customize the presentation of the standard Google map styles, changing the visual display of suchelements as roads, parks, and built-up areas to reflect a different style than that used in the default map type. Thesecomponents are known as features and a styled map allows you to select these features and apply visual styles to theirdisplay (including hiding them entirely). With these changes, the map can be made to emphasize particular components orcomplement content within the surrounding page.
A customized "styled" map consists of one or more specified styles, each indicated through a style parameter within theStatic Map request URL. Additional styles are specified by passing additional style parameters. A style consists of aselection(s) and a set of rules to apply to that selection. The rules indicate what visual modification to make to the selection.
Each style declaration consists of the following arguments, separated using a pipe ("|") character within the styledeclaration:
feature (optional) indicates what features to select for this style modification. (See Map Features below.) If nofeature argument is passed, all features will be selected.element (optional) indicates what sub-set of the selected features to select. (See Map Elements below.) If no elementargument is passed, all elements of the given feature will be selected.Any following arguments indicate the rule(s) to apply to the above selection. All rules are applied in the order inwhich they appear within the style declaration. (See Style Rules below.) Any number of rules may follow a featureselection, within the normal URL-length constraints of the Static Maps API.
Note: the style declaration must specify the above arguments in the order stated. For example, a feature selection with tworules would appear as show below:
Map Features
A map consists of a set of features, such as roads or parks. The feature types form a category tree, with feature:all as theroot. Some common features are listed below:
feature:all (default) selects all features of the map.feature:road selects all roads on the map.feature:landscape selects all background landscapes on a map, which is often the area between roads, forexample. In cities, landscape usually consists of built-up areas.
The full list of features for selection within a map is documented in the Maps Javascript API V3 reference.
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-
73.998672&zoom=12&size=400x400&maptype=roadmap&sensor=true_or_false
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-
73.998672&zoom=12&size=400x400&maptype=terrain&sensor=true_or_false
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-
73.998672&zoom=12&size=400x400&maptype=satellite&sensor=true_or_false
http://maps.googleapis.com/maps/api/staticmap?center=40.714728,-
73.998672&zoom=12&size=400x400&maptype=hybrid&sensor=true_or_false
style=feature:featureArgument|element:elementArgument|rule1:rule1Argument|rule2:rule2Argument
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Some feature type categories contain sub-categories which are specified using a dotted notation (landscape.natural orroad.local, for example). If the parent feature (road, for example) is specified, then styles applied to this selection will beapplied to all roads, including sub-categories.
Map Feature Elements
Additionally, some features on a map typically consist of different elements. A road, for example, consists of not only thegraphical line (geometry) on the map, but the text denoting its name (labels) attached the map. Elements within features areselected by declaring an element argument. The following element argument values are supported:
element:all (default) selects all elements of that feature.element:geometry selects only geometric elements of that feature.element:labels selects only textual labels associated with that feature.
If no element argument is passed, styles will be applied to all elements of the feature regardless of element type.
The following style declaration selects the labels for all local roads:
Style Rules
Style rules are formatting options which are applied to the features and elements specified within each style declaration.Each style declaration must contain one or more operations separated using the pipe ("|") character. Each operationspecifies its argument value using the colon (":") character, and all operations are applied to the selection in the order inwhich they are specified.
The following operation arguments, and the values that take, are currently supported:
hue (an RGB hex string of format 0xRRGGBB) indicates the basic color to apply to the selection. (* See usage notebelow.)lightness (a floating point value between -100 and 100) indicates the percentage change in brightness of theelement. Negative values increase darkness (where -100 specifies black) while positive values increase brightness(where +100 specifies white).saturation (a floating point value between -100 and 100) indicates the percentage change in intensity of the basiccolor to apply to the element.gamma (a floating point value between 0.01 and 10.0, where 1.0 applies no correction) indicates the amount ofgamma correction to apply to the element. Gammas modify the lightness of hues in a non-linear fashion, whileunaffecting white or black values. Gammas are typically used to modify the contrast of multiple elements. Forexample, you could modify the gamma to increase or decrease the contrast between the edges and interiors ofelements. Low gamma values (< 1) increase contrast, while high values (> 1) decrease contrast.inverse_lightness:true simply inverts the existing lightness.visibility (on, off, or simplified) indicates whether and how the element appears on the map.visibility:simplified indicates that the map should simplify the presentation of those elements as it sees fit. (Asimplified road structure may show fewer roads, for example.)
Style rules must be applied as separate, distinct operations, and are applied in the order they appear within the styledeclaration. Order is important, as some operations are not commutative. Features and/or elements that are modified throughstyle operations (usually) already have existing styles; the operations act on those existing styles, if present.
Note that we use the Hue, Saturation, Lightness (HSL) model to denote color within the styler operations. These operationsto define color are common within graphic design. Hue indicates the basic color, saturation indicates the intensity of thatcolor, and lightness indicates the relative amount of white or black in the constituent color. All three HSL values can bemapped to RGB values (and vice versa). Gamma correction acts to modify saturation over the color space, generally toincrease or decrease contrast. Additionally, the HSL model defines color within a coordinate space where hue indicates theorientation within a color wheel, while saturation and lightness indicate amplitudes along different axes. Hues are measuredwithin an RGB color space, which is similar to most RGB color spaces, except that shades of white and black are absent.
An RGB Color Wheel
Note: while hue takes an RGB hex color value, it only uses this value to determine the basic color (its orientation around thecolor wheel), not its saturation or lightness, which are indicated separately as percentage changes. For example, the hue for
style=feature:road.local|element:labels
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
pure green may be defined as hue:0x00ff00 or hue:0x000100 and both hues will be identical. (Both values point to puregreen in the HSL color model.) RGB hue values which consist of equal parts Red, Green and Blue — such as hue:0x0000000(black) and hue:0xffffff (white) and all the pure shades of grey — do not indicate a hue whatsoever, as none of thosevalues indicate an orientation in the HSL coordinate space. To indicate black, white or grey, you must remove all saturation(add a saturation:-100 operation) and adjust lightness instead.
Additionally, when modifying existing features which already have a color scheme, changing a value such as hue does notchange its existing saturation or lightness.
The following example displays a map of Brooklyn where local roads have been changed to bright green and the residentialareas have been changed to black (note that in this fully worked example the pipe separators have been properly URLencoded; see the note above):
The following example uses operations and simplifications to approximate the look of a US road atlas:
Markers
The markers parameter defines a set of one or more markers at a set of locations. Each marker defined within a singlemarkers declaration must exhibit the same visual style; if you wish to display markers with different styles, you will need tosupply 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 descriptorsseparated 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 firstin any marker descriptor. Once the Static Map server encounters a location in the marker descriptor, all other markerparameters 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 descriptordefines the visual attributes to use when displaying the markers within this marker descriptor. These style descriptors containthe following key/value assignments:
size: (optional) specifies the size of marker from the set {tiny, mid, small}. If no size parameter is set, themarker 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 aresupported for paths.
label: (optional) specifies a single uppercase alphanumeric character from the set {A-Z, 0-9}. (The requirement foruppercase characters is new to this version of the API.) Note that default and mid sized markers are the only markerscapable of displaying an alphanumeric-character parameter. tiny and small markers are not capable of displayingan alphanumeric-character.
Note: instead of using these markers, you may wish to use your own custom icon. (For more information, see Custom Iconsbelow.)
http://maps.googleapis.com/maps/api/staticmap?
sensor=false&size=512x512&zoom=15¢er=Brooklyn&style=feature:road.local%7Celement:geometry%7Ccolor:0x00ff00
http://maps.googleapis.com/maps/api/staticmap?
sensor=false&size=512x512&zoom=12&center=Chicago&format=png&style=feature:road.highway%7Celement:geometry%
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Marker Locations
Each marker descriptor must contain a set of one or more locations defining where to place the marker on the map. Theselocations may be either specified as latitude/longitude values or as addresses. These locations are separated using the pipecharacter (|).
The location parameters define the marker's location on the map. If the location is off the map, that marker will not appear inthe constructed image provided that center and zoom parameters are supplied. However, if these parameters are notsupplied, the Static Map server will automatically construct an image which contains the supplied markers. (See ImplicitPositioning below.)
A sample marker declaration is shown below. Note that we define one set of styles and three locations:
To define markers with differing styles, we need to supply multiple markers parameters. This set of markers parametersdefines 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:
Custom Icons
Rather than use Google's marker icons, you are free to use your own custom icons instead. Custom icons are specified usingthe following descriptors to the markers parameter:
icon specifies a URL to use as the marker's custom icon. Images may be in PNG, JPEG or GIF formats, thoughPNG is recommended.shadow (default true) indicates that the Static Maps service should construct an appropriate shadow for the image.This shadow is based on the image's visible region and its opacity/transparency.
The icon parameter must be specified using a URL (which should be URL-encoded). You may use any valid URL of yourchoosing, or a URL-shortening service such as http://goo.gl. Most URL-shortening services have the advantage ofautomatically encoding URLs. Icons are limited to sizes of 4096 pixels (64x64 for square images), and the Static Mapsservice allows up to five unique custom icons per request. Note that each of these unique icons may be used multiple timeswithin the static map.
Custom icons that have a shadow:true descriptor (the default) will have their "anchor point" set as the bottom center of theprovided icon image, from which the shadow is cast. Icons without a shadow (setting a shadow:false descriptor) are insteadassumed to be icons centered on their specified locations, so their anchor points are set as the center of the image.
The following example uses Google's Chart API to create custom markers, showing several coffee shops in New York City:
Note: The multiple levels of escaping above may be confusing. The Google Chart API uses the pipe character (|) to delimitstrings within its URL parameters. Since this character is not legal within a URL (see the note above), when creating a fullyvalid 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 static map URL parameters, so it toomust be encoded.
Here are the steps of creating the static map URL:
http://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&sensor=true_or_false
http://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&sensor=false" />
http://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:http://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&sensor=true_or_false
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
Static Map Paths
The path parameter defines a set of one or more locations connected by a path to overlay on the map image. The pathparameter 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 andpoint information is delimited via the pipe character, style information must appear first in any path descriptor. Once theStatic Map server encounters a location in the path descriptor, all other path parameters are assumed to be locations aswell.
Path Styles
The set of path style descriptors is a series of value assignments separated by the pipe (|) character. This style descriptordefines the visual attributes to use when displaying the path. These style descriptors contain the following key/valueassignments:
weight: (optional) specifies the thickness of the path in pixels. If no weight parameter is set, the path will appear inits 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 valuevaries between 00 (completely transparent) and FF (completely opaque). Note that transparencies are supported inpaths, 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 anoverlay within that area. The set of locations following need not be a "closed" loop; the Static Map server willautomatically join the first and last points. Note, however, that any stroke on the exterior of the filled area will not beclosed 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 thecurvature 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:1Solid red line: path=color:0xff0000ff|weight:5Solid 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, thepath 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 thenconnect 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.
# Intended chld parameter:
chld=cafe|996600
# Embedded in a fully valid chart URL:
http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600
# Intended icon parameter, containing a fully valid URL:
markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600
# Embedded in a valid and unambiguous static map URL:
...&markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
The specifics of the path parameter appear below:
The following example defines the same path instead defining a solid red line with 100% opacity:
The specifics of this path parameter appear below:
The example below defines a polygonal area within Manhattan, passed a series of intersections as locations:
The specifics of this path parameter appear below:
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 thelocation 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 anencoded polyline:
As with standard paths, encoded polyline paths may also demarcate polygonal areas if a fillcolor argument is passed tothe path parameter.
The following example outlines a polygonal area for Brooklyn, NY:
Viewports
Images may specify a viewport by specifying visible locations using the visible parameter. The visible parameter instructsthe Static Map service to construct a map such that the existing locations remain visible. (This parameter may be combinedwith existing markers or paths to define a visible region as well.) Defining a viewport in this manner obviates the need tospecify an exact zoom level.
The example below requests a map centered on Boston, MA containing both MIT and Harvard Square in Cambridge, MA:
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.
path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-
73.986397
path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-
73.986397
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
http://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data
http://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data
http://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&sensor=true_or_false
Static Maps API V2 Developer Guide - Google Maps Image APIs — Google Developers
https://developers.google.com/maps/documentation/staticmaps/#Markers[16/11/2013 11:17:35 p.m.]
However, if you supply markers, path, or visible parameters, you can instead let the Static Maps API determine the correctcenter 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 generousmargins for the elements contained. The example below displays a map containing San Francisco, Oakland, and San Jose,CA:
More InformationFor more information on using the Static Maps API, or other Google Maps API products, be sure to check out the Maps APISupport page.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, andcode samples are licensed under the Apache 2.0 License. For details, see our Site Policies.
Last updated November 15, 2013.
http://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&sensor=false
Google Terms of Service Privacy Policy Jobs Report a bugEnglish