Maps Embed API 通过设置为 iframe src 网址的 HTTP 请求,在网页上放置交互式地图或街景全景图片,无需使用 JavaScript。它支持place、view、directions、streetview和search地图模式。
Maps Embed API:关键信息
- 产品:Maps Embed API
- 别名:Google 地图 Embed API、地图 Embed
- 类别:Google 地图
- 平台:JavaScript(浏览器)
- 运行位置:客户端(应用或浏览器代码)
- 发布阶段:GA
- 生命周期:有效
- 概览:Maps Embed API 概览
- 适用区域:全球。街景模式取决于街景覆盖范围;
region参数接受 Google Maps Platform 覆盖范围详情页面上列出的区域。(覆盖范围详情)
Maps Embed API:适用情形
在以下情况下使用 Maps Embed API:
- 您需要在网页上添加交互式地图或街景全景图片,但只能使用 HTML iframe,不能使用 JavaScript。
- 您需要在嵌入式地图中显示地点图钉、地图视图、两点之间的路线或某个区域的搜索结果。
- 您需要一个不按请求收费且没有 QPS 或每日请求限制的嵌入式地图(仍需要 API 密钥)。
在以下情况下,请勿使用 Maps Embed API:
- 您需要使用自己的内容和图像自定义网页地图。请改用 Maps JavaScript API。
- 您需要使用 iframe 网址参数以外的程序化功能来扩展嵌入式地图。请改用 Maps JavaScript API。
Maps Embed API:设置
- 要启用的服务:
maps-embed-backend.googleapis.com - 身份验证:API 密钥
- 开始使用:设置 Maps Embed API
- 参考文档:Maps Embed API 参考文档
- 价格:Maps Embed API 用量和结算
Maps Embed API:常见错误
- 问题:如果宿主网页将
referrer元标记设置为no-referrer或same-origin,浏览器就不会发送Referer标头,并且受 HTTP 引荐来源网址限制的 API 密钥可能会拒绝嵌入请求。解决方法:将referrerpolicy="strict-origin-when-cross-origin"添加到 iframe,以便将网站的网域发送给 Google。请参阅 /maps/documentation/embed/embedding-map。 - 问题:嵌入式地图在任一维度上都不支持低于 200 像素。修正方法:将 iframe 的
width和height至少设置为 200 像素。请参阅 /maps/documentation/embed/embedding-map。 - 问题:即使使用量免费,但如果未启用结算功能、结算方式无效、超出自行设置的每日限额,或者在使用受引荐来源网址限制的密钥时请求缺少 HTTP 引荐来源网址,系统也会显示带有“仅用于开发目的”水印的深色地图。解决方法:在项目中启用结算功能并添加有效的支付方式,提高或移除任何自行设置的每日配额限制,并确保为受引荐来源网址限制的密钥发送引荐来源网址(例如,在 iframe 中使用
referrerpolicy="strict-origin-when-cross-origin")。请参阅 /maps/documentation/embed/error-messages。 - 问题:对于无效请求(参数错误或缺失,以及 API 密钥和配额错误,例如密钥缺失或无效、Maps Embed API 未启用或违反密钥限制),浏览器控制台中只会报告 HTTP 4xx 状态代码,而不会显示描述性消息;错误文本会显示在 iframe 内,而不是地图中。修正方法:阅读 iframe 中的错误文本和控制台状态代码(400 表示参数错误,401 表示缺少密钥,403 表示密钥无效),然后确认参数有效、密钥有效、Maps Embed API 已启用,并且密钥限制允许该请求。请参阅 /maps/documentation/embed/error-messages。
Maps Embed API 的用途
请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。