嵌入地图

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

创建 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 的大小，使其适合自己网站的结构和设计，但据我们发现，访客通常认为地图越大，越便于交互。请注意，在 维度。

API 密钥限制

如果托管网站的 referrer 元标记设置为 no-referrer 或 same-origin，浏览器将不会向 Google 发送 Referer 标头。这个 可能会导致您的 API 密钥限制 拒绝这些请求为使限制有效，请将 referrerpolicy 属性添加到 iframe（如上例所示），以显式 允许将 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 模式显示挪威 Oslow 和 Telemark 之间的路线、距离和避开收费站和高速公路的旅行时间。

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，或 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 将为指定路线显示一个或多个最相关的模式。 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 找不到全景图片时，才会使用 location ID。

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

参数 类型 说明 已接受的值
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，仅搜索室外全景图片。室内合集不会包含在搜索结果中。请注意，指定位置可能不存在室外全景图片。另请注意，搜索功能只会返回可确定其是在室内还是室外的全景图片。例如，系统不会返回全景照片，因为无法确定它们是在室内还是室外拍摄的。