一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Static Maps API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Static Maps API
  3. 创建相应密钥
继续

Google 静态地图开发者指南

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

:Google Static Maps API 使用限制发生了变化。您可以通过创建 API 密钥并将其加入请求在 Google API 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 属性内,或其他编程语言的等效属性内。如果在基于网络的应用(如浏览器)以外使用 Google Static Maps API 图像,则必须加入一个链接,该链接须指向网络浏览器或原生 Google 地图应用中显示的位置。(Google Maps APIs Premium Plan 用户不受此要求约束。)请参阅 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

无论使用 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。可接受的值为 244 只适用于 Google Maps APIs Premium Plan客户。)如需了解详细信息,请参阅地图比例值
  • format选填项)定义所生成图像的格式。默认情况下,Google Static Maps API 创建 PNG 图像。有几种格式可以使用,其中包括 GIF、JPEG 和 PNG 类型。您使用哪一种格式取决于您打算以何种方式呈现图像。JPEG 压缩率通常较高,而 GIF 和 PNG 更精细。如需了解详细信息,请参阅图像格式
  • maptype选填项)定义要构建的地图类型。可接受的 maptype 值有若干个,其中包括 roadmapsatellitehybridterrain。如需了解详细信息,请参阅下文的 Google Static Maps API 地图类型
  • 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 API Console 中监控您的应用的 API 使用情况,能够获取大量的每日免费配额,并确保 Google 可以在必要时就应用的相关事宜与您联系。如需了解详细信息,请参阅获取密钥和签名
  • signature推荐项)是一种数字签名,用于验证任何使用您的 API 密钥生成请求的网站都获得了相应授权。注:如果启用收费,则必须提供数字签名。如果超过地图加载的每日免费限额,当天剩余时间内的额外地图加载将被收取费用。不包含数字签名的可收费地图加载将会失败。如需了解详细信息,请参阅获取密钥和签名

注:Google Maps APIs Premium Plan 客户可以在 Static Maps 请求中使用 API 密钥和数字签名,或者有效的客户端 ID 和数字签名。获取有关 Premium Plan 客户身份验证参数的更多信息。

“之前”已有 Google Maps APIs for Work 许可证的客户必须在其请求中附带有效的 clientsignature 参数而不是 key。如需了解详细信息,请参阅“获取密钥和签名”页面的客户端 ID 和签名部分。

URL 大小限制

Google Static Maps API 网址大小被限制为 8192 个字符。在实践中,除非您需要制作包含大量标记和路径的复杂地图,否则多半不需要长度超过该限值的 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 的值,使地图以格林威治为中心:

英国格林威治

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

地址

大多数人不会使用纬度和经度进行交流,他们使用地址来表示位置。将地址转换为地理点的过程称为地理编码,如果您提供有效的地址,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 返回的地图将以该位置可达到的最大缩放比例呈现。

下面的列表显示了您在每个缩放比例下会看到的大致细节级别:

  • 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
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 APIs Premium Plan 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 APIs Premium Plan 客户] 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=1scale=2,便可利用 scale 参数轻松地为标准分辨率屏幕请求地图图像,为高分辨率屏幕请求匹配的地图。

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

图像格式

可以下面这几种常见的 Web 图形格式返回图像:GIFJPEGPNGformat 参数取下列值之一:

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

jpgjpg-baseline 通常可提供最小的图像尺寸,但这是通过可能降低图像质量的“有损”压缩实现的。gifpng8png32 提供无损压缩。

大多数 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

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

样式化地图

请参阅样式化地图指南。

标记

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

:您可能想使用自己的自定义图标来替代这些标记。(如需了解详细信息,请参阅下文的自定义图标。)

标记位置

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

位置参数定义标记在地图上的位置。如果位置不在地图上,该标记将不会出现在构建的图像中,前提是提供了 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。

icon 参数必须使用 URL 指定(应接受 URL 编码)。您可以使用通过网址缩短服务创建的网址,例如 https://goo.gl。大多数 URL 缩短服务都具有自动为 URL 编码的优点。图标尺寸上限为 4096 像素(方形图像上限为 64x64 像素),Google Static Maps API 服务允许每次最多请求五个唯一的自定义图标。请注意,这些唯一图标均可在 Google Static Maps API 内多次使用。

自定义图标的锚点为图像的底部中心。

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

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

曼哈顿咖啡店

注:以上的多层转义可能令人迷惑。Google Chart API 使用管道符号 (|) 来分隔其 URL 参数内的字符串。由于该字符在网址内不合法(请参阅上文的),因此在创建完全有效的图表网址时,会将其转义为 %7C。现在,结果以字符串形式嵌入 icon 规范内,但它包含 % 字符(来自上面提及的 %7C),该字符无法以数据形式直接包括在网址内,必须转义为 %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:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

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

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

Google Static Maps API 路径

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

坎布里奇地图

隐式地图定位

正常情况下,您需要指定 centerzoom 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 参数,以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。

发送以下问题的反馈:

此网页
Google Static Maps API
需要帮助?请访问我们的支持页面