本指南介绍了如何将互动式地图嵌入到网页中。
创建 Maps Embed API 网址
以下是加载 Maps Embed API 的示例网址:
https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&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
¢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
模式显示 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
,仅搜索室外全景图片。室内合集不会包含在搜索结果中。请注意,室外全景图片 可能不存在。另请注意 用于返回全景图片,以便可以确定这些全景图片是否位于室内 或室外。例如,系统不会返回全景照片,因为无法确定它们是在室内还是室外拍摄的。