开始使用

简介

Maps Static API 通过网址返回图片(GIF、PNG 或 JPEG)来响应 HTTP 请求。对于每个请求,您可以指定地图位置、图片大小、缩放级别、地图类型以及可选标记在地图上的位置。此外,您还可以使用字母数字字符为标记添加标签。

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

本文档介绍了所需的 Maps Static 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”)或字符串地址(例如“市政厅、纽约、纽约”)为目标的位置,用于标识地球表面的唯一位置。如需了解详情,请参阅位置
  • zoom(如果标记不存在,则为必需)用于定义地图的缩放级别,该级别决定了地图的放大级别。此参数采用与所需区域缩放级别对应的数值。如需了解详情,请参阅缩放级别

映射参数

  • size(必需)用于定义地图图片的矩形尺寸。此参数接受 {horizontal_value}x{vertical_value} 形式的字符串。例如,500x400 定义了宽 500 像素、高 400 像素的地图。宽度小于 180 像素的地图将显示缩小的 Google 徽标。此参数受 scale 参数的影响;最终输出大小为大小与缩放值之和。
  • scale(可选)会影响返回的像素数。scale=2 返回的像素数是 scale=1 的两倍,且覆盖区域和细节级别保持不变(即地图内容不变)。这在针对高分辨率显示屏进行开发时很有用。 默认值为 1。接受的值包括 12。如需了解详情,请参阅比例值
  • format(可选)- 用于定义生成的图片的格式。默认情况下,Maps Static API 创建 PNG 图片。有多种可能的格式,包括 GIF、JPEG 和 PNG 类型。使用哪种格式取决于您打算如何呈现图片。JPEG 通常可提供更大的压缩率,而 GIF 和 PNG 可提供更多细节。如需了解详情,请参阅图片格式
  • maptype(可选)- 用于定义要构造的地图类型。有多种可能的地图类型值,包括 roadmapsatellitehybridterrain。如需了解详情,请参阅 Maps Static API 地图类型
  • language(可选)- 用于指定在地图图块上显示标签时所用的语言。请注意,只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则系统会使用该图块集的默认语言。
  • region(可选)根据地缘政治敏感性定义要显示的相应边界。接受以两个字符的 ccTLD(“顶级域名”)值形式指定的地区代码。如需了解受支持的区域,请参阅 Google Maps Platform 覆盖范围详细信息

特征参数

  • map_id(可选)- 指定特定地图的标识符。地图 ID 会将地图与特定样式或地图项相关联,并且必须与用于初始化地图的 API 密钥属于同一个项目。如需了解详情,请参阅使用地图 ID
  • markers(可选)用于定义要在指定位置附加到图片的一个或多个标记。此参数采用单个标记定义,以竖线字符 (|) 分隔参数。只要标记样式相同,就可以在同一 markers 参数中放置多个标记;您可以通过添加其他 markers 参数来添加不同样式的其他标记。请注意,如果为地图提供标记,则无需指定(通常必需的)centerzoom 参数。如需了解详情,请参阅 Maps Static API 标记
  • path(可选)用于定义要在指定位置叠加在图像上的两个或多个连接点的单路径。此参数采用由竖线字符 (|) 分隔的点定义字符串或编码路径(在路径的位置声明中使用 enc: 前缀)。您可以通过添加其他 path 参数来提供其他路径。请注意,如果为地图提供路径,则无需指定(通常必需的)centerzoom 参数。如需了解详情,请参阅 Maps Static API 路径
  • visible(可选):用于指定应该在地图上保持可见的一个或多个位置,但不会显示任何标记或其他指示符。使用此参数可确保 Maps Static API 上显示某些地图项或地图位置。
  • style(可选):用于定义自定义样式,用于更改特定地图项(道路、公园和其他地图项)的显示方式。此参数接受 featureelement 参数,以便确定要设置样式的地图项,以及一组要应用于选定地图项的样式操作。您可以通过添加额外的 style 参数来提供多个样式。如需了解详情,请参阅有关自定样式的地图的指南。

密钥和签名参数

  • key必需)让您可以在 Google Cloud Console 中监控应用的 API 使用情况,并确保 Google 可以在必要时就应用的相关事宜与您联系。如需了解详情,请参阅将 API 密钥与 Maps Static API 搭配使用
  • signature推荐)是一种数字签名,用于验证所有使用您的 API 密钥生成请求的网站是否有权执行此操作。没有数字签名的请求可能会失败。如需了解详情,请参阅使用数字签名

网址大小限制

Maps Static API 网址的长度不得超过 8192 个字符。在实践中,除非您要生成具有大量标记和路径的复杂地图,否则可能就不需要超过这一时间的网址。

参数使用

Maps Static API 相对易于使用,因为它仅包含一个参数化网址。本部分介绍了如何使用这些参数构建网址。

指定位置

Maps Static API 必须能够准确标识地图上的位置,以便将地图放置于正确的位置上(使用 center 参数)和/或将任何可选地标放置到地图的相应位置上(使用 markers 参数)。Maps Static API 使用数字(纬度和经度值)或字符串(地址)来指定这些位置。这些值标识经过地理编码的位置。

多个参数(例如 markerspath 参数)采用多个位置。在这些情况下,这些位置之间用竖线字符 (|) 进行分隔。

纬度和经度

纬度和经度使用逗号分隔的文本字符串中的数字定义,可精确到小数点后 6 位。例如,“40.714728,-73.998672”是有效的地理编码值。小数点后 6 位之外的精度会被忽略。

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

英国格林威治

纬度和经度值必须对应于地球表面的有效位置。纬度可采用 -9090 之间的任何值,而经度可采用 -180180 之间的任何值。如果您指定的纬度或经度值无效,您的请求将作为错误请求被拒绝。

地址数

大多数人并不使用纬度和经度,而是使用地址来表示位置。将地址转换为地理地点的过程称为“地理编码”,如果您提供有效的地址,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 像素的形式返回。在 LCD 计算机显示器(通常为每英寸 100 像素 (ppi) 显示屏上),200x200 的地图在每个维度上约为 2 英寸。

不过,移动设备越来越多地使用像素密度超过 300ppi 的高分辨率屏幕,这些屏幕出现以下任一情况:

  • 将 200x200 像素图片的尺寸缩小到 0.7 英寸,导致标签和图标太小,以致无法阅读;或者
  • 缩放(缩放)图片以提高可辨度,从而产生模糊或像素化的图片。
太小 过于模糊

针对移动设备进行开发时,您可以使用 API 的 scale 参数返回可解决上述问题的更高分辨率地图图片。scale 值会与 size 相乘,可确定图片的实际输出大小(以像素为单位),而无需更改地图的覆盖区域。默认 scale 值为 1;接受的值包括 1 和 2。

例如,比例值 2 与未指定比例的请求会返回相同的地图覆盖区域,但每个尺寸的像素数是后者的两倍。这包括道路和标签,使其在高分辨率小尺寸屏幕上以及通过浏览器缩放时清晰可辨。

150x150 150x150 且 scale=2

此类图片在插入采用 CSS 高度和宽度的 imgdiv 标记后,也可在桌面浏览器中呈现良好的性能。浏览器会将图片缩小到正确的尺寸,而不会降低图片的质量。

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

  • 第一项请求的对象是大小为 100x100 且未指定比例值的图片。它可在桌面设备上正常显示,但在移动设备上因过小而无法辨认。
  • 第二项请求的对象是大小为前者两倍的地图。在桌面设备上,CSS 会将其放入指定的 100x100 img 元素中,但在缩小图片大小时,道路和标签变得过小。在移动设备上,图片的尺寸合适,但同样,道路和标签难以辨认。
  • 第三个请求针对的是使用 scale=2 的 100x100 地图。返回的图像有 200 像素的细节;桌面会完美地缩小图像,以便与原始的 100x100 请求无法区分,而移动浏览器则受益于 API 返回的额外分辨率。
图片请求
设备 100x100 200x200 100x100&scale=2
桌面设备

img 标记上的 height="100px"
width="100px"
高分辨率
(模拟)

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

图片格式

图片可以以多种常见的 Web 图形格式返回:GIFJPEGPNGformat 参数采用以下值之一:

  • png8png(默认)指定 8 位 PNG 格式。
  • png32 用于指定 32 位 PNG 格式。
  • gif 用于指定 GIF 格式。
  • jpg 用于指定 JPEG 压缩格式。
  • jpg-baseline,用于指定非渐进式 JPEG 压缩格式。

以下示例请求的是 gifpng 格式的地图:

  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

jpgjpg-baseline 通常可提供最小的图片,不过这是通过“有损”压缩来实现的,可能会降低图片。gifpng8png32 提供无损压缩。

大多数 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 参数的标记。tinysmall 标记无法显示字母数字字符。

标记缩放

scale 值乘以标记图像大小,即可生成标记的实际输出大小(以像素为单位)。默认缩放值为 1;可接受的值为 1、2 和 4。

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

标记位置

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

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

位置参数用于定义标记在地图上的位置。如果位置不在地图范围内,只要提供 centerzoom 参数,该标记就不会出现在构建的图像中。但是,如果没有提供这两个参数,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 参数定义了三个标记:一个标记为“S”的蓝色标记(位于 62.107733, -145.5419),一个绿色小标记位于“Delta Junction, AK”,另一个中等大小的黄色标记标有“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),或使用以下值之一进行预定义对齐:topbottomleftrightcentertoplefttoprightbottomleftbottomright。例如:

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 位十六进制值,那么最后 2 个字符用于指定 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 将按指定顺序沿这些点连接路径。每个 pathPoint 都由 pathDescriptor 表示,其中以 |(竖线)字符分隔。

以下示例定义了从纽约联合广场到纽约时报广场的不透明度为 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}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

阿拉斯加高速公路

与标准路径一样,如果将 fillcolor 参数传递给 path 参数,编码多段线路径也可以划分多边形区域。

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_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

坎布里奇地图

隐式定位地图

通常,您需要指定 centerzoom 网址参数才能定义生成地图的位置和缩放级别。不过,如果您提供 markerspathvisible 参数,则可以改为让 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)以及它们为何无法满足您的需求。
  3. 有关如何使用大尺寸图片的屏幕截图、模拟或示例。
  4. 估算的大型图片的每月用量。

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

我们可提供的尺寸上限为 2048 x 2048 像素。

问题排查和支持

如需详细了解如何使用 Maps Static API,请查看支持页面

出现问题时,Maps Static API 可能会发出错误或警告。您应特别注意是否有警告信息,如果您注意到地图中缺少内容。此外,最好在启动新应用前查看警告。请注意,这些警告可能不会立即显现,因为它们显示在 HTTP 标头中。如需了解详情,请参阅错误和警告指南。