嵌入地图

本指南介绍了如何在网页上嵌入互动式地图。

创建 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="strict-origin-when-cross-origin"
  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="strict-origin-when-cross-origin" 属性可确保浏览器将您网站的网域作为 Referer 标头发送给 Google。这样，API 密钥限制便可以验证请求，同时让您的特定网页路径保持私密。

您可以调整 iframe 的大小，使其适合您自己网站的结构和设计，但我们发现，访问者通常更容易与较大的地图进行互动。请注意，嵌入式地图在任一维度上的尺寸均不得小于 200 像素。

引荐来源网址信息和 API 密钥限制

如果托管网站的 referrer 元标记设置为 no-referrer 或 same-origin，浏览器将不会向 Google 发送 Referer 标头。这可能会导致您的 API 密钥限制拒绝请求。为使限制正常发挥作用，请向 iframe 添加 referrerpolicy 属性（如上例所示），以明确允许将 Referer 标头发送到 Google。

• strict-origin-when-cross-origin（推荐）：仅向 Google 发送您的基本网域（例如 https://example.com/）。这样可以确保您的特定网页路径不公开，同时仍允许 API 密钥限制发挥作用。
• no-referrer-when-downgrade（旧版）：发送整个网址，包括特定网页路径和查询参数（例如 https://example.com/contact?user=123）。

详细了解 Referrer-Policy 标头。

选择地图模式

您可以在请求网址中指定要使用的以下地图模式之一：

• 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，或将 Plus Code“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	必需	定义显示路线的起点。	经过网址转义的地点名称、地址、Plus Code、纬度/经度坐标或地点 ID。 Maps Embed API 在对空格进行转义时，同时支持 + 和 %20。例如，将“City Hall, New York, NY”转换为 City+Hall,New+York,NY，或将 Plus Code“849VCWC8+R9”转换为 849VCWC8%2BR9。
destination	必需	定义路线的终点。	经过网址转义的地点名称、地址、Plus Code、纬度/经度坐标或地点 ID。 Maps Embed API 在对空格进行转义时，同时支持 + 和 %20。例如，将“City Hall, New York, NY”转换为 City+Hall,New+York,NY，或将 Plus Code“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 是唯一标识地点的稳定方式。如需了解详情，请参阅 Places API（新版）文档。

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

• q
• origin
• destination
• waypoints

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

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

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

  • default，使用默认街景来源；搜索范围不限于特定来源。
  • outdoor，仅搜索室外全景图片。室内合集不会包含在搜索结果中。请注意，指定位置可能不存在室外全景图片。另请注意，搜索只会返回可以确定是室内还是室外的全景图片。例如，系统不会返回 PhotoSphere，因为无法确定它们是在室内还是室外。