嵌入地图

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

创建 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 地图模式，在 Eiffel Tower：

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 之间的路径 以及避开收费站和高速公路的距离和行程时间。

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”更改为 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”更改为 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 度水平视图（完全环绕） 以及 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 Places API 文档。

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

  • q
  • origin
  • destination
  • waypoints

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

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

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

    • default 使用默认街景来源；搜索量是 不限于特定来源
    • outdoor，仅搜索室外全景图片。室内 集合未包含在搜索结果中。请注意，室外全景图片 可能不存在。另请注意 用于返回全景图片，以便可以确定这些全景图片是否位于室内 或室外。例如，由于 PhotoSpheres 未知， 无论是在室内还是室外。