嵌入地图

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

创建 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 可选 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符（非数字）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 必需 定义所显示路线的起点。 经过网址转义的地点名称、地址、加号代码、纬度/经度坐标或地点 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 可选 根据地缘政治敏感性定义要显示的相应边界和标签。 接受以双字符（非数字）Unicode 地区子标记的形式指定的地区代码，该子标记会映射到熟悉的 ccTLD（“顶级域名”）双字符值。如需了解支持的地区，请参阅 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，仅搜索室外全景图片。室内合集不会包含在搜索结果中。请注意，指定位置可能不存在室外全景图片。另请注意，搜索功能只会返回可确定其是在室内还是室外的全景图片。例如，系统不会返回全景照片，因为无法确定它们是在室内还是室外拍摄的。