本指南介绍了如何将互动式地图嵌入您的网页。
创建 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 属性（如上例所示），以允许向 Google 明确发送 Referer 标头。
地图上显示的广告
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，或将代码“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
¢er=-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 代码、纬度/经度坐标或地点 ID。
对空格进行转义时，Maps Embed API 支持 + 和 %20。例如，将“City Hall, New York, NY”转换为 City+Hall,New+York,NY，或将代码“849VCWC8+R9”转换为 849VCWC8%2BR9。 |
destination |
必需 | 定义路线的终点。 | 网址转义地点的名称、地址以及 Plus 代码、纬度/经度坐标或地点 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 度视图。图像包含 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：
qorigindestinationwaypoints
若要使用地点 ID，您必须先添加前缀 place_id:。以下代码将纽约市政厅指定为路线请求的来源：origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8。
radius，用于设置半径，以米为单位，以指定的纬度和经度为中心按该半径搜索全景图片。有效值为非负整数。默认值为 50。source，可将街景搜索限制为所选来源。有效值包括：default，使用默认街景来源；搜索不限于特定来源。outdoor，将搜索范围限定为户外集合。室内集合不会显示在搜索结果中。请注意，指定位置可能不存在户外全景图片。另请注意，搜索仅会返回有可能确定是室内还是室外的全景图片。例如，系统不会返回 PhotoSphere，因为它未知是室内还是室外。