嵌入地图

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

创建 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。

选择地图模式

您可以在请求网址中指定以下任一地图模式：

• 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 是一种稳定且唯一标识地点的方式。如需了解详情，请参阅 Google Places API 文档。

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

• q
• origin
• destination
• waypoints

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

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

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

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