嵌入地图

本指南介绍了如何将互动式地图嵌入到您的网页中。

创建 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 的 height 和 width 属性控制地图的大小，例如：

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

streetview模式

借助 Maps Embed API，您可以将街景图像显示为其覆盖区域内指定位置的全景交互式图片。还可提供用户贡献的照片球和街景特色收藏。

每张街景全景图均提供以单个位置为中心的 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)，或者添加 center 和 zoom 参数来限制搜索。

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

您可以使用以下参数：

参数 类型 说明 已接受的值
q 必需 定义搜索字词。 它可以包括地理限制，如 in+Seattle 或 near+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 地点 API 文档。

Maps Embed API 接受使用地点 ID 表示下列网址参数：

  • q
  • origin
  • destination
  • waypoints

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

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

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

    • default，使用默认街景来源；搜索范围不限于特定来源。
    • outdoor，仅搜索室外全景图片。室内藏馆不会显示在搜索结果中。请注意，指定位置可能不存在室外全景图片。另请注意，仅当能够确定位于室内还是室外的全景图片时，搜索才会返回这些全景图片。例如，不会返回 PhotoSphere，因为照片是在室内还是室外是未知的。