Google 静态地图开发者指南

Google Static Maps API 让您无需 JavaScript 或任何动态页面加载便可将 Google 地图图像嵌入网页。Google Static Maps API 根据通过标准 HTTP 请求发送的 URL 参数创建您的地图，并返回可供您显示在网页上的图像形式地图。

注：Google Static Maps API 使用限制发生了变化。您可以通过创建 API 密钥并将其加入请求在 Google Developers Console 中追踪使用情况，以及在必要时购买额外配额。

本文对 Google Static Maps API v2 做了详述。如需更新您的 v1 URL，请查阅升级指南。

快速示例

下例包含下图所示纽约市中心 Google Static Maps API 图像的 URL：

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

请注意，您无需执行任何“特别”操作，便可将这幅图像显示在页面上。无需 JavaScript。我们只需创建一个 URL，然后将其置于一个 <img> 标记内。您可以将 Google Google Static Maps API 置于网页上任何可以放置图像的位置。

受众

本文档的适用对象是想要在网页或移动应用内加入 Google Static Maps API 图像的网站和移动开发者。它介绍了 API 使用方法，并提供了有关可用参数的参考资料。

概览

Google Static Maps API 返回图像（GIF、PNG 或 JPEG 格式）来响应通过 URL 发出的 HTTP 请求。您可以为每个请求指定地图的位置、图像尺寸、缩放比例、地图类型以及地图各位置处可选标记的放置。此外，您还可以使用字母数字字符来标示您的标记。

Google Static Maps API 图像内嵌于 <img> 标记的 src 属性内，或其他编程语言的等效属性内。如果在基于 Web 的应用（如浏览器）以外使用 Google Static Maps API 图像，则必须加入一个链接，该链接须指向 Web 浏览器或原生 Google 地图应用中显示的位置。（Google Maps API for Work 用户不受此要求约束。）请参阅 Google 地图/Google 地球服务条款第 10.1.1(h) 节，了解有关这项要求的最新完整条文。

本文档介绍要求的 Google Static Maps API URL 格式和可用参数。此外，它还指出了在指定 URL 方面的一些技巧和诀窍。

URL 参数

Google Static Maps API URL 必须采用以下形式：

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

如果您的网站通过 HTTPS 进行访问，必须同样通过 HTTPS 加载 Google Static Maps API 图像，以避免浏览器安全警报。如果请求中包含用户位置等敏感的用户信息，也建议使用 HTTPS：

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

注：Google Static Maps API 不支持使用 HTTPS 的自定义图标 URL；将显示默认图标。

无论使用 HTTP 还是 HTTPS，有些 URL 参数是必填的，而有些则是可选的。依照 URL 的标准，所有参数都使用“与”字符 (&) 分隔。下面枚举了各个参数及其可能的值。

重要说明：为了清楚起见，下文在介绍 URL 参数时使用的示例以转义前形式提供。向 API 发送任何请求前，应对其参数进行正确的 URL 编码。例如，许多参数都使用管道符号 (|) 作为分隔符，在最终 URL 中，该符号应编码为 %7C，正如本文档顶部的快速示例中所示。如需了解详细信息，请参阅生成有效的 URL。

Google Static Maps API 使用以下 URL 参数定义地图图像：

位置参数

• center（如果不存在标记，则为必填项）定义与地图所有边缘等距的中心。该参数带有逗号分隔 {latitude,longitude} 对形式的位置（例如：“40.714728,-73.998672”），或者表示地球表面某个唯一位置的字符串地址（例如：“city hall, new york, ny”）。如需了解详细信息，请参阅下文的位置。
• zoom（如果不存在标记，则为必填项）定义决定地图放大倍率的地图缩放比例。此参数带有与所需地区缩放比例对应的数字值。如需了解详细信息，请参阅下文的缩放比例。

地图参数

• size（必填项）定义地图图像的矩形尺寸。此参数带有 {horizontal_value}x{vertical_value} 形式的字符串。例如，500x400 定义的地图宽 500 像素、高 400 像素。宽度小于 180 像素的地图将显示为缩小尺寸的 Google 徽标。此参数受下文介绍的 scale 参数的影响；最终输出尺寸为 size 值与 scale 值的乘积。
• scale（选填项）影响返回的像素数。scale=2 返回 scale=1 两倍的像素数，同时保持覆盖面积和详细程度不变（即地图内容不变）。可以在进行高分辨率显示开发或生成印刷用途的地图时使用此参数。默认值为 1。可接受的值为 2 和 4（4 只适用于 Google Maps API for Work 客户。）如需了解详细信息，请参阅地图比例值。
• format（选填项）定义所生成图像的格式。默认情况下，Google Static Maps API 创建 PNG 图像。有几种格式可以使用，其中包括 GIF、JPEG 和 PNG 类型。您使用哪一种格式取决于您打算以何种方式呈现图像。JPEG 压缩率通常较高，而 GIF 和 PNG 更精细。如需了解详细信息，请参阅图像格式。
• maptype（选填项）定义要构建的地图类型。可接受的 maptype 值有若干个，其中包括 roadmap、satellite、hybrid 和 terrain。如需了解详细信息，请参阅下文的 Google Static Maps API Maptypes。
• language（选填项）定义在地图图块上显示的标签所使用的语言。请注意，只有部分国家图块支持此参数；如果图块集不支持所请求的特定语言，将使用该图块集的默认语言。
• region（选填项）根据地缘政治敏感性定义要显示的相应边界。接受以双字符 ccTLD（“顶级域”）值形式指定的地区代码。

特征参数

• markers（选填项）定义附加于指定位置处图像上的一个或多个标记。此参数带有单个标记定义，各参数使用管道符号 (|) 分隔。只要标记呈现的样式相同，便可在同一 markers 参数内放置多个标记；您可以通过添加额外的 markers 参数来添加不同样式的额外标记。请注意，在您为地图提供标记时，无需指定（通常必需的）center 参数和 zoom 参数。如需了解详细信息，请参阅下文的 Google Static Maps API 标记。
• path（选填项）定义要覆盖在指定位置图像上、由两个或更多个相连点组成的单个路径。此参数带有使用管道符号 (|) 分隔的点定义字符串。您可以通过添加额外 path 参数来提供额外路径。请注意，在您为地图提供路径时，无需指定（通常必需的）center 参数和 zoom 参数。如需了解详细信息，请参阅下文的 Google Static Maps API 路径。
• visible（选填项）指定即使不显示任何标记或其他指示器，也应在地图上保持可见状态的一个或多个位置。此参数用于确保某些特征或地图位置显示在 Google Static Maps API 上。
• style（选填项）定义用于改变地图特定特征（道路、公园等）呈现效果的自定义样式。此参数带有 feature 自变量和 element 自变量，分别表示要选择的特征，以及一组要对选定特征应用的样式操作。您可以通过添加额外 style 参数来提供多个样式。如需了解详细信息，请参阅下文的样式化地图。

密钥和签名参数

• key（必填项）让您可以在 Google Developers Console 中监控您的应用的 API 使用情况；启用按密钥而不是按 IP 地址的配额限制；并确保 Google 可以在必要时就应用的相关事宜与您联系。如需了解详细信息，请参阅获取密钥和签名。
• signature（推荐项）是一种数字签名，用于验证任何使用您的 API 密钥生成请求的网站都获得了相应授权。如需了解详细信息，请参阅获取密钥和签名。

Google Maps API for Work 用户必须在其请求中包含有效的 client 和 signature 参数。如需了解详细信息，请参阅 Google Maps API for Work 身份验证和授权一章。

URL 大小限制

Google Static Maps API URL 大小被限制在 2048 个字符。在实践中，除非您需要制作包含大量标记和路径的复杂地图，否则多半不需要长度超过该限值的 URL。但请注意，某些字符在发送给 API 之前可能由浏览器和/或服务进行 URL 编码，致使实际使用的字符数量增加。如需了解详细信息，请参阅生成有效的 URL。

参数使用

Google Static Maps API 相对容易使用，因为它只包括参数化 URL。此部分说明如何利用这些参数来构建您的 URL。

指定位置

Google Static Maps API 必须能精确识别地图上的位置，以便将地图聚焦于正确位置（使用 center 参数）和/或在地图上的各位置处放置任何可选标注（使用 markers 参数）。Google Static Maps API 使用数字（维度值和经度值）或字符串（地址）来指定这些位置。这些值表示地理编码位置。

几个参数（如 markers 参数和 path 参数）带有多个位置。在这些情况下，各位置之间使用管道符号 (|) 分隔。

纬度和经度

纬度和经度使用逗号分隔文本字符串内的数字定义，精确到 6 个小数位。例如，“40.714728,-73.998672”便是有效的地理编码值。超过 6 个小数位的精度会被忽略。

经度值基于其与本初子午线所在地英国格林威治的距离。由于格林威治所在地纬度为 51.477222，我们可以输入 51.477222,0 作为 center 的值，使地图以格林威治为中心：

纬度和经度值必须对应于地球表面上的有效位置。纬度可取 -90 和 90 之间的任何值，而经度可取 -180 和 180 之间的任何值。如果您指定的纬度值或经度值无效，您的请求将作为无效请求而遭到拒绝。

地址

大多数人不会使用纬度和经度进行交流，他们使用地址来表示位置。将地址转换为地理点的过程称为地理编码，如果您提供有效的地址，Google Static Maps API 服务便可为您执行地理编码。

在任何可以提供纬度/经度的参数中，您都可以改为指定表示地址的字符串。Google 将对地址进行地理编码，并为 Google Static Maps API 服务提供用于在放置标记或指定位置时使用的纬度值/经度值。字符串应为 URL 转义字符串，因此举例来说，“City Hall, New York, NY”这样的地址应转换为“City+Hall,New+York,NY”。

请注意，地址反映的可能是街道地址等精确位置，具名路线等多段线，或者城市、国家或国家公园等多边形区域。对于多段线结果和多边形结果，Google Static Maps API 服务器将使用线/区域的中心点作为地址中心。如果您对地址的地理编码方式有疑问，可以利用此地理编码实用程序对地址进行测试。

下例可为加利福尼亚州伯克利生成 Google Static Maps API：

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

缩放比例

Google 地图上的地图具有定义当前视图分辨率的整数“缩放比例”。在默认 roadmap 视图内，可接受的缩放比例为 0（最小缩放比例，可在一幅地图上显示整个世界）至 21+（精确到街道和个别建筑）。当缩放比例为 17 左右时，地图上会出现建筑轮廓（若有）。该值因区域而异，可能随数据的演化而逐渐发生变化。

Google 地图将缩放比例设置为 0 时可囊括整个地球。之后缩放比例每增加 1，水平维度和垂直维度均加倍。如需了解有关具体实现过程的详细信息，请参阅 Google Maps JavaScript API 文档。

注：并非地球上的所有位置都能以所有缩放比例呈现。缩放比例因位置而异，因为地球某些部分的数据精度高于其他位置。

如果您请求的缩放比例下没有可用的地图图块，Google Static Maps API 返回的地图将以该位置可达到的最大缩放比例呈现。

下例请求的两幅曼哈顿地图的 center 值相同，但缩放比例分别为 12 和 14：

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

  

图像尺寸

size 参数与 center 联用，用于定义地图的覆盖面积。它还可与 scale 值（默认值为 1）相乘来定义地图的输出尺寸（单位：像素）。

下表列出了各 scale 值下允许的最大 size 参数值。

API	scale=1	scale=2	scale=4
免费	640x640	640x640（返回 1280x1280 像素）	不可用。
Google Maps API for Work	2048x2048	1024x1024（返回 2048x2048 像素）	512x512（返回 2048x2048 像素）

下例请求以缩放比例 1 显示地球赤道位置某一“部分”的地图：

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

下例请求显示以同一地区为中心、尺寸为 100 x 100 像素的小地图。请注意较小的 Google 徽标：

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

地图比例值

Google Static Maps API 的 size 参数以像素定义地图的尺寸，因此 size=200x200 的地图将以 200 像素 x 200 像素形式返回。在一台像素密度通常约为 100 每英寸像素数 (ppi) 的 LCD 计算机显示器上，一幅 200x200 的地图各维度的值约为 2 英寸。

不过，移动设备使用像素密度超过 300ppi 的高分辨率屏幕的情况在日益增加，所造成的影响是：

• 将一幅 200x200 像素图像的尺寸缩小到 0.7 英寸，导致标签和图标因过小而无法辨认；或者
• 通过缩放图像来改善辨认度时，造成图像模糊或像素化。

过小	过于模糊

面向移动设备开发时，请利用 API 的 scale 参数返回更高分辨率的地图图像来解决以上问题。scale 值与 size 相乘可得出不改变地图覆盖面积条件下图像的实际输出尺寸（单位：像素）。（scale 默认值为 1；可接受的值为 1、2 和 [仅限 Google Maps API for Work 客户] 4）。

例如，当 scale 值为 2 时，返回的地图覆盖面积与未指定 scale 的请求相同，但各维度的像素数加倍。这包括道路和标签，从而使它们在高分辨率小尺寸屏幕上，以及在浏览器缩放的情况下都容易辨认。

150x150	150x150&scale=2

这样的图像在插入 img 标记或 div 标记后，并使用 CSS 设置高度和宽度时，同样可以在桌面浏览器上获得出色的显示效果。浏览器将在不损失质量的情况下将图像缩小至正确的尺寸。

下表显示了三种不同的图像请求。

• 第一个请求的是 100x100 图像，未指定 scale 值。它能在桌面上正常显示，但在移动设备上因过小而无法辨认。
• 第二个请求的目的是将地图尺寸加倍。在桌面上，CSS 可将其装入指定的 100x100 img 元素，但由于图像缩小尺寸的缘故，道路和标签变得过小。在移动设备上，图像尺寸合适，但还是同样的问题，道路和标签无法辨认。
• 第三个请求的是 scale=2 的 100x100 地图。所返回图像的精度为 200px；桌面对其进行的尺寸缩减很完美，难以分辨其与原始 100x100 请求的区别，而移动浏览器则受益于 API 返回的附加分辨率。

设备	100x100	200x200	100x100&scale=2
桌面 （在 img 标记中，height="100px"， width="100px" ）
高分辨率 （模拟）

提示：Android 和 iOS 等移动平台允许应用通过为每一种分辨率指定不同的图像来支持高分辨率屏幕。只需分别设置 scale=1 和 scale=2，便可利用 scale 参数轻松地为标准分辨率屏幕请求地图图像，为高分辨率屏幕请求匹配的地图。

如需了解有关面向移动和高分辨率显示开发的详细信息，建议阅读以下内容：

• Android 开发者文档中的支持多种屏幕
• Webkit.org 针对高 DPI 网站的建议
• iOS 开发者内容库中的支持高分辨率屏幕

图像格式

可以下面这几种常见的 Web 图形格式返回图像：GIF、JPEG 和 PNG。format 参数取下列值之一：

• png8 或 png（默认值）指定 8 位 PNG 格式
• png32 指定 32 位 PNG 格式
• gif 指定 GIF 格式
• jpg 指定 JPEG 压缩格式
• jpg-baseline 指定非渐进式 JPEG 压缩格式

jpg 和 jpg-baseline 通常可提供最小的图像尺寸，但这是通过可能降低图像质量的“有损”压缩实现的。gif、png8 和 png32 提供无损压缩。

大多数 JPEG 图像是渐进式的，也就是说，它们会先加载较粗糙的图像，然后随着更多数据的到来改善图像分辨率。这有利于图像在网页中的快速加载，并且是 JPEG 目前最广泛的用途。不过，JPEG 的某些用途（尤其是打印）要求使用非渐进式（基线）图像。在此类情况下，您可能需要使用非渐进式的 jpg-baseline 格式。

地图类型

Google Static Maps API 以下列几种格式创建地图：

• roadmap（默认值）指定标准路线图图像，即 Google 地图网站上正常显示的图像。如果不指定 maptype 值，则默认情况下由 Google Static Maps API 提供 roadmap 图块。
• satellite 指定卫星图像。
• terrain 指定显示地形和植被的自然地形地图图像。
• hybrid 指定混合型卫星和路线图图像，显示一个透明的主要街道层，并在卫星图像上放置名称。

您可以通过以下代码示例了解 roadmap 类型与 terrain 类型之间的差异。

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

  

混合型地图利用卫星图像和显著的路线图特征来创建组合式地图。以下示例显示了卫星地图类型和混合地图类型：

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

  

样式化地图

您可以利用样式化地图定制标准 Google 地图样式的呈现方式，从而更改道路、公园和建成区等元素的视觉显示，体现出与默认地图类型所用相异的样式。这些组件称为特征，样式化地图允许您选择这些特征并对其显示应用视觉样式（包括将它们完全隐藏）。可通过这些更改使生成的地图突出周围页面内的特定组件或补充内容。

定制的“样式化”地图包括一个或多个指定样式，其中的每个样式都通过 Google Static Maps API 请求 URL 内的 style 参数指定。附加样式通过传递附加 style 参数进行指定。样式包括选定项和应用于该选定项的一组规则。规则指定对选定项做出的视觉修改。

每个 style 声明都包括下列参数，style 声明内的这些参数之间使用管道符号（“|”）进行分隔：

• feature（选填项）表示为此样式修改选择哪些特征。（请参阅下文的地图特征。）如果未传递 feature 参数，将选择所有特征。
• element（选填项）表示选择选定特征的哪个子集。（请参阅下文的地图元素。）如果未传递 element 参数，将选择给定特征的所有元素。
• 任何后续参数均指定应用于以上选定项的规则。所有规则都按它们在 style 声明内的出现顺序应用。（请参阅下文的样式规则。）特征选定项可在 Google Static Maps API 的正常 URL 长度限制内后跟任意数量的规则。

注：style 声明必须按规定顺序指定以上参数。例如，后跟两个规则的特征选定项将如下所示：

style=feature:featureArgument|element:elementArgument|rule1:rule1Argument|rule2:rule2Argument

地图特征

地图包括道路或公园等一系列特征。特征类型组成类别树，以 feature:all 为树根。以下列出了一些常见特征：

• feature:all（默认值）选择地图的所有特征。
• feature:road 选择地图上的所有道路。
• feature:landscape 选择地图上的所有背景景观，例如，道路之间的区域通常就属于此类景观。在城市中，景观通常包括建成区。

Google Maps JavaScript API 参考中记述了可供在地图内选择的特征的完整列表。

某些特征类型类别包含的子类别使用点分表示法（例如 landscape.natural 或 road.local）指定。如果指定了上级特征（例如，road），则应用于该选定项的样式将应用于包括子类别在内的所有道路。

地图特征元素

此外，地图上的某些特征通常包含不同的元素。例如，道路不仅包含地图上的图形线（几何结构），还包括表示其附加在地图上的名称（标签）的文本。特征内的元素通过声明 element 参数进行选择。支持的元素参数值如下：

• element:all（默认值）选择该特征的所有元素
• element:geometry 只选择该特征的几何元素
• element:labels 只选择与该特征关联的文本标签

如果未传递 element 参数，将对特征的所有元素应用样式，不考虑元素类型。

以下 style 声明选择所有本地道路的标签：

style=feature:road.local|element:labels

样式规则

样式规则是应用于每个 style 声明内指定的特征和元素的格式设置选项。每个 style 声明都必须包含一个或多个使用管道符号（“|”）分隔的操作。每个操作都使用冒号（“:”）字符指定其参数值，所有操作都按其指定顺序应用于选定项。

目前支持的操作参数及其取值如下：

• hue（0xRRGGBB 格式的 RGB 十六进制字符串）表示应用于选定项的基础颜色。（* 请参阅下文的使用说明。）
• lightness（一个介于 -100 和 100 的浮点值）表示元素的亮度变化百分比。负值增加暗度（-100 指定黑色），正值增加亮度（+100 指定白色）。
• saturation（一个介于 -100 和 100 的浮点值）表示应用于元素的基础颜色强度变化百分比。
• gamma（一个介于 0.01 和 10.0 的浮点值，其中 1.0 不应用任何校正）表示对元素应用的伽马校正的大小。伽马校正以非线性方式修改色调的亮度，同时对白色值或黑色值没有影响。伽马校正通常用于修改多个元素的对比度。例如，您可以通过修改伽马校正值来增减元素边缘与内部之间的对比度。低伽马校正值 (< 1) 可提高对比度，而高伽马校正值 (> 1) 则可降低对比度。
• inverse_lightness:true 单纯用于反转现有亮度。
• visibility（on、off 或 simplified）表示元素是否以及如何出现在地图上。visibility:simplified 表示地图应按照其认为适当的方式简化这些元素的呈现。（例如，经过简化的道路结构所显示的道路可能会减少。）

样式规则必须以独立的不同操作形式应用，并且按它们在 style 声明内的出现顺序应用。顺序很重要，因为某些操作是不可交换的。通过样式操作修改的特征和/或元素（通常）已有样式；操作将作用于这些已有样式（若存在）。

请注意，我们使用色调、饱和度、亮度 (HSL) 模型在样式器操作内表示颜色。这些用于定义颜色的操作在图形设计中司空见惯。色调表示基础颜色，饱和度表示该颜色的强度，亮度表示组成颜色中白色或黑色的相对数量。这三种 HSL 值都可映射到 RGB 值（以及进行反向映射）。伽马校正的作用是修改色彩空间的饱和度，通常用于提高或降低对比度。此外，HSL 模型还定义了坐标空间内的颜色，其中 hue 表示色轮内的朝向、而 saturation 和 lightness 则表示沿不同轴的振幅。色调在一个 RGB 色彩空间内测量，该空间与大多数 RGB 色彩空间类似，不同的是缺少白色和黑色阴影。

一个 RGB 色轮

注：尽管 hue 采用 RGB 十六进制颜色值，但它仅使用该值来确定基础颜色（其在色轮范围内的朝向）而非其饱和度或亮度，后者以百分比变化形式单独指定。例如，可将纯绿色的色调定义为 hue:0x00ff00 或 hue:0x000100，这两个色调将完全相同。（两个值都指向 HSL 颜色模型中的纯绿色。）包含等量红色、绿色和蓝色的 RGB hue 值—如 hue:0x0000000（黑色）和 hue:0xffffff（白色）以及所有纯灰阴影—不表示任何色调，因为其中没有任何值表示 HSL 坐标空间内的朝向。如需表示黑色、白色或灰色，您必须删除所有 saturation（添加一个 saturation:-100 操作），并改为调整 lightness。

此外，在修改已有配色方案的现有特征时，更改 hue 等值并不会改变其现有 saturation 或 lightness。

下例显示了一幅布鲁克林区地图，其中的本地道路已更改为亮绿色，住宅区已更改为黑色（请注意，在这个全功能示例中，管道分隔符已进行了正确的 URL 编码；请参阅上文的注）：

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=15&center=Brooklyn&style=feature:road.local%7Celement:geometry%7Ccolor:0x00ff00%7Cweight:1%7Cvisibility:on&style=feature:landscape%7Celement:geometry.fill%7Ccolor:0x000000%7Cvisibility:on&style=feature:administrative%7Celement:labels%7Cweight:3.9%7Cvisibility:on%7Cinverse_lightness:true&style=feature:poi%7Cvisibility:simplified&key=YOUR_API_KEY

下例利用操作和简化来粗略呈现美国道路图的外观：

https://maps.googleapis.com/maps/api/staticmap?size=512x512&zoom=12&center=Chicago&format=png&style=feature:road.highway%7Celement:geometry%7Cvisibility:simplified%7Ccolor:0xc280e9&style=feature:transit.line%7Cvisibility:simplified%7Ccolor:0xbababa&style=feature:road.highway%7Celement:labels.text.stroke%7Cvisibility:on%7Ccolor:0xb06eba&style=feature:road.highway%7Celement:labels.text.fill%7Cvisibility:on%7Ccolor:0xffffff&key=YOUR_API_KEY

标记

markers 参数定义一组位置处的一组（一个或多个）标记。在一个 markers 声明内定义的每个标记都必须呈现相同的视觉样式；如果您想显示具有不同样式的标记，则需提供具有不同样式信息的多个 markers 参数。

markers 参数取以下格式的一组赋值（标记描述符）：

markers=markerStyles|markerLocation1| markerLocation2|... 依此类推

markerStyles 集在 markers 的开头处声明，包含零个或更多个由管道符号 (|) 分隔的样式描述符，后跟同样以管道符号 (|) 分隔的一组（一个或多个）位置。

由于样式信息和位置信息都通过管道符号分隔，因此在任何标记描述符中，都必须先出现样式信息。Google Static Maps API 服务器遇到标记描述符中的某个位置后，也会将所有其他标记参数视为位置。

标记样式

这组标记样式描述符是一系列由管道符号 (|) 分隔的赋值。该样式描述符定义在此标记描述符内显示标记时使用的视觉属性。这些样式描述符包含下列键/赋值：

• size:（选填项）从 {tiny, mid, small} 集中指定标记的尺寸。如果未设置 size 参数，将以默认（正常）尺寸显示标记。

• color:（选填项）指定 24 位颜色（例如：color=0xFFFFCC）或 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 集中的预定义颜色。

  请注意，尽管路径提供支持，但标记中并不支持透明度（使用 32 位十六进制颜色值指定）。

• label:（选填项）指定 {A-Z, 0-9} 集中的单个大写字母数字字符。（这一大写字符要求是此版本 API 新增的要求。）请注意，默认尺寸和 mid 尺寸标记是仅有的能够显示 alphanumeric-character 参数的标记。tiny 和 small 标记无法显示字母数字字符。

注：您可能想使用自己的自定义图标来替代这些标记。（如需了解详细信息，请参阅下文的自定义图标。）

标记位置

每个标记描述符都必须包含一组（一个或多个）位置，用于定义在地图上何处放置标记。这些位置可指定为纬度/经度值形式或地址形式。这些位置使用管道符号 (|) 分隔。

位置参数定义标记在地图上的位置。如果位置不在地图上，该标记将不会出现在构建的图像中，前提是提供了 center 参数和 zoom 参数。不过，如果未提供这些参数，Google Static Maps API 服务器将自动构建包含所提供标记的图像。（请参阅下文的隐式定位。）

以下显示了一个示例标记声明。请注意，我们定义了一组样式和三个位置：

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

如需定义具有不同样式的标记，我们需要提供多个 markers 参数。这组 markers 参数定义了三个标记：一个是位于 62.107733, -145.5419、标示为“S”的蓝色标记，一个是位于“阿拉斯加州德尔塔章克申”的小尺寸绿色标记，还有一个是位于“阿拉斯加州托克”、标示为“C”的中等尺寸黄色标记。下例中显示了这些标记：

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

自定义图标

您可以不受限制地改用自己的自定义图标来替代 Google 的标记图标。自定义图标使用下列 markers 参数的描述符指定：

• icon 指定用作标记自定义图标的 URL。图像可采用 PNG、JPEG 或 GIF 格式，但建议采用 PNG。
• shadow（默认值为 true）表示 Google Static Maps API 服务应为图像构建合适的阴影。该阴影基于图像的可见区域及其不透明度/透明度。

icon 参数必须使用 URL 指定（应接受 URL 编码）。您可以使用自选的任何有效 URL，或者 http://goo.gl 等 URL 缩短服务。大多数 URL 缩短服务都具有自动为 URL 编码的优点。图标尺寸上限为 4096 像素（方形图像上限为 64x64 像素），Google Static Maps API 服务允许每次最多请求五个唯一的自定义图标。请注意，这些唯一图标均可在 Google Static Maps API 内多次使用。

具有 shadow:true 描述符（默认值）的自定义图标的“锚点”将设置为所提供图标图像的底部中心，即阴影的投射中心。相反，不带阴影（设置 shadow:false 描述符）的图标将被视为以其指定位置为中心的图标，因此其锚点将设置为图像的中心。

下例使用 Google 的 Chart API 创建自定义标记，显示的是纽约市的几家咖啡店：

https://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&key=YOUR_API_KEY

注：以上的多层转义可能令人迷惑。Google Chart API 使用管道符号 (|) 来分隔其 URL 参数内的字符串。由于该符号在 URL 内不合法（请参阅上文的注），因此在创建完全有效的图表 URL 时，会将其转义为 %7C。现在结果以字符串形式嵌入 icon 值内，但它包含 % 字符（来自上面提及的 %7C），该字符无法以数据形式直接包括在 URL 内，必须转义为 %25。结果是，URL 包含 %257C，它代表了两层编码。同理，图表 URL 包含的 & 字符也无法在不被混同为 Google Static Maps API URL 参数分隔符的情况下直接包括在 URL 内，因此也必须进行编码。

以下是创建 Google Static Maps API URL 的步骤：

# 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 Google Static Maps API URL:
...&markers=icon:http://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Google Static Maps API 路径

path 参数定义一组（一个或多个）位置，这些位置由路径相连，覆盖在地图图像上。path 参数取以下格式的一组赋值（路径描述符）：

path=pathStyles|pathLocation1|pathLocation2|... 依此类推

请注意，这些路径点相互之间均使用管道符号 (|) 分隔。由于样式信息和点信息都通过管道符号分隔，因此在任何路径描述符中，都必须先出现样式信息。Google Static Maps API 服务器遇到路径描述符中的某个位置后，也会将所有其他路径参数视为位置。

路径样式

这组路径样式描述符是一系列由管道符号 (|) 分隔的赋值。该样式描述符定义显示路径时使用的视觉属性。这些样式描述符包含下列键/赋值：

• weight:（选填项）指定路径的厚度（单位：像素）。如果未设置 weight 参数，将以其默认厚度（5 像素）显示路径。

• color:（选填项）指定 24 位十六进制值形式颜色（示例：color=0xFFFFCC）或 32 位十六进制值形式颜色（示例：color=0xFFFFCCFF），或在 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 集中指定一种颜色。

  指定 32 位十六进制值时，最后两个字符表示 8 位 alpha 透明度值。该值在 00（全透明）至 FF（全不透明）范围内变化。请注意，路径中支持透明度，但标记中并不支持透明度。

• fillcolor:（选填项）指示路径划出的多边形区域，并指定用作该区域内叠层的填充色。后跟的一组位置无需是“封闭”循环；Google Static Maps API 服务器会自动连接第一点和最后一点。但请注意，服务器不会封闭填充区外部的任何描边，除非您明确提供相同的开始位置和结束位置。
• geodesic:（选填项）表示应将请求的路径解读为依循地球曲度的测地线。值为 false 时，路径渲染为屏幕空间内的一条直线。默认值为 false。

以下是一些示例路径定义：

• 50% 不透明度的蓝色细线 ：path=color:0x0000ff80|weight:1
• 红色实线：path=color:0xff0000ff|weight:5
• 白色粗实线：path=color:0xffffffff|weight:10

这些路径样式为可选样式。如果需要的是默认属性，您可以跳过定义路径属性的步骤；在这种情况下，路径描述符的第一个“参数”将改为包括第一个声明点（位置）。

路径点

如需绘制路径，还必须向 path 参数传递两个或更多个点。然后，Google Static Maps API 将按指定顺序沿这些点连接路径。pathDescriptor 中表示的每个 pathPoint 都以 |（管道）符号分隔。

下例定义从纽约市联合广场至纽约市时代广场、使用默认 50% 不透明度的蓝色路径。

path 参数的详情如下所示：

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

下例定义的是同一路径，不同的是，它定义的是一条不透明度为 100% 的红色实线：

此 path 参数的详情如下所示：

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

下例定义的是曼哈顿内的一个多边形区域，传递了一系列交叉路口作为位置：

此 path 参数的详情如下所示：

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

请注意，我们将路径本身设置为不可见，将多边形区域的不透明度设置为 15%。

编码多段线

您可以不使用一系列位置，而是改为在 path 的位置声明内使用 enc: 前缀以编码多段线形式声明路径。请注意，在您为地图提供编码多段线路径时，无需指定（通常必需的）center 参数和 zoom 参数。

下例使用编码多段线描画阿拉斯加高速公路不列颠哥伦比亚省道森克里克至阿拉斯加州德尔塔章克申段道路的轮廓：

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

与标准路径一样，如果向 path 参数传递了 fillcolor 自变量，编码多段线路径也可划分多边形区域。

下例描画纽约市布鲁克林区的多边形区域轮廓：

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

视口

可通过利用 visible 参数指定可见位置来为图像指定视口。visible 参数指示 Google Static Maps API 服务在构建地图时让现有位置保持可见状态。（此参数还可与现有标记或路径结合使用来定义可见区域。）以这种方式定义视口时，可不必指定确切的缩放比例。

下例请求的地图以马萨诸塞州波士顿为中心，将麻省理工学院和马萨诸塞州坎布里奇的哈佛广场都包含在内：

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

隐式地图定位

正常情况下，您需要指定 center 和 zoom URL 参数，才能定义所生成地图的位置和缩放比例。不过，如果您提供 markers 参数、path 参数或 visible 参数，则可改为让Google Static Maps API 根据对这些元素位置的评估隐式地确定正确的中心和缩放比例。

如果提供两个或更多个元素，Google Static Maps API 将确定适当的中心和缩放比例，从而为包含的元素提供充裕的边距。下例显示的地图包含加利福尼亚州的旧金山、奥克兰和圣何塞：

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

故障排除和支持

如需了解有关使用 Google Static Maps API 的详细信息，请参阅支持页面。

Google Static Maps API 可能会在出现故障时显示错误或警告。您应该检查有无警告，尤其是在您注意到地图中缺少内容时。此外，最好也在启动新应用前检查有无警告。请注意，不一定会立即注意到警告，因为它们出现在 HTTP 标头中。如需了解详细信息，请参阅错误和警告指南。

Google Static Maps API 之前要求您包括 sensor 参数，以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。