嵌入地图

本指南介绍了如何在网页上嵌入互动式地图。

创建 Maps Embed API 网址

以下是加载 Maps Embed API 的示例网址:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

您需要在其中:

  • MAP_MODE 替换为地图模式
  • YOUR_API_KEY 替换为您的 API 密钥。如需了解详情,请参阅获取 API 密钥
  • PARAMETERS 替换为地图模式的必需参数和可选参数。

将网址添加到 iframe 中

如需在网页上使用 Maps Embed API,请将您构建的网址设置为 iframe src 属性的值。您可以使用 iframe 的 heightwidth 属性来控制地图的大小,例如:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

上面的 iframe 示例使用了其他属性:

  • allowfullscreen 属性,可让某些地图部分全屏显示。
  • frameborder="0"style="border:0" 属性,用于移除地图周围的标准 iframe 边框。
  • referrerpolicy="no-referrer-when-downgrade" 属性允许浏览器将完整网址作为 Referer 标头随请求发送,以便 API 密钥限制可以正常工作。

您可以根据自己网站的结构和设计来调整 iframe 的大小,但我们发现访客通常更容易与较大的地图互动。请注意,不支持任何尺寸小于 200 像素的嵌入式地图。

API 密钥限制

如果托管网站的 referrer 元标记设置为 no-referrersame-origin,浏览器将不会向 Google 发送 Referer 标头。这可能会导致您的 API 密钥限制拒绝请求。为使限制正常运行,如上例所示,请向 iframe 添加 referrerpolicy 属性,以明确允许将 Referer 标头发送到 Google。

地图上的广告

Maps Embed API 可包含地图上的广告。在任何给定地图中展示的广告格式和广告组均有可能发生更改,恕不另行通知。

选择地图模式

您可以在请求网址中指定要使用的以下地图模式之一:

  • place:在特定地点或地址(例如地标、商家、地理地图项或城镇)显示地图图钉。
  • view:返回不带标记或路线的地图。
  • directions:显示地图上两个或多个指定点之间的路径,以及距离和行程时间。
  • streetview:显示指定位置的交互式全景视图。
  • search:显示可见地图区域中的搜索结果。

place模式

以下网址使用 place 地图模式在埃菲尔铁塔显示地图标记:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

您可以使用以下参数:

参数 类型 说明 已接受的值
q 必需 定义地图标记位置。 经过网址转义的地点名称、地址、Plus 代码或地点 ID。 在对空格进行转义时,Maps Embed API 支持 +%20。例如,将“City Hall, New York, NY”转换为 City+Hall,New+York,NY,或将 Plus 代码“849VCWC8+R9”转换为 849VCWC8%2BR9
center 选填 定义地图视图的中心。 接受以英文逗号分隔的纬度和经度值;例如:37.4218,-122.0840
zoom 选填 设置地图的初始缩放级别。 值的范围为 0(全世界)到 21(个别建筑物)。上限可能因所选位置的可用地图数据而异。
maptype 选填 定义要加载的地图图块类型。 roadmap(默认)或 satellite
language 选填 定义界面元素以及在地图图块上显示标签时所用的语言。默认情况下,访问者看到的地图将以自己的语言显示。只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则将使用该图块集的默认语言。
region 选填 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符(非数字)Unicode 区域子标记的形式指定的区域代码,映射到熟悉的 ccTLD(“顶级域名”)双字符值。如需了解支持的地区,请参阅 Google Maps Platform 覆盖范围详细信息

view模式

以下示例使用 view 模式和可选的 maptype 参数显示地图的卫星视图:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

您可以使用以下参数:

参数 类型 说明 已接受的值
center 必需 定义地图视图的中心。 接受以英文逗号分隔的纬度和经度值;例如:37.4218,-122.0840
zoom 选填 设置地图的初始缩放级别。 值的范围为 0(全世界)到 21(个别建筑物)。上限可能因所选位置的可用地图数据而异。
maptype 选填 定义要加载的地图图块类型。 roadmap(默认)或 satellite
language 选填 定义界面元素以及在地图图块上显示标签时所用的语言。默认情况下,访问者看到的地图将以自己的语言显示。只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则将使用该图块集的默认语言。
region 选填 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符(非数字)Unicode 区域子标记的形式指定的区域代码,映射到熟悉的 ccTLD(“顶级域名”)双字符值。如需了解支持的地区,请参阅 Google Maps Platform 覆盖范围详细信息

directions模式

以下示例使用 directions 模式显示挪威奥斯洛和挪威泰勒马克之间的路径、距离和行程时间(避开收费站和高速公路)。

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

您可以使用以下参数:

参数 类型 说明 已接受的值
origin 必需 定义要显示路线的起点。 经过网址转义的地点名称、地址、Plus 代码、纬度/经度坐标或地点 ID。 在对空格进行转义时,Maps Embed API 支持 +%20。例如,将“City Hall, New York, NY”转换为 City+Hall,New+York,NY,或将 Plus 代码“849VCWC8+R9”转换为 849VCWC8%2BR9
destination 必需 定义路线的终点。 经过网址转义的地点名称、地址、Plus 代码、纬度/经度坐标或地点 ID。 在对空格进行转义时,Maps Embed API 支持 +%20。例如,将“City Hall, New York, NY”转换为 City+Hall,New+York,NY,或将 Plus 代码“849VCWC8+R9”转换为 849VCWC8%2BR9
waypoints 选填 指定一个或多个中转地点,以便在出发地和目的地之间规划路线。 地点名称、地址或地点 ID。 可以使用竖线字符 (|) 分隔地点(例如 Berlin,Germany|Paris,France),从而指定多个航点。您最多可以指定 20 个航点。
mode 选填 定义出行方式。如果未指定模式,Maps Embed API 会显示与指定路线最相关的一种或多种模式。 drivingwalking(首选步道和人行道,如有)、bicycling(采用自行车道和首选街道(如有)、transitflying
avoid 选填 指定要在路线中避开的地图项。请注意,这不会排除包含受限地图项的路线,而是会对结果设置偏向,以获得更有利的路线。 tollsferries 和/或 highways。 请使用竖线字符分隔多个值(例如 avoid=tolls|highways)。
units 选填 指定结果中显示距离时的测量方法、公制或英制。如果未指定 units,则查询中的 origin 国家/地区决定要使用的单位。 metricimperial
center 选填 定义地图视图的中心。 接受以英文逗号分隔的纬度和经度值;例如:37.4218,-122.0840
zoom 选填 设置地图的初始缩放级别。 值的范围为 0(全世界)到 21(个别建筑物)。上限可能因所选位置的可用地图数据而异。
maptype 选填 定义要加载的地图图块类型。 roadmap(默认)或 satellite
language 选填 定义界面元素以及在地图图块上显示标签时所用的语言。默认情况下,访问者看到的地图将以自己的语言显示。只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则将使用该图块集的默认语言。
region 选填 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符(非数字)Unicode 区域子标记的形式指定的区域代码,映射到熟悉的 ccTLD(“顶级域名”)双字符值。如需了解支持的地区,请参阅 Google Maps Platform 覆盖范围详细信息

streetview模式

借助 Maps Embed API,您可以从指定位置在整个覆盖区域以交互式全景图片的形式展示街景图像。另外,还提供用户提交的 360 度全景照片街景特别照片集

每张街景全景图片均提供以单个位置为中心的 360 度全景视图。图像包含 360 度水平视图(完整环绕一周)和 180 度垂直视图(从直上至直下)。streetview 模式提供了一个查看器,能够以镜头为中心将生成的全景图片渲染为一个球面。您可以通过操纵镜头来控制镜头的缩放级别和朝向。

请参阅以下 streetview 模式全景图片:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

以下网址参数之一是必需的:

  • location 接受逗号分隔值 (46.414382,10.013988) 形式的纬度和经度。API 将显示距离此地点最近的拍摄的全景图片。由于街景图像会定期刷新,并且系统每次拍摄照片的位置可能会略有差异,因此当图像更新时,您的位置可能会对应于不同的全景图片。

  • pano 是具体的全景图片 ID。如果您指定 pano,则还可以指定 location。仅当 API 找不到全景图片 ID 时,才会使用 location

以下网址参数为可选参数:

参数 类型 说明 已接受的值
heading 选填 以与北方所呈顺时针角度表示镜头的罗盘航向。 值(以度为单位,范围为 -180° 到 360°)
pitch 选填 指定镜头的向上或向下角度。正值表示相机向上倾斜,而负值则表示相机向下倾斜。默认倾斜度为 0°,根据拍摄图片时相机的位置来设置。因此,倾斜度为 0° 通常(但并不总是)是水平的。例如,在山上拍摄的图像可能会呈现出非水平的默认倾斜度。 值(以度为单位,范围为 -90° 到 90°)
fov 选填 决定了图片的水平视野。该值默认为 90°。在处理固定尺寸的视口时,可将视野视为缩放级别,数字越小表示缩放级别越高。 以度为单位的值,范围为 10° - 100°
center 选填 定义地图视图的中心。 接受以英文逗号分隔的纬度和经度值;例如:37.4218,-122.0840
zoom 选填 设置地图的初始缩放级别。 值的范围为 0(全世界)到 21(个别建筑物)。上限可能因所选位置的可用地图数据而异。
maptype 选填 定义要加载的地图图块类型。 roadmap(默认)或 satellite
language 选填 定义界面元素以及在地图图块上显示标签时所用的语言。默认情况下,访问者看到的地图将以自己的语言显示。只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则将使用该图块集的默认语言。
region 选填 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符(非数字)Unicode 区域子标记的形式指定的区域代码,映射到熟悉的 ccTLD(“顶级域名”)双字符值。如需了解支持的地区,请参阅 Google Maps Platform 覆盖范围详细信息

search模式

Search 模式会显示可见地图区域中的搜索结果。建议通过在搜索字词中包含位置 (record+stores+in+Seattle) 或添加 centerzoom 参数来限定搜索范围来定义搜索位置。

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

您可以使用以下参数:

参数 类型 说明 已接受的值
q 必需 定义搜索字词。 它可以包含地理位置限制,例如 in+Seattlenear+98033
center 选填 定义地图视图的中心。 接受以英文逗号分隔的纬度和经度值;例如:37.4218,-122.0840
zoom 选填 设置地图的初始缩放级别。 值的范围为 0(全世界)到 21(个别建筑物)。上限可能因所选位置的可用地图数据而异。
maptype 选填 定义要加载的地图图块类型。 roadmap(默认)或 satellite
language 选填 定义界面元素以及在地图图块上显示标签时所用的语言。默认情况下,访问者看到的地图将以自己的语言显示。只有部分国家/地区图块支持此参数;如果图块集不支持请求的特定语言,则将使用该图块集的默认语言。
region 选填 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符(非数字)Unicode 区域子标记的形式指定的区域代码,映射到熟悉的 ccTLD(“顶级域名”)双字符值。如需了解支持的地区,请参阅 Google Maps Platform 覆盖范围详细信息

地点 ID 参数

Maps Embed API 支持使用地点 ID,而不是提供地点名称或地址。地点 ID 是对地点进行唯一标识的可靠方式。有关详情,请参阅 Google Places API 文档

Maps Embed API 接受以下网址参数的地点 ID:

  • q
  • origin
  • destination
  • waypoints

如需使用地点 ID,您必须先添加前缀 place_id:。以下代码将纽约市政厅指定为路线请求的出发地:origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8

  • radius,用于设置以米为单位的半径,以指定要在指定的纬度和经度周围搜索全景图片。有效值为非负整数。默认值为 50。

  • source:将街景搜索范围限制为选定来源。有效值包括:

    • default,使用默认街景来源;搜索范围不限于特定来源。
    • outdoor,仅搜索室外全景图片。室内照片集不会显示在搜索结果中。请注意,指定位置可能不存在室外全景图片。另请注意,搜索只会返回能够确定是位于室内还是室外的全景图片。例如,系统不会返回 PhotoSphere,因为系统不知道它们是位于室内还是室外。