嵌入地图

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

创建 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 密钥限制拒绝这些请求。为了使此限制正常运行，请向 iframe 添加 referrerpolicy 属性（如上例所示），以明确允许将 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，或将“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，或 Plus 代码“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 度水平视图（完整环绕）和 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，仅搜索室外全景图片。室内合集不会包含在搜索结果中。请注意，室外全景图片 可能不存在。另请注意 用于返回全景图片，以便可以确定这些全景图片是否位于室内 或室外。例如，系统不会返回全景照片，因为无法确定它们是在室内还是室外拍摄的。