开始使用

简介

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

Maps Static API 图片会嵌入到 <img> 标记的 src 属性中，或其他编程语言的等效属性中。

本文档介绍了 Google 地图静态 API 网址所需的格式及可用参数。此外，它还指出了在指定网址方面的一些技巧和诀窍。

准备工作

本文档的适用对象是想要在网页或移动应用内加入 Maps Static API 图片的网站和移动开发者。其中介绍了如何使用此 API 以及有关可用参数的参考资料。

在开始使用 Maps Static API 进行开发之前，请查看身份验证要求（您需要 API 密钥）和 API 使用和结算信息（您需要为项目启用结算功能）。

网址参数

Maps Static API 网址必须采用以下格式：

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

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

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

无论使用 HTTP 还是 HTTPS，有些网址参数是必需的，有些则是可选的。依照网址的标准，所有参数都使用“与”符号 (&) 分隔。本文档列出了各个参数及其可能的值。

Maps Static API 使用以下网址参数定义地图图片：

位置参数

  • center（如果不存在标记，则为必需）定义与地图所有边缘等距的中心。此参数接受以逗号分隔的 {纬度,经度} 对（例如“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。可接受的值为 1 和 2。如需了解详情，请参阅比例值。
  • format（可选）用于定义生成的图片的格式。默认情况下，Maps Static API 会创建 PNG 图片。有多种可能的格式，包括 GIF、JPEG 和 PNG 类型。您使用哪种格式取决于您打算以何种方式呈现图像。JPEG 压缩率通常较高，而 GIF 和 PNG 更精细。如需了解详情，请参阅图片格式。
  • maptype（可选）定义要构建的地图类型。可能的 maptype 值有多个，包括 roadmap、satellite、hybrid 和 terrain。如需了解详情，请参阅 Maps Static API 地图类型。
  • language（可选）定义在地图图块上显示的标签所使用的语言。请注意，只有部分国家图块支持此参数；如果图块集不支持所请求的特定语言，将使用该图块集的默认语言。
  • region（可选）根据地缘政治敏感性定义要显示的相应边界。接受以双字符 ccTLD（“顶级域名”）值形式指定的地区代码。如需了解支持的地区，请参阅 Google Maps Platform 覆盖范围详细信息。

地图项参数

  • map_id（可选）指定特定地图的标识符。地图 ID 可将地图与特定样式或地图项相关联，并且必须与用于初始化地图的 API 密钥属于同一项目。如需了解详情，请参阅使用地图 ID。
  • markers（可选）用于定义要附加到指定位置处图像上的一个或多个标记。此参数带有单个标记定义，各参数使用竖线字符 (|) 分隔。只要标记呈现的样式相同，便可在同一 markers 参数内放置多个标记；您可以通过添加额外的 markers 参数来添加不同样式的额外标记。请注意，在您为地图提供标记时，无需指定（通常必需的）center 和 zoom 参数。如需了解详情，请参阅 Maps Static API 标记。
  • path（可选）定义要在指定位置叠加到图片上的两个或多个连接点的单条路径。 此参数接受使用竖线字符 (|) 分隔的点定义字符串，或在路径的位置声明中使用 enc: 前缀编码的多段线。您可以通过添加额外的 path 参数来提供额外路径。请注意，在您为地图提供路径时，无需指定（通常必需的）center 和 zoom 参数。如需了解详情，请参阅 Maps Static API 路径。
  • visible（可选）指定一个或多个应在地图上保持可见状态（尽管不会显示标记或其他指示器）的地点。此参数用于确保某些地图项或地图位置显示在 Maps Static API 中。
  • style（可选）用于定义自定义样式，以改变地图的特定地图项（道路、公园和其他地图项）的呈现效果。此参数带有 feature 和 element 自变量，分别表示要设置样式的地图项，以及一组要对选定地图项应用的样式操作。您可以通过添加额外的 style 参数来提供多个样式。如需了解详情，请参阅有关自定样式的地图的指南。

密钥和签名参数

  • 借助 key（必需），您可以在 Google Cloud 控制台中监控应用的 API 用量，并确保 Google 在必要时可以就您的应用与您联系。 如需了解详情，请参阅将 API 密钥与 Maps Static API 搭配使用。
  • signature（推荐）是一种数字签名，用于验证任何使用您的 API 密钥生成请求的网站都获得了相应授权。没有数字签名的请求可能会失败。 如需了解详情，请参阅使用数字签名。

网址大小限制

Maps Static API 网址大小不得超过 16384 个字符。在实践中，除非您需要制作包含大量标记和路径的复杂地图，否则多半不需要长度超过该限值的网址。

参数使用

Maps Static API 相对容易使用，因为它只包括参数化网址。本部分介绍了如何使用这些参数构建网址。

指定位置

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

几个参数（如 markers 和 path 参数）带有多个位置。在这些情况下，这些位置使用竖线 (|) 字符分隔。

纬度和经度

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

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

英国格林威治

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

地址

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

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

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

以下示例可为加利福尼亚州伯克利生成静态地图图片：

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

加利福尼亚州伯克利

缩放级别

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

Google 地图将缩放级别设置为 0 时可囊括整个地球。随后的每个缩放级别都会将水平和垂直方向的精度加倍。如需详细了解具体实现方法，请参阅 Google Maps JavaScript API 文档。

注意：并非地球上的所有位置都会显示所有缩放级别。缩放级别因位置而异，因为地球上某些地区的数据比其他位置的数据更细化。

如果您请求的缩放级别下没有可用的地图图块，Maps Static API 将改为返回空白图片。

以下列表显示了您在每个缩放级别看到的地图的大致详细程度：

  • 1：世界
  • 5：大陆/洲
  • 10：城市
  • 15：街道
  • 20：建筑物

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

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

曼哈顿远景  曼哈顿近景

图片尺寸

size 参数与 center 结合使用可定义地图的覆盖区域。将其与 scale 值（默认为 1）相乘时，还可以定义地图的输出大小（以像素为单位）。

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

scale=1 scale=2
640x640 640x640（返回 1280x1280 像素）

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

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

赤道

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

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

小赤道地图

比例值

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

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

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

在针对移动设备进行开发时，您可以使用 API 的 scale 参数返回分辨率更高的地图图片，从而解决上述问题。scale 值与 size 相乘可得出不改变地图覆盖面积条件下图像的实际输出尺寸（单位：像素）。默认的 scale 值为 1；可接受的值为 1 和 2。

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

150x150 150x150 且 scale=2

此类图片在插入使用 CSS 设置高度和宽度的 img 或 div 标记后，在桌面浏览器上也可取得良好效果。浏览器将在不损失质量的情况下将图像缩小至正确的尺寸。

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

  • 第一项请求的对象是大小为 100x100 且未指定比例值的图片。它能在桌面上正常显示，但在移动设备上因过小而无法辨认。
  • 第二项请求的对象是大小为前者两倍的地图。在桌面上，CSS 可将其装入指定的 100x100 img 元素，但由于图像缩小尺寸的缘故，道路和标签变得过小。在移动设备上，图片尺寸合适，但道路和标签仍然难以辨认。
  • 第三个请求的是 scale=2 的 100x100 地图。所返回图像的精度为 200px；桌面对其进行的尺寸缩减很完美，难以分辨其与原始 100x100 请求的区别，而移动浏览器则受益于 API 返回的附加分辨率。
图片请求
设备 100x100 200x200 100x100&scale=2
桌面
（在
img 标记中，height="100px" 和
width="100px"）
高分辨率
（模拟）

如需详细了解如何针对移动设备和高分辨率显示屏进行开发，建议阅读以下内容：

图片格式

图片可以采用以下几种常见的网络图形格式返回：GIF、JPEG 和 PNG。format 参数取下列值之一：

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

以下示例请求的是 gif 和 png 格式的地图：

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

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

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

地图类型

Maps Static API 可以多种格式创建地图，如下所示：

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

您可以在此代码示例中查看路线图类型和地形类型之间的区别。

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

曼哈顿普通地图  曼哈顿地形地图

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

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

曼哈顿卫星地图  曼哈顿地形地图

自定样式的地图

通过应用您自己的样式，自定义标准 Google 地图的显示。 请参阅自定义地图样式指南。

标记

markers 参数定义一组位置处的一组（一个或多个）标记（地图图钉）。单个 markers 声明中定义的每个标记都必须具有相同的视觉样式；如果您希望显示不同样式的标记，则需要提供多个具有单独样式信息的 markers 参数。

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

markers=markerStyles|markerLocation1| markerLocation2|... 等

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

由于样式信息和位置信息都通过竖线字符分隔，因此在任何标记描述符中，都必须先出现样式信息。当 Maps Static 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 标记无法显示字母数字字符。

标记缩放

scale 值与标记图片大小相乘，可得出标记的实际输出尺寸（以像素为单位）。默认比例值为 1；可接受的值为 1、2 和 4。

图片的像素大小限制在缩放应用后应用。例如，如果将标记设置为 scale:2，则标记可以大于 4096 像素的大小上限，只要在缩放后小于 4096 像素即可。在显示更高分辨率的地图时，请将标记缩放与地图缩放结合使用。

标记位置

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

注意：如果您选择使用需要进行地理编码的方法（例如可人工读取的地址字符串或多段线）指定标记位置，则请求最多只能包含 15 个标记。此限制仅适用于需要进行地理编码的标记位置。并不适用于以纬度/经度坐标指定的标记位置。

位置参数用于定义标记在地图上的位置。如果位置不在地图上，该标记将不会出现在构建的图像中，前提是提供了 center 和 zoom 参数。不过，如果未提供这些参数，Maps Static 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&signature=YOUR_SIGNATURE

三个布鲁克林区邮政编码

如需定义具有不同样式的标记，我们需要提供多个 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&signature=YOUR_SIGNATURE

三个使用不同标记的阿拉斯加州城镇

自定义图标

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

markers=icon:URLofIcon|markerLocation

使用网址（应接受网址编码）指定 icon。您可以使用通过网址缩短服务创建的网址，例如 https://goo.gl。大多数网址缩短服务都具有自动为网址编码的优点。

您可以为自定义图标指定锚点。锚点用于设置图标相对于指定 markers 位置的放置方式。默认情况下，自定义图标的锚点为图标图片的底部中心。您可以将 anchor 描述符与 icon 结合使用，指定其他锚点。将 anchor 设置为图标的 x,y 点（例如 10,5），或使用以下值之一设置为预定义对齐：top、bottom、left、right、center、topleft、topright、bottomleft 或 bottomright。例如：

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

每个请求最多可以使用五个唯一的自定义图标。此限制并不意味着您只能在地图上标记 5 个位置。每个唯一图标都可以用于地图上的多个 markers 位置。

图标格式：

  • 图标图片可以是 PNG、JPEG 或 GIF 格式，但建议采用 PNG。
  • 图标大小不得超过 4096 像素（方形图片为 64x64 像素）。
自定义图标示例

示例 1：创建自定义图标并使用锚点放置图标。

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

三个澳大利亚城镇，使用锚点放置不同的自定义图标。

示例 2 会创建与示例 1 相同的自定义图标，但不会使用锚点设置图标位置，而是依赖于底部中心的默认锚点。

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

澳大利亚三个小镇，带有默认位置的不同自定义图标。

Maps Static API 路径

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

path=pathStyles|pathLocation1|pathLocation2|... 等

请注意，这些路径点相互之间均使用竖线字符 (|) 分隔。由于样式信息和点信息都通过竖线字符分隔，因此在任何路径描述符中，都必须先出现样式信息。Maps Static 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:（选填项）指示路径划出的多边形区域，并指定用作该区域内叠层的填充色。后跟的一组位置无需是“闭合”环路；Maps Static API 服务器会自动连接第一点和最后一点。但请注意，服务器不会封闭填充区外部的任何描边，除非您明确提供相同的开始位置和结束位置。
  • geodesic:（可选）表示请求的路径应解读为沿地球曲度的测地线。值为 false 时，路径渲染为屏幕空间内的一条直线。默认值为 false。

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

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

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

路径点

若要绘制路径，还必须向 path 参数传递两个或更多个点。然后，Maps Static 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: 前缀以编码多段线形式声明路径。

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

阿拉斯加高速公路

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

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

带签名的布鲁克林编码多段线

视口

您可以通过使用 visible 参数指定可见位置，为图像指定视口。visible 参数会指示 Maps Static 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&signature=YOUR_SIGNATURE

坎布里奇地图

隐式地图定位

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

如果提供两个或更多个元素，Maps Static 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&signature=YOUR_SIGNATURE

路线图

更大的图片尺寸

如果您需要的图片尺寸大于 640 x 640 像素（或 1280 x 1280 像素，且缩放值为 2），请 与支持团队联系并提供以下信息：

  1. 您的用例以及您需要大尺寸图片的原因。
  2. 您是否考虑过使用其他 Google Maps Platform API（Maps JavaScript API、Maps Embed API、Maps SDK for Android 或 Maps SDK for iOS），以及这些 API 为何不符合您的需求。
  3. 屏幕截图、模拟图或示例，展示您将如何使用大尺寸图片。
  4. 大尺寸图片的每月预估用量。

我们会根据您提供的信息审核您的申请，并确定您的用例是否符合 Google Maps Platform 服务条款。

我们可以提供的最大尺寸为 2048 x 2048 像素。

问题排查和支持

如需详细了解如何使用 Maps Static API，请参阅支持页面。

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