My favorites ▼ | 中文(简体) ▼ | Sign in

  • Google 静态地图 API

    • 开发人员指南

Google 地图 API 专业版

包含企业许可和支持

静态地图 API 开发人员指南

欢迎阅读 Google 静态地图 API 的开发人员文档！通过 Google 静态地图 API，您不需要使用 JavaScript 或加载任何动态页面，便可将 Google 地图图像嵌入到自己的网页中。Google 静态地图服务会根据通过标准 HTTP 请求发送的网址参数来创建您的地图，并将地图以您可以在网页上显示的图像形式返回。

Google 静态地图 API 需要地图 API 密钥。如果尚未注册地图 API 密钥，请注册一个免费的 API 密钥。

新！Google 静态地图 API 现在具有卫星和地形图块功能！

快速示例

以下示例包含静态地图图像的网址，如下所示：

# Note that this URL wraps at the '\' character.
# You can copy the URL from the image below, however.
# For clarity, we don't write the actual API key in use.
#
http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=14&size=512x512&maptype=mobile\
&markers=39.949328,116.3875,blues%7C39.949328,116.3775,greeng%7C39.943028,116.3975,redc\
&key=MAPS_API_KEY&sensor=false

下曼哈顿区的景点

请注意，您无需进行任何“特殊”操作便可在地图上显示此图像。不需要 JavaScript。只需创建一个网址并将其放入 <img> 标签中。您可以将 Google 静态地图放在可放置图像的网页上的任何位置。

目录

  1. 受众
  2. 使用限制
  3. 概览
  4. 网址参数
  5. 参数的用法
  6. 更多信息

读者

本文档适用于希望在网页中包含 Google 静态地图 API 图像的网站和手机开发人员。它对使用有关可用参数的 API 和参考材料进行了介绍。

使用限制

使用静态地图 API 需要注册一个免费的地图 API 密钥。地图 API 密钥允许您使用静态地图 API 和标准地图 API。

使用 Google 静态地图 API 还需遵从每位查看者每天的唯一（不同）图像请求不超过 1000 次的查询限制。由于此限制是按“查看者”而非“关键字”制订的配额，因此大多数开发人员并不需要为超过其配额而担心。此外，请注意，一般情况下，对相同图像的请求，除了第一次，其他请求并不计入该限制。

如果用户超出以上的禁止限制，则将显示以下图像，指示超出了配额：

强制执行此限制是为了防止滥用和/或重复使用静态地图 API。以后可能对此限制进行更改，而无需另行通知。如果超过了 24 小时的限制或滥用此服务，静态地图 API 会临时停止运行。如果您继续无视这个限制，将会阻止您对静态地图 API 的访问。

概述

Google 静态地图 API 通过网址返回图像（GIF、PNG 或 JPEG）来响应 HTTP 请求。您可以为每个请求指定地图的位置、图像的大小、缩放级别、地图的类型以及可选标记在地图各个位置上的放置。此外，您还可以使用字母字符为您的标记制作标签，以便在“关键字”中引用这些标记。

将静态地图 API 图像嵌入<img> 标签的 src 属性内的网页上。当显示网页时，浏览器从静态地图 API 请求图像，并显示在图像位置内。

本文档介绍了静态地图 API 网址的所需格式和可用参数。还提供了一些指定网址的提示和技巧。

网址参数

Google 静态地图 API 网址必须为以下形式：

http://ditu.google.cn/staticmap?parameters

有些参数是必需的，而有些参数则是可选的。根据 HTTP 请求的标准，所有参数均使用 & (&) 字符分隔。参数列表及参数的可能值枚举如下。

静态地图 API 使用以下网址参数定义地图图像：

  • center（不显示标记时为必需）定义地图的中心，到地图各边缘的距离相等。此参数采用一个用逗号分隔的 {经度,纬度} 对（例如，"40.714728,-73.998672"）来标识地球表面的唯一位置。有关详细信息，请参见下面的经度和纬度。
  • zoom （不显示标记时为必需）定义地图的缩放级别，缩放级别确定地图放大的级别。此参数根据所需的区域缩放级别来采用数字值。有关更多信息，请参见下面的缩放级别。
  • size（必需）定义地图图像的矩形尺寸。此参数采用 valuexvalue 形式的字符串，其中先表示水平像素，再表示垂直像素。例如，500x400 定义了一幅宽为 500 像素、高为 400 像素的地图。如果您创建一幅宽为 100 像素或更小的静态地图，“由 Google 强力驱动”徽标的大小会自动缩小。
  • format（可选）定义生成的图像的格式。默认情况下，静态地图 API 创建 GIF 图像。有若干种可能的格式，包括 GIF、JPEG 和 PNG 类型。使用哪种格式取决于您想要显示图像的方式。JPEG 通常提供更大程度的压缩，而 GIF 和 PNG 提供更多细节。有关详细信息，请参见图像格式。
  • maptype（可选）定义要构造的地图类型。有若干种可能的地图类型值，包括 satellite、terrain、hybrid 和 mobile。有关更多信息，请参见下面的静态地图 API 地图类型。
  • markers（可选）定义要在指定位置附加到图像的一个或多个标记。此参数采用由管道字符 (|) 分隔的标记定义的字符串。请注意，如果为地图提供标记，就无需指定（通常情况下必需的）center 和 zoom 参数。有关更多信息，请参见下面的静态地图标记。
  • path（可选）定义要在指定位置覆盖在图像上的单条路径，其由两个或两个以上的连接点组成。此参数采用由管道字符 (|) 分隔的点定义的字符串。请注意，如果为地图提供标记，就无需指定（通常情况下必需的）center 和 zoom 参数。有关详细信息，请参见下面的静态地图路径。
  • span（可选）定义地图图像的最小“视口”，以成对的纬度和经度表示。静态地图服务采用该值并生成适当缩放级别的地图，以包含距地图中心点的所提供全部的 span 值。请注意，生成的地图可能包含在经度或纬度上更大的边界，这取决于地图的矩形尺寸。如果指定了 zoom，则会忽略 span。
  • frame（可选）指定生成的图像应由蓝色的边框框起来。框架由 5 像素宽，不透明度为 55% 的蓝色边框组成。
  • hl（可选）定义用于在地图图块上显示标签的语言。请注意，该参数仅支持部分国家/地区图块；如果请求的指定语言不支持图块集，则将为该图块集使用默认的语言。
  • key（必需）标识生成此网址请求的域的地图API 密钥。如果没有地图 API 密钥，可以注册一个免费的地图 API 密钥。
  • sensor（必需）指定请求静态地图的应用程序是否使用传感器来确定用户的位置。对于所有静态地图请求，此参数都是必需的。有关详细信息，请参见下面的传感器。

参数的用法

静态地图 API 相对来说易于使用，因为它只包含一个参数网址。此部分介绍怎样使用这些参数构造您的网址。

指定位置

静态地图 API 必须能够精确标识地图上的位置，目的在于使地图处于正确的位置（使用 center 参数）和/或将任何可选地标放置到地图的各个位置上（使用·markers·参数）。静态地图 API 使用经纬度值指定这些位置。这些值共同标识“地址解析”位置。

如果您的设备使用“传感器”（例如 GPS 设备）来确定某个设备或用户的位置，您还必须在您的静态地图 API 请求网址内传递 sensor=true。如果您的应用程序不使用传感器，则传递 sensor=false。

经度和纬度

使用逗号分隔的文本字符串内的数字定义经度和纬度，精确到 6 位小数。例如，“40.714728，-73.998672”是有效的地址解析值。精确到 6 位小数之后的部分将被忽略。

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

英国格林威治

经纬度值必须与地球表面的有效位置对应。纬度可以采用 -90 和 90 之间的任意值，而经度值则可采用 -180 和 180 之间的任意值。如果指定了无效的纬度或经度值，您的请求将作为错误请求被拒绝。

地址解析

许多人不使用经度和纬度，而是使用“地址”来表示位置。将地址转换为地理点的过程称为“地址解析”，将在 Google 地图 API 服务部分中详细讨论。请注意，要直接使用地址解析服务，需要使用地图 API 密钥。

除了这个地址解析服务之外，您也可以使用其他服务（包括 Google 地图本身）来获取经地址解析后的经纬度值。例如，您可以将某个地址输入到 Google 地图，并通过单击地图右上方的链接到该页面来确定其经地址解析后的位置。将显示一个弹出式对话框，对话框内可复制的网址。如果将该网址复制到浏览器中，您便可以查找 ll 参数中包含的地址解析值。

缩放级别

Google 地图上的地图具有整数“缩放级别”，可定义当前视图的分辨率。普通地图视图中，可以使用 0（最低缩放级别，在地图上可以看到整个世界）到 19（最高缩放级别，可以看到每个建筑物）之间的缩放级别。

Google 地图将缩放级别 0 设为包含整个地球。随后的每个缩放级别在水平和垂直尺寸上使精确度加倍。Google 地图 API 文档中提供了有关怎样执行此操作的详细信息。

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

如果发送了并不存在任何地图图块的缩放级别请求，静态地图 API 将转而返回黑色图像。

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

http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=MAPS_API_KEY&sensor=true_or_false

曼哈顿远景  曼哈顿近景

图像大小

可以检索的最大图像大小为 640 x 640 像素。size 参数采用具有两个值的字符串，这两个值由 x 字符分隔。640x640 是所允许的最大图像大小。请注意，center 参数与 size 参数相结合可隐式定义地图图像的覆盖区域。

下面的示例请求地球赤道上的某个“块”（缩放级别为 1）：

http://ditu.google.cn/staticmap?center=0,0&zoom=1&size=400x50&key=MAPS_API_KEY&sensor=true_or_false

赤道

以下示例请求 100 x 100 像素大小的小型地图，以相同的区域为中心。请注意较小的 Google 徽标：

小型赤道地图

视口

图像可能通过传递 span 参数指定一个“视口”（按纬度和经度值定义，以度为单位）来显示提供的中心点周围的地区。以这种方式定义最大视口免去了指定确切缩放级别的必要。静态地图服务将 span 参数与 size 参数配合使用来构建适当缩放级别的地图，其中至少包括指定的视口限制。

以下示例请求一个方形地图，以 0 度经度和 0 度纬度为中心，宽度和高度为 20 度：

http://ditu.google.cn/staticmap?center=0,0&span=20,20&size=512x512&key=MAPS_API_KEY&sensor=true_or_false

赤道方形地图

以下示例请求一个以曼哈顿为中心的地图，在两个方向显示 1 度的弧度。请注意，因为该地图水平形成，在水平方向扩展 4 度，因此可以在垂直方向最少扩展 1 度。

http://ditu.google.cn/staticmap?center=40.714728,-73.998672&span=1,1&size=512x128&key=MAPS_API_KEY&sensor=true_or_false

纽约，所有边 1 度

图像格式

可以以若干种常见网络图形格式返回图像：GIF、JPEG 和 PNG。format 参数采用以下值之一：

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

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

大多数 JPEG 图像都是渐进式，这意味着它们先加载“较粗糙的”图像，再随着更多数据的传入而优化图像分辨率。这使图像在网页中能够迅速加载，是当前最普及的 JPEG 应用。但是，JPEG 的部分使用（尤其是打印）要求非渐进式（基线）图像。在这种情况下，您可能想使用非渐进式的 jpg-baseline 格式。

地图类型

Google 静态地图 API 以若干种格式创建地图，如下所列：

  • roadmap（默认）指定标准路线图图像，如 Google 地图网站通常所示。如果未指定 maptype 值，默认情况下，静态地图 API 会使用 roadmap 图块。
  • mobile 指定移动设备的路线图地图图像，它包含更多的特征和文本字体，从而能够以高分辨率在移动设备的小屏幕上方便地进行查看。
  • satellite 指定卫星图像。
  • terrain 指定自然地形地图图像，显示地形和植被。
  • hybrid 指定卫星和路线图的混合图像，在卫星图像上显示主要街道和地址名称的透明层。

您可以在以下代码示例中查看路线图和移动设备这两种类型之间的区别。请注意，这些地图也有 frame=true。

http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=MAPS_API_KEY&sensor=true_or_false
http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=mobile&key=MAPS_API_KEY&sensor=true_or_false

曼哈顿常规地图  曼哈顿移动设备地图

以下示例显示了卫星地图类型和地形地图类型：

http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=MAPS_API_KEY&sensor=true_or_false
http://ditu.google.cn/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=MAPS_API_KEY&sensor=true_or_false

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

标记

markers 参数定义要添加到地图图像中的一个或多个标记的集合。此参数是一个由赋值集合定义的多达 50 个标记的列表：

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|... 等。

请注意，标记描述符使用管道字符 (|) 相互隔开。（注意：如果正在对网址进行编码，管道字符在 ASCII 中也显示为 %7C。）

标记描述符

每个标记描述符都包含一个字符串，用于定义放置标记的位置和显示标记时使用的可视属性。这些字符串包含以下变量值：

  • {latitude}（必需）指定纬度值，精确到 6 位小数。
  • {longitude}（必需）指定经度值，精确到 6 位小数。
  • {size}（可选）指定集合 {tiny, mid, small} 中的标记大小。如果未设置 size 参数，标记将以其默认（常规）大小显示。
  • {color}（可选）指定集合 {black, brown, green, purple, yellow, blue, gray, orange, red, white} 中的一种颜色。
  • {alphanumeric-character}（可选）指定集合 {a-z, 0-9} 中的一个小写字母数字字符。请注意，显示 alphanumeric-character 参数时仅能使用默认和 mid 大小的标记。tiny 和 small 标记无法显示字母数字字符。

纬度和经度值定义标记在地图上的位置。如果位置在地图之外，该标记将不会显示在构建的图像上。

大小、颜色和字母数字字符值可以定义标记的可视外观。如果未指定大小值，标记会以其默认（常规）大小显示。此外，只有常规大小的标记才能显示字母数字字符。如果未指定值（或指定了错误的值），则标记会显示为默认的带点红色标记。

示例标记声明的格式为 {latitude},{longitude},{size}{color}{alphanumeric-character}。请特别注意，字符串的大小、颜色和字母数字字符值不用逗号隔开。样本标记声明如下所示。

markers=39.949328,116.3875,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc&key=MAPS_API_KEY&sensor=true_or_false

此 markers 参数定义三个标记（用“|”字符分隔）：40.702147,-74.015794 处标为“S”的一个蓝色标记，40.711614,-74.012318 处的一个小型绿色标记，以及 40.713504,-74.005607（市政厅）处标为“C”的一个中等大小红色标记。以下示例中显示了这些标记：

下曼哈顿区的景点

使用标记隐式定位地图

通常，您需要指定 center 和 zoom 网址参数来定义生成的地图的位置和缩放级别。但是，如果提供了 markers 参数，您也可以改用静态地图 API 来隐式确定正确的中心和缩放级别，具体取决于对这些标记位置的估算。

如果提供两个或两个以上的标记，静态地图 API 将确定适当的中心和缩放级别，从而提供足够的边距以显示 markers 参数中包含的标记。下面的示例包含与上面显示的标记相同的标记，但删除了 center 和 zoom 参数，使地图中心更接近两个目标标记的位置。

隐式定位

静态地图路径

path 参数定义要在地图图像上覆盖的一条或多条路径的集合。此参数是一个由赋值集合定义的路径列表：

path=pathColorType:pathColorValue,weight:pathWeight|pathPoint1|pathPoint2|pathPoint3|... 等。

请注意，路径点使用管道字符 (|) 相互隔开。（如果对网址进行编码，管道字符在 ASCII 中也显示为 %7C。）

路径属性

每个 path 参数的开头都可能是指定路径属性的可选字符串，由“pathColorType”和该类型的值组成（使用冒号分隔）。如果需要默认的路径属性，可能忽略路径描述符中的路径属性前缀；在本例中，路径描述符的第一个参数描述路径声明中的第一个点。（请参见下面的路径点。）

有两种可能的“pathColorType”：

  • rgb 指定标准的 RGB 颜色方案，使用 0xffffff 形式的 24 位十六进制值颜色值作为“pathColorValue”。rgb 路径的默认不透明度为 50%。
  • rgba 指定 0xffffffff 形式的 32 位十六进制颜色值作为“pathColorValue”，其中第四个字节（最后两个字符）指定“alpha 通道”不透明度。使用 rgba 使您可以更改您创建的任意路径的不透明度。

除了颜色，weight 还指定给定路线的粗细（以像素为单位）。

部分示例路径定义显示如下：

  • 蓝色细线，50% 不透明度：path=rgb:0x0000ff,weight:1
  • 红色实线：path=rgba:0xff0000ff,weight:5
  • 黑色粗实线：path=rgba:0xffffffff,weight:10

路径描述符中的具体路径属性为可选。如果需要默认属性，您可以跳过定义路径属性；在这种情况下，路径描述符的第一个“参数”将由第一个声明点组成。

路径点

为了绘制路径，path 参数也必须传递两个或两个以上的点。Google 静态地图 API 随后将沿着这些点按指定顺序连接路径。每个“pathPoint”都以“pathDescriptor”表示，由 |（管道）字符隔开。和标记一样，Google 静态地图 API 会根据提供的路径的隐式定位来尝试确定地图的默认中心和缩放。当前，对于任何给定路径都有 100 点的限制。

下面的示例定义了一个从纽约联合广场到时代广场的蓝色路径，默认不透明度为 50%。请注意，我们不需要提供 center 或 zoom 参数。

从联合广场到时代广场的路径

具体 path 参数如下所示：

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

下面的示例定义了相同的路径，即定义不透明度为 100% 的红色实线：

从联合广场到时代广场的路径

具体 path 参数如下所示：

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

更多信息

如果“编码”的概念使您感到头痛，Google 静态地图向导提供了一种 UI 引导的简单方法，能够通过简单的 UI 界面生成静态地图。

有关使用静态地图 API 或其他 Google 地图 API 产品的更多信息，请务必参见地图 API Google 网上论坛。