Maps Embed API 快速参考

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 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 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Maps Embed API:路线和路线规划

Maps Embed API:地图

Maps Embed API:地点

Maps Embed API:街景