Google Maps Platform 常见问题解答

开始使用

了解服务条款

用量限额和结算

使用 Google Maps Platform

错误和问题排查

Google Maps Platform 服务

Maps JavaScript API

Google Maps SDK for iOS

Google Maps SDK for Android

网址签名

开始使用

什么是 Google Maps Platform?

Google Maps Platform 是一组 API 和 SDK,可让开发者将 Google 地图嵌入到移动应用和网页中,或从 Google 地图检索数据。它提供多种产品和服务。您可以根据需要使用以下任一 API 和 SDK,或组合使用 API 和 SDK。

地图:

路线:

地点:

环境:

如何开始使用 Google Maps Platform?

请参阅 Google Maps Platform 使用入门

我需要哪一个 API?

如需了解如何根据功能要求找到合适的 API,请查看 API 选择器

如何开始在我的网站上使用 API?

请参阅您感兴趣的特定 API 或 SDK 对应的概览、开发者指南和入门指南。例如,查看 Maps SDK for AndroidMaps JavaScript API 的指南。

Google Maps Platform 覆盖哪些国家/地区?

Google 地图团队一直在不断推出新的地图数据,逐渐扩大在全球的覆盖范围。如需了解最新的覆盖范围信息,请参阅 Google 地图覆盖范围数据。您可以使用页面顶部的过滤框来过滤数据。请注意,覆盖范围数据可能会随与数据提供商签订的许可协议的更改而发生变化。

另请参阅:

如果不使用 Google Maps Platform 产品,我能否将 Google 地图嵌入我的网站?

能。Google 地图现在提供了一项功能,无需编写任何代码或使用 Google Maps Platform,即可将您正在查看的地图嵌入您的网站或博客中。如需了解详情,请点击此处

如何在移动设备上提供地图应用?

如需在 Android 应用中集成地图,请使用 Maps SDK for Android

如需在 iOS 原生应用中集成地图,请使用 Maps SDK for iOS

Maps JavaScript API 专为满足移动设备的需求而开发,适用于同时面向桌面设备和其他设备(此类设备应带有包含完整 JavaScript 实现的网络浏览器,例如 Apple iPhone)的浏览器应用。

如果应用面向的设备不适合使用 Maps JavaScript API,请使用 Maps Static API,该 API 可用于提供 GIF、JPG 和 PNG 格式的地图图片,包括标记和多段线。请注意,如需在基于浏览器的应用以外使用 Maps Static API,您需要将相应地图图片关联到 Google 地图。

Maps JavaScript API 和 Maps Embed API 支持哪些网络浏览器?

Maps JavaScript API 和 Maps Embed API 支持以下网络浏览器:

桌面设备
  • Microsoft Edge 的现行版本 (Windows),不包括 IE 模式。
  • Firefox 的两个最新主要稳定版本(Windows、macOS、Linux)。
  • Chrome 的两个最新主要稳定版本(Windows、macOS、Linux)。
  • Safari 的两个最新主要稳定版本 (macOS)。
Android
  • Chrome 的现行版本 (Android 4.1+)。
  • Chrome WebView (Android 4.4+)。
iOS
  • Mobile Safari(iOS 现行版本和以往主要版本)。
  • UIWebView 和 WKWebView(iOS 现行版本和以往主要版本)。
  • Chrome 的现行版本 (iOS)。
我能否通过 Maps JavaScript API 输出地图?

不支持通过 Maps JavaScript API 输出地图。因为各常用浏览器对地图输出的支持不一致。

如何及时了解 Google Maps Platform 产品发生的变化?

您应该订阅 Google Maps Platform 博客,以接收关于各 Google Geo 开发者产品和服务的最新动态。

如何与技术支持人员联系?

如需了解可用的支持选项,请参阅 Google Maps Platform 支持和资源

技术支持服务在什么时间提供?
对于“服务无法使用”问题,我们的支持团队在工作日全天提供服务,区域性节假日除外,具体的服务时间段为:周一上午 9 点(东京时间)到周五下午 5 点(太平洋时间)。
如何恢复对 Google 账号的访问权限?

如果您无法访问自己的 Google 账号(例如 joe@mycompany.com 或 joe@gmail.com),可以尝试通过找回或重置密码来恢复对账号的访问权限。请参阅 Google 账号帮助中的如何恢复您的 Google 账号或 Gmail 服务一文。

如何恢复对特定项目的访问权限?

如果您无法访问用于管理您的 Google Maps Platform 实现的项目,可以尝试恢复对该项目的访问权限。

如果您有权访问与项目相关联的 Google 账号:

如果您无权访问与项目相关联的 Google 账号:

能否在基于 ARM 的 Mac 上使用 Maps SDK for iOS 和 Places SDK for iOS?

您可以在基于 ARM 的新 Mac 上进行开发,但需要在 iOS 实体设备上进行构建和运行。在我们设法为在模拟器上进行开发提供更多支持期间,会暂时实施此限制。

了解服务条款

Google Maps Platform 产品的服务条款有哪些?

如需查看 Google Maps Platform 服务条款,请访问以下链接:

https://cloud.google.com/maps-platform/terms

我的网站是否符合 Google Maps Platform 服务条款的要求?

只要您的网站符合 Google Maps Platform 服务条款的要求,您就可以在应用内使用 Google Maps Platform。

但是,不应将 Google Maps Platform 用于某些用途:例如,在地图上标识某个城市内可以购买违禁药品的地点,或标识可以进行任何其他非法活动的地点。我们也尊重用户的隐私,因此您不得使用 Google Maps Platform 来标识个人隐私信息。

在开发和发布您的应用之前,您应咨询自己的顾问,确定应用是否符合 Google Maps Platform 服务条款中的要求。Google 工程师只能提供技术协助,无法给予法律建议。Google 保留随时暂停或终止您使用该服务的权利,因此请仔细阅读 Maps API 条款

我能否直接访问地图图块和卫星图像?

您不得通过 Google Maps Platform 以外的任何机制(例如,创建您自己的地图绘制 API 或使用批量图块下载脚本)访问地图图块或卫星图像。如果您的应用通过 Google Maps Platform 以外的机制访问图块,系统会阻止该访问。如需了解详情,请参阅 Google Maps Platform 服务条款

我能否使用 Google Maps Platform 产品来跟踪应用?

在使用 Google Maps Platform 产品显示实时数据(跟踪)方面,我们未设置任何限制,但前提是应用需符合 Google Maps Platform 服务条款中的要求。

我能否在自己的非 Web 应用内使用 Google 地图?

能,Google Maps Platform 产品现在可在非 Web 应用内使用,前提是应用遵守 Google Maps Platform 服务条款中的其他限制。

只有在支持的浏览器中运行时,Google Maps JavaScript API 才受支持。

我能否在受密码保护的网站上使用 Google Maps Platform 产品?

可以,Google 地图、路线、地点和环境服务均可用于设置了私密访问权限的应用。如需了解详情,请参阅 Google Maps Platform 服务条款

我构建的应用可以在文档中包含 Google Maps Platform 数据吗?

如果您的应用可生成电子版或纸质版文档,文档中不得包含任何 Google Maps Platform 数据(包括图片)。如需了解详情,请参阅 Google Maps Platform 服务条款的“No Scraping”(不得抄袭)部分。

如何选择在 Google 搜索结果中排除我的内容?

我们已不再收集此类数据。indexing 参数已被弃用且已失效。您无需再明确停用此参数,但我们建议您尽快将其移除。

如需从搜索结果中移除您的网页或网站,请按照我们的网站站长帮助中心提供的说明操作。

我可以使用 Maps Static API 生成地图图片,将其存储在我自己的网站上,并从自己的网站提供图片吗?

您不得在自己的网站上存储或提供使用 Maps Static API 生成的图片副本。所有需要使用静态图片的网页都必须将 HTML img 标记的 src 属性或 HTML div 标记的 CSS background-image 属性直接关联到 Maps Static API,以便所有地图图片都显示在网页的 HTML 内容中,并直接由 Google 提供给最终用户。

用量限额和结算

如何为项目设置结算信息?
请参阅 Google Maps Platform 使用入门
Google Cloud Platform 免费层级客户如何升级为付费账号?
Google Cloud Platform 免费层级 计划向客户提供 $300 赠金,用于免费试用任何 Google Cloud 服务,包括 Google Maps Platform (GMP) API。免费试用期结束后,您必须 升级为付费账号 以继续使用这些服务。如需升级为付费账号,请访问 Cloud 控制台
Google Maps Platform 是否有用量限额?

您每天可以发出任意次数的 Google Maps Platform 产品请求,在这一方面我们未设置上限。唯一的用量限额与每分钟查询次数 (QPM) 的上限有关。

对于距离矩阵,根据每分钟事件数 (EPM) 设置上限,计算方式是将客户端和服务器端查询相加。

对于 Routes:Compute 路线矩阵,限制以每分钟元素数 (EPM) 为单位,其中 请求中的元素等于:(起点数乘以目的地数)。

对于导航 SDK,请求中的每个目的地都将计为一个单独的查询。

下表列出了各个 API 的用量限额。

API 用量限额
Address Validation 6,000 QPM
Aerial View:查找视频 180 QPM 和 100,000 QPD
Aerial View:渲染视频 100 QPM 和 100 QPD
Air Quality 6,000 QPM
Directions 3,000 QPM
Distance Matrix 60,000 EPM
Dynamic Maps 30,000 QPM
Elevation 6,000 QPM
Geocoding 3,000 QPM
Geolocation 6,000 QPM
Map Tiles API:2D 图块和街景图块 6,000 QPM 和 15,000 QPD
Map Tiles API:仿真 3D 图块 10000 QPD
Map Tiles API:仿真 3D 图块:渲染程序 12,000 QPM
导航:设置目的地请求 30,000 QPM
地点 6,000 QPM
Pollen 6,000 QPM
Roads 30,000 QPM
Routes:计算路线 3,000 QPM
Routes:计算路线矩阵 3,000 EPM
Solar 600 QPM
Static Maps 30,000 QPM
Street View Image API 30,000 QPM
Time Zone 30,000 QPM

为了控制支出,您可以监控 API 用量,并为对任何可计费 API 的所有请求设置每日上限

您必须按照标准 Google Maps Platform 服务条款部署 Google Maps Platform 产品。

如何计算使用费?

如需简要了解 Google Maps Platform 产品的定价,请参阅定价表

如需详细了解 Google Maps Platform API 的结算方式,请参阅了解地图、路线、地点和环境的结算信息

Google Maps Platform 如何统计地图加载次数?

出现以下任意情况时,收取一次地图加载费用:

  • 网页或应用使用 Maps JavaScript API 显示地图。
  • 应用通过 Maps Static API 请求一张地图图片。

街景全景图片和地图加载是分开计费的:

  • 每次向 Street View Static API 发出嵌入某张静态(非交互式)街景全景图片的请求,都会收取一次静态街景全景图片使用费。
  • 在采用 Maps JavaScript API、Maps SDK for Android 或 Maps SDK for iOS 的应用中,对于全景图片对象的每次实例化,您都需支付单张动态街景全景图片的费用。

网页或应用加载地图、静态地图图片或街景全景图片后,用户与之进行的任何互动(例如平移、缩放或切换地图图层)都不会产生任何额外地图加载次数,也不会影响用量限额。

添加标记不会产生额外的地图加载次数,但可能会因确定图钉位置的方式产生费用(例如加载或重新加载“google.maps.Map()”类)。

我如何监控自己的用量?

您可以在 Google Cloud 控制台中监控各个 API 的用量。

  1. 选择包含您要查看的 API 的项目。
  2. 在信息中心上的 API 列表中,点击相应 API 的名称。
  3. 点击页面顶部附近的指标配额

如需查看整个项目的流量报告和结算信息,请按以下步骤操作:

  1. 如果您尚未设置结算信息,请先设置结算信息
  2. 前往 Cloud 控制台的“结算”页面
  3. 选择项目。
  4. 在左侧边栏中,点击报告。使用右侧边栏上的过滤器查看结算账号的报告。

如需了解详情,请参阅 Google Maps Platform 报告以及监控 API 使用量限制 API 使用量

如果我超过请求速率 (QPM) 限额,会怎么样?

如果您超过了指定的 QPM 限制, Google Maps Platform 产品,则 API 将返回错误消息。如果您反复超过限额,系统将暂时阻止您使用相应 API。

如果您超过了请求的 QPM 限额或以其他方式滥用服务,请求将返回特定错误消息。如果您继续超过限额,将无法访问 Google Maps Platform。

注意:以下四个网络服务 API 提供与 Maps JavaScript API 拥有的客户端服务等效的服务:DirectionsDistance MatrixElevationGeocoding

超过用量限额

如果超出用量限额,您会收到 OVER_QUERY_LIMIT 状态代码作为响应。

此消息表示网络服务已停止提供正常响应,并已改为仅返回状态代码 OVER_QUERY_LIMIT,直到获得更多使用量。如果此错误为 因为您的应用每分钟发送的请求过多。

如果您经常超过 QPM 用量限额,不妨考虑优化应用以更加高效地使用 Google Maps Platform 产品,从而降低用量,或者申请增加配额。如需了解详情,请参阅优化指南

我的网站流量很大。我能否使用 Google Maps Platform 产品?

能。不过,我们建议您熟悉一下您的应用所依赖的任何 Google Maps Platform 产品或服务的用量限额

在拥有结算账号后,如果您超过了每月 200 美元的免费用量限额,并且没有为结算账号设置有效的付款方式(信用卡、银行转账等),那么在您添加有效的付款方式之前,API 会停止运作。

用量是如何计算和结算的?

我们会在每天结束时计算用量并按定价表计算费用。在每个月的月底,系统会通过与您的结算账号相关联的付款方式收取总用量的费用。如需了解详情,请参阅 Google Maps Platform 结算

Google Maps Platform 的使用费是多少?

如需简要了解每个 API 的费用,请参阅定价表。如果您的应用生成的请求数或地图加载次数所需的费用不超过每月 200 美元,则您的用量是免费的。超过每月 200 美元赠金的用量费用将从您的结算账号中扣除。如需了解详情,请参阅了解 Google Maps Platform 结算指南

是否提供其他货币的定价?

在控制台内可使用其他货币。当您选择使用其他货币时,定价表中列出的美元费率会转换为等值的其他货币。

我已设置结算信息。如何查看自己的账单?

Google 会按照您的指定付款方式在每个月初收取您上个月的费用。如需详细了解您的账单,请参阅我们的了解 Google Maps Platform 结算指南

其他资源:

如果我的用量意外增加,如何避免支付高额费用?

在 Google Maps Platform 中,您可以通过多种方法来设置每日请求数上限和每日可结算限额。您可以设置每日用量上限,以防止用量意外增加。您还可以设置预算提醒,在结算账号上的费用达到您设置的限额时收到电子邮件通知。

设置每日可结算限额

为了避免支付高额费用,您可以设置每日用量上限,以防止用量意外增加。您可以在 Cloud 控制台中更改此上限,具体步骤如下:

  1. 前往“API 和服务”信息中心
  2. 根据系统提示选择一个项目。
  3. 从列表中选择一个 API,然后点击配额标签页。
  4. 点击“每日请求数”配额旁边的修改图标

或者,您也可以在“IAM 和管理”的“配额”信息中心为多个 API 修改多个配额。

设置和管理预算提醒

设置预算提醒,以在结算账号上的费用达到您设置的限额时向结算管理员发送电子邮件通知。结算管理员将在结算账号上的估算费用超过限额的 50%、90% 和 100% 时收到电子邮件通知。

我收到一条消息说我的项目与“Google Maps Platform 过渡期账号”相关联,但我无权访问该账号。我该怎么办?

“Google Maps Platform 过渡期账号”旨在帮助特定客户过渡到新的随用随付定价方案。借助此过渡期账号,Google 可以向这些客户提供一次性赠金,以便他们可以继续使用 Google Maps Platform,直至达到 200 美元免费层级的限额。超出此限额后,结算账号将会关闭,您将无法再使用服务。为避免服务中断,我们建议您设置自己的结算账号,以便继续享用每月 200 美元的免费层级。如需更改项目的结算账号,请执行以下操作:

  1. 创建新结算账号(如果您已拥有结算账号,可以跳过此步骤)。
  2. 将结算账号与您的项目相关联
为什么我的配额上限设为每天 1 次请求?如何提高此上限?

如果您尚未创建结算账号并将其与您的项目相关联,那么您的 Maps Platform API 配额上限将为每天 1 次请求。您可以通过创建并关联结算账号获得较高的配额。为此,请参阅 Google Maps Platform 使用入门

创建并关联结算账号后,您将不再有每日配额上限。您可以在 Cloud 控制台中设置一个上限,以防产生意外支出

我收到了结算违规通知。如何解决此问题?

您之所以会收到这条通知,是因为 Google 已判定您的账号在使用多个结算账号。这种做法违反了 Google 的相关条款(如 Google Maps Platform 服务条款第 3.2.4 条所述)。根据这些条款的规定,禁止创建多个结算账号。如需了解详情,请参阅结算账号违规方面的常见问题解答

使用 Google Maps Platform

我应该为不同的地图产品使用哪些密钥或凭据?

每次您使用 Google Maps Platform 产品时,都必须添加 API 密钥以验证您的请求。Google Maps Platform 适用于 Android、iOS 或 Web 应用,并且可通过 HTTP 网络服务使用。

API 密钥

  • API 密钥是您使用 Cloud 控制台生成的唯一标识符。
  • 加载包含密钥的 API 的示例:&key=AIzaSyBjsINSH5x39Ks6c0_CoS1yr1Mb3cB3cVo

数字签名

  • 数字签名使用 Google 为您提供的网址签名密钥生成。数字签名用于 Maps Static API 和 Street View Static API。

限制

  • API 密钥限制是可选的,但我们强烈建议您为所有 API 密钥添加限制,以提高安全性。如需了解详情,请参阅 API 安全性最佳做法
  • 您可以向 API 密钥添加应用限制。添加限制后,密钥将只能在支持这一类型限制的平台上工作。有四种类型的应用限制。施加同一限制类型的 API 可以使用相同的受限密钥。
  • 您还可以向 API 密钥添加 API 限制。如需了解详情,请参阅获取、添加和限制 API 密钥

下表列出了适用于各 Google Maps Platform API/SDK 的密钥/凭据和应用限制。

API/SDK 凭据和应用限制
Maps SDK for Android 具有 Android 限制的 API 密钥1
Places SDK for Android 具有 Android 限制的 API 密钥1
适用于 Android 的 Navigation SDK 具有 Android 限制的 API 密钥1
Maps SDK for iOS 具有 iOS 限制的 API 密钥1
Places SDK for iOS 具有 iOS 限制的 API 密钥1
适用于 iOS 的 Navigation SDK 具有 iOS 限制的 API 密钥1
Maps JavaScript API 具有 HTTP 引荐来源网址限制的 API 密钥1
Map Tiles API 具有 IP 地址限制的 API 密钥1
Maps Datasets API OAuth 令牌
Aerial View API 具有 IP 地址限制的 API 密钥1
Maps Static API 具有 HTTP 引荐来源网址限制的 API 密钥1 + 数字签名2
Street View Static API 具有 HTTP 引荐来源网址限制的 API 密钥1 + 数字签名2
Maps Embed API 具有 HTTP 引荐来源网址限制的 API 密钥1
Address Validation API 具有 IP 地址限制的 API 密钥1
Directions API 具有 IP 地址限制的 API 密钥1
Distance Matrix API 具有 IP 地址限制的 API 密钥1
Elevation API 具有 IP 地址限制的 API 密钥1
Geocoding API 具有 IP 地址限制的 API 密钥1
Geolocation API 具有 IP 地址限制的 API 密钥1
Places API 具有 IP 地址限制的 API 密钥1
Roads API 具有 IP 地址限制的 API 密钥1
Routes API 具有 IP 地址限制的 API 密钥1
Time Zone API 具有 IP 地址限制的 API 密钥1
Air Quality API 具有 IP 地址限制的 API 密钥1
Pollen API 具有 IP 地址限制的 API 密钥1
Solar API 具有 IP 地址限制的 API 密钥1
1 API 密钥限制是可选的,但我们强烈建议您为所有 API 密钥添加限制,以提高安全性。
2 Maps Static APIStreet View Static API 可能需要使用数字签名,具体取决于用量。我们强烈建议您在任何使用情况下都应当同时使用 API 密钥和数字签名来对您的请求进行身份验证。
如何将密钥限制类型从 HTTP 引荐来源网址限制改为 IP 地址限制?

重要提示:如果您使用的任何网络服务 API 的 API 密钥采用引荐来源网址限制,您的请求将失败,并显示错误消息“API keys cannot have referer restrictions when used with this API”。您应该改用具有 IP 地址限制的 API 密钥。

在将 API 密钥限制类型从 HTTP 引荐来源网址改为 IP 地址之前,请确保使用相应 API 密钥的所有 API 都支持 IP 限制类型。施加同一限制类型的 API 可以使用相同的受限密钥。如果您需要施加多种限制,请单独添加一个具有所需限制的密钥。了解如何添加新的 API 密钥

详细了解与 Google Maps Platform 产品相关的 API 密钥限制

如要将 API 密钥的限制类型从 HTTP 引荐来源网址限制改为 IP 地址限制,请执行以下操作:

  1. 前往 Cloud 控制台的“凭据”页面
  2. 选择包含您要修改的 API 密钥的项目。
  3. 凭据页面上,从 API 密钥列表中选择相应 API 密钥的名称,以修改其详细信息。
  4. 在该页面的密钥限制部分中,选择“IP 地址(Web 服务器、Cron 作业等)”并插入相应的服务器 IP 地址,然后点击“保存”。
如何获取新的 API 密钥?
请参阅 Google Maps Platform 使用入门
如何找到在 Google Maps API 的各个版本中引入的变更?

如需了解众多 Maps API 的版本变更信息,请访问以下链接:

您还可以使用 Google Maps Platform 问题跟踪器查看 Google Maps Platform 的哪个版本中引入了以及修复了特定 bug,网址如下:

https://issuetracker.google.com/bookmark-groups/76561

如何在网页加载完毕后以异步方式将 API 加载到网页中?

只需在加载 API 时指定回调参数即可。有关详情和示例代码,请参阅 Maps JavaScript API 文档的使用入门一章。

如何让 Google Maps Platform 产品以非英语语言显示?

默认情况下,API 将尝试根据用户位置或浏览器设置加载最恰当的语言。某些 API 允许您在发出请求时明确设置语言。如需详细了解如何设置语言,请参阅各 API 对应的文档:

支持的语言

Google 会经常更新支持的语言。此列表并非详尽无遗,并且随时可能会发生变化。

语言代码 语言 语言代码 语言
af 南非荷兰语 ja 日语
sq 阿尔巴尼亚语 kn 卡纳达语
am 阿姆哈拉语 kk 哈萨克语
ar 阿拉伯语 km 高棉语
hy 亚美尼亚语 ko 韩语
az 阿塞拜疆语 ky 吉尔吉斯语
eu 巴斯克语 lo 老挝语
be 白俄罗斯语 lv 拉脱维亚语
bn 孟加拉语 lt 立陶宛语
bs 波斯尼亚语 mk 马其顿语
bg 保加利亚语 ms 马来语
my 缅甸语 ml 马拉雅拉姆语
ca 加泰罗尼亚语 mr 马拉地语
zh 中文 mn 蒙古语
zh-CN 中文(简体) ne 尼泊尔语
zh-HK 中文(香港) no 挪威语
zh-TW 中文(繁体) pl 波兰语
hr 克罗地亚语 pt 葡萄牙语
cs 捷克语 pt-BR 葡萄牙语(巴西)
da 丹麦语 pt-PT 葡萄牙语(葡萄牙)
nl 荷兰语 pa 旁遮普语
en 英语 ro 罗马尼亚语
en-AU 英语(澳大利亚) ru 俄语
en-GB 英语(英国) sr 塞尔维亚语
et 爱沙尼亚语 si 僧伽罗语
fa 波斯语 sk 斯洛伐克语
fi 芬兰语 sl 斯洛文尼亚语
fil 菲律宾语 es 西班牙语
fr 法语 es-419 西班牙语(拉丁美洲)
fr-CA 法语(加拿大) sw 斯瓦希里语
gl 加利西亚语 sv 瑞典语
ka 格鲁吉亚语 ta 泰米尔语
de 德语 te 泰卢固语
el 希腊语 th 泰语
gu 古吉拉特语 tr 土耳其语
iw 希伯来语 uk 乌克兰语
hi 印地语 ur 乌尔都语
hu 匈牙利语 uz 乌兹别克语
is 冰岛语 vi 越南语
id 印度尼西亚语 zu 祖鲁语
it 意大利语

您可以通过此示例应用查看地图以上述任何语言显示时的效果。

能否通过 SSL (HTTPS) 访问 Google Maps Platform?

您可以通过安全 (HTTPS) 连接访问 Maps JavaScript API、Maps Static API 和网络服务 API。如需了解如何通过 SSL 访问 API,请参阅相关 API 对应的文档。

请注意,Maps Static API 不支持使用 HTTPS 的自定义图标网址;将显示默认图标。

如何在 Google Maps Platform 中报告 bug 或请求新功能?

如果您认为自己可能遇到了 bug,请先到相关论坛发帖提问,以便其他开发者验证该 bug 并排除您的代码中可能存在的问题。

如果您有功能方面的请求,也请先到相关论坛发帖,以确认现有的解决方案确实无法满足您的需求。

如果您确认自己发现了新 bug,或者 Google Maps Platform 产品的现有功能无法满足您的需求,请使用 Google Maps Platform 问题跟踪器报告 bug 或提交功能请求。

在向问题跟踪器添加 bug 或功能请求之前,请确保他人尚未提交过相同的 bug 或功能请求。如果已有他人提交,您可以将该问题加注星标,以表示关注并接收更新通知。

Google Maps Platform API 如何使用网站 Cookie?

Maps SDK for Android 和 Maps SDK for iOS 使用遵守 Google 隐私权政策的 Cookie,例如计算每日和 7 天内的活跃用户数以及防止服务滥用。这些 Cookie 不会与任何已登录的 Google 账号相关联,也不会与从 API 调用中收集的其他信息一起被记录下来。

我找不到所遇问题的答案。应该与谁联系?

Google 开发者关系团队在 Stack Overflow 上设有常驻人员。Stack Overflow 是一个协作编辑的问答网站,面向编程人员。您可以在此咨询关于开发和维护 Google 地图应用的技术问题。如需了解如何在 Stack Overflow 上提问,请参阅支持页面。

要想在请求帮助时获得最满意的结果,请注意以下几点:

  • 搜索最新讨论内容。可能其他人也遇到类似问题并找到了解决方案。
  • 如果可能,提交指向您的网站的链接。请仅在代码不方便在线查看时才发布代码段。
  • 提供所有相关信息,包括浏览器版本、错误和其他所有可能有助于排查该问题的信息。

错误和问题排查

此错误意味着什么?

如果您在加载或运行 Google Maps API 时遇到了错误,请访问以下链接,以找到关于错误代码的说明:

我的地图看上去比平时暗。这是怎么了?

在某些情况下,可能会显示暗色地图或“负片”效果的街景图像,并带有“仅用于开发目的”的文字水印。如果出现此行为,通常说明存在 API 密钥或结算方面的问题。如要使用 Google Maps Platform 产品,您必须拥有结算账号,并且所有请求都必须包含有效的 API 密钥。以下流程有助于排查此问题:


如何让错误代码 OVER_DAILY_LIMITOVER_QUERY_LIMIT 不再显示?
系统可能会因为以下任何原因而返回这些错误代码:
  • 请求中缺少 API 密钥。
  • 提供的 API 密钥无效。
  • 项目没有关联的结算账号。
  • 超出了您设定的用量上限
  • 提供的付款方式不再有效(例如,信用卡已过期)。
  • 您已超出给定 API 的配额限制

如要使用 Google Maps Platform 产品,您必须拥有结算账号,并且所有请求都必须包含有效的 API 密钥。如需修正此问题,请按以下步骤操作:

如何让错误代码 kGMSPlacesRateLimitExceeded9005 PLACES_API_RATE_LIMIT_EXCEEDED 不再显示?
如果您看到 kGMSPlacesRateLimitExceeded9005 PLACES_API_RATE_LIMIT_EXCEEDED,则说明您使用的可能是已弃用的 Places SDK for Android 或 Places SDK for iOS 版本。如需了解详情并查找新版 SDK,请访问 https://goo.gle/places-sdk-deprecation
如何修正错误“This IP, site or mobile application is not authorized to use this API key.”?

以下各种情况均有可能引发这一错误:

  • 您为 API 密钥启用了 IP 地址(服务器)限制,但有未经授权的 IP 地址尝试发出请求。
  • 您为 API 密钥启用了 HTTP 引荐来源网址限制,但有未经授权的引荐来源网址尝试发出请求。
  • 您已通过设置软件包名称和指纹将使用方限制为您的 Android 应用,但有未经授权的 Android 应用尝试发出请求。
  • 您已通过指定软件包标识符限制了来自 iOS 应用的请求,但有无法识别的 iOS 应用尝试发送请求。
  • 如果您的任何网络服务 API 使用的是具有 HTTP 引荐来源网址限制的 API 密钥,可能会出现这种错误。应使用具有 IP 地址限制的 API 密钥来标识对这些 API 的请求。将您的密钥限制类型从 HTTP 引荐来源网址限制切换为 IP 地址限制。如需详细了解如何限制 API 密钥,请参阅 API 密钥最佳实践

查看和修改您的 API 密钥凭据

如需查看您的 API 密钥以及管理任何限制,请执行以下步骤:

  1. 前往 Cloud 控制台的“凭据”页面
  2. 选择包含您要查看的 API 密钥的项目。
  3. 如需查看凭据详情,包括为密钥设置的任何限制,请在 API 密钥列表中点击密钥的名称。
  4. 此时会显示所选 API 密钥的完整凭据,包括为该密钥设置的任何限制。在这里,可根据需要更改、删除或更新限制。
如何修正错误“API keys with referer restrictions cannot be used with this API.”?

您正在使用任一网络服务 API,其 API 密钥采用 HTTP 引荐来源网址限制。为安全起见,网络服务 API 需要使用具有 IP 地址限制的 API 密钥。请将您的密钥限制类型从 HTTP 引荐来源网址限制改为 IP 地址限制;如果您的 API 密钥已用于 Maps JavaScript API,请创建新的密钥。

Google Maps Platform 服务

我需要将地址转换为纬度/经度对。可以使用 Google Maps Platform 执行此操作吗?

可以,该过程称为“地理编码”。Maps JavaScript API 包含一个用于执行地理编码服务的类。该类为 google.maps.Geocoder

此外,Google 还推出了 Geocoding API,该 API 提供的 REST 接口能够以 JSON 和 XML 格式作出响应。

地理编码可在哪些国家/地区使用?

如需了解 Google Maps Platform 地理编码器目前支持在哪些国家/地区使用,请参阅 Google 地图覆盖范围数据

经过地理编码的位置的精确度可能会因国家/地区而异,因此您应考虑根据返回的 location_type 字段,确定您的应用是否找到了合适的匹配项。请注意,地理编码数据的提供情况取决于我们与数据提供商之间签订的合同,可能会发生变化。

为什么 Google Maps Platform 地理编码器与 Google 地图提供的位置不同?

API 地理编码器和 Google 地图地理编码器有时会使用不同的数据集(取决于具体国家/地区)。API 地理编码器会根据新数据不定期更新,因此随着时间的推移,您会看到结果发生变化或有所改进。

该如何设置地理编码器查询格式,才能最大限度提升请求的成功率?

地理编码器的作用是将街道地址映射为地理坐标。因此,我们建议您按照以下准则设置地理编码器请求的格式,以最大限度提高查询的成功率:

  • 根据相关国家/地区的邮政服务所使用的地址格式指定地址。
  • 请勿指定未包含在相关国家/地区的邮政服务所定义的地址中的其他地址元素,例如企业名称、单元号、楼层号或房间号。这样做可能会导致返回 ZERO_RESULTS 响应。
  • 按如下格式设置 Plus Codes(加号经网址转义为 %2B,空格经网址转义为 %20):
    • 全局代码是包含 4 个字符的区号和至少包含 6 个字符的区域代码(849VCWC8+R9 为 849VCWC8%2BR9)。
    • 混合代码是至少包含 6 个字符的区域代码,具有明确的位置信息(CWC8+R9 Mountain View, CA, USA 为 CWC8%2BR9%20Mountain%20View%20CA%20USA)。
  • 尽可能优先使用建筑物的门牌号码,其次才是建筑名称。
  • 尽可能优先使用门牌号码进行寻址,其次才是指定十字路口。
  • 不要提供“提示”(例如附近的地标)。
如何为有编号的美国公路地址设置统一格式,以进行地理编码?

Google Maps Platform 地理编码器要求按以下格式指定地址中的有编号的美国公路:

  • 县级公路"Co Road NNN"(其中“NNN”为公路编号),例如 "Co Road 82"
  • 州级公路"State NNN"(其中“State”为州的全名,“NNN”为公路编号),例如 "California 82"
  • 美国国道"U.S. NNN"(其中“NNN”为公路编号),例如 "U.S. 101"
  • 美国州际公路"Interstate NNN"(其中“NNN”为州际公路编号),例如 "Interstate 280"
应在何时使用 API 地理编码器类?何时使用 HTTP 地理编码服务?

请参阅地理编码策略文档,其中详细介绍了各种地理编码策略的优缺点。

如何通过 Google Maps Platform 提供行车路线?

通过 Routes APIDirections API计算路线服务,您可以针对单程和多程行程提供行车路线。您可以使用路线安排选项,设置出行方式(例如驾车)、单条路线或一组路线以及限制条件(例如避开收费公路),从而生成行车路线。您可以通过以下形式使用这些服务:

  • HTTP 请求/响应接口(适用于移动应用和其他应用)与 Maps SDK for Android 和其他 Google 地图网络服务兼容。
  • 借助 JavaScript API(适用于客户端应用),您可通过 google.maps.DirectionsService 类提供行车路线。DirectionsRenderer 类可自动为您创建叠加层和路线面板。如需查看其他示例,请参阅相关文档。
  • Java、Python、Go 和 Node.js 客户端接口(适用于服务器端应用)提供相同的功能。如需详细了解客户端库,请参阅 Directions API 客户端库
行车路线服务面向哪些国家/地区提供?

如需了解 Google Maps Platform 产品中的行车路线目前支持在哪些国家/地区使用,请参阅 Google 地图覆盖范围数据。请注意,行车路线的提供情况取决于我们与数据提供商之间签订的合同,可能会发生变化。

公交路线服务面向哪些国家/地区提供?

Directions APIDistance Matrix API 支持所有 Google 公交合作伙伴(日本的合作伙伴除外)。

Maps JavaScript API 支持哪些 KML 和 GeoRSS 功能?

借助 Maps JavaScript API 中的 KmlLayer 类,开发者可以在地图上方叠加 KML/KMZ 和 GeoRSS 文件。如需查看相关文档和示例,请点击此处

可使用 Maps JavaScript API 的 KmlLayer 类显示的 KML 在大小和复杂程度上有什么限制?

如需了解使用 KmlLayer 类显示 KML 时的大小和复杂程度限制,请参阅此处的文档。

如何在地图上渲染托管在内网网站上的 KML 文件?

KmlLayer 类会在 Maps JavaScript API 中生成 KML 叠加层,它使用 Google 托管服务检索和解析要渲染的 KML 文件。因此,如果 KML 文件未托管在可以公开访问的网址(无需进行身份验证即可访问)上,则无法显示。

如果您要开发的应用需要使用托管在内网网站上的 KML 文件,我们建议您使用第三方 JavaScript 库在客户端上渲染 KML 文件。由于该 KML 文件是由浏览器进行分析的,因此与使用 KmlLayer 类进行分析相比,前者的性能可能较低。

Maps Static API 最多支持多少个标记或路径顶点?

Maps Static API 支持的标记或路径顶点数没有限制。使用自定义图标时,每个请求最多可指定五个唯一图标,不过每个图标都可在地图内多次使用。

请注意,Maps Static API 网址最多可包含大约 8,192 个字符,这可限制可以指定的标记和路径顶点数(该数量取决于指定各个纬度/经度对时使用的小数位数)。如需了解所使用的小数位数与 Google 地球精确度的关系,请参阅这篇关于十进制度数的维基百科文章。

为什么我在某些国家/地区无法使用 Google Maps Platform 产品?

Maps API 不得在禁止的地区使用。另请参阅服务条款

如何报告 Google 基本地图相关问题?
您可以通过 Google 地图发送有关地图信息错误或缺失的反馈,例如:
  • 地址或标记位置错误
  • 道路名称不正确
  • 单行道和双行道信息不正确
  • 道路绘制有误
  • 道路封闭
  • 道路不存在

如需更正地点或商家信息,请提出修改建议

如果您认为根据适用法律某些地图内容需要被移除,请提交法律请求

对于关键请求或具有时效性的请求,请提交支持请求,并详细说明需要修正哪些内容。

系统如何监控与 Maps JavaScript API 搭配使用的服务的性能?

一些客户端功能已设置插桩,可报告成功或失败,以计算 SLO(服务等级目标)。此信息将通过 maps.googleapis.com/maps_api_js_slo/log 在记录 SLO 信息的调用中发送至 Google。此类信息包括所使用的 Maps JavaScript API 的成功状态、延迟时间和版本/渠道。为了提升性能,系统可能会批量处理这些调用。请注意,您可能需要在内容安全政策中允许 maps.googleapis.com,以确保这些调用不会在浏览器级别被阻止。例如:带有 HTTP 标头的 Content-Security-Policy: default-src 'self' maps.googleapis.com;,或带有 HTML 元标记的 <meta http-equiv="Content-Security-Policy" content="default-src 'self' maps.googleapis.com;">

Maps JavaScript API

Maps JavaScript API 加载后的有效时间是多久?

您至少要每 5 天刷新一次加载 Maps JavaScript API 的页面。

Google Maps SDK for iOS

如何修正错误 kGMSPlacesRateLimitExceeded
如果您看到此错误,则说明您使用的可能是已弃用的 Places SDK for iOS 版本。Places SDK for iOS 版本 2.7.0 已停用,不再提供。请尽快将您的应用更新为使用最新版本。如需了解详情,请参阅迁移指南
我在使用 iOS 8.x 设备进行调试时遇到崩溃问题。我该怎么做?

如果您在使用搭载 iOS 8.x 的设备进行调试时遇到问题,请按照以下步骤在所运行的 XCode 架构中停用 GPU 帧捕获:

  1. 在 XCode 中,依次选择 ProductSchemeManage Schemes
  2. 选择相应架构,然后选择 Edit...
  3. GPU Frame Capture 选项设置为 Disabled。请注意,可能并非针对所有设备都提供此选项。
常规 iOS 设备页面上的 Xcode GPU Frame Capture 选项
圆角且较宽的屏幕对 Google Maps iOS SDK 有何影响?

iPhone X 开始,iPhone 将采用全新的屏幕形状:拥有全新圆角,顶部凹口造型的设备传感器区域(“刘海”),以及屏幕底部用于返回主屏幕的指示横条。自 iOS 11.0 SDK 起,Apple 新增了 Safe Area API,以便开发者能够将元素放置到不会被全新的屏幕形状裁剪的安全区域。

Google Maps iOS SDK 提供许多视觉元素和控件,例如室内楼层选择器和问题报告链接。在版本 2.4 中,这些视觉元素和控件可能会被全新的屏幕形状裁剪。在横屏模式下,室内楼层选择器可能会被凹口或主屏幕按钮指示横条裁剪。

在 Google Maps iOS SDK 2.5 版本中,这些布局问题会自动得到修复。用户在 iPhone X 或更新机型上使用您的应用时,系统会增加 GMSMapViewGMSPanoramaView 的内边距,防止视觉元素被裁剪。

默认情况下,我们会始终包含您的内边距。Google Maps iOS SDK 假设内边距是从安全区域向外延伸的。如果您在设计界面时假设所有内容都放置在安全区域内,那么您无需执行任何其他操作即可实现调整。

如果您设计的界面不支持进行我们的默认调整,我们为 GMSMapView 引入了一个名为 paddingAdjustmentBehavior 的新属性。现在,您可以使用 GMSMapView 选择以下三种内边距调整行为之一:“Always”(默认)、“Automatic”和“Never”。

如果 GMSMapView 设置为使用“Always”内边距行为,它将始终向内边距添加安全区域边衬区。这样,您就可以在设计界面时假设所有元素都在安全区域的边缘内。这是默认值。

如果 GMSMapView 设置为使用“Automatic”内边距行为,它将始终选择内边距或安全区域边衬区这两者中的较大者。这样,您就可以从屏幕边缘添加内边距,同时确保所有元素始终位于安全区域内。

如果 GMSMapView 设置为使用“Never”内边距行为,它绝不会向内边距添加安全区域边衬区。这是 2.5 版本之前的行为。如果您的内边距已将安全区域考虑在内,或者如果我们的其他行为不适用于您的界面,此行为可能较为实用。您有责任确保 Google 徽标和版权通知始终可见(如 Google Maps Platform 服务条款中所规定)。

相反,GMSPanoramaView 没有可选的内边距属性。这意味着没有内边距可调整,并且 GMSPanoramaView 会始终应用任何必要的内边距,以确保所有视觉元素都位于安全区域内。

Google Maps SDK for Android

如何修正错误 9005 PLACES_API_RATE_LIMIT_EXCEEDED
如果您看到此错误,则说明您使用的可能是已弃用的 Places SDK for Android 版本。Places SDK for Android 的 Google Play 服务版本已停用,不再提供。请尽快将您的应用更新为使用最新版本。如需了解详情,请参阅迁移指南
我的应用仅显示空白的灰色图块,而非地图。如何解决此问题?

如果应用显示空白的灰色图块而非地图,一种常见原因是存在身份验证问题。您可以按照以下步骤,使用 adb logcat 排查这些问题。

  1. 确保您已安装 adb。如果尚未安装,请按照此处的指南操作。
  2. 在设备或 Android 模拟器上安装存在相应问题的应用。如果您使用的是 Android 模拟器,请确保模拟器中设置了 Play 商店。
  3. 在 Android Studio 终端中,运行 adb logcat -e "Google Maps Android API"。这只会输出日志消息与“Google Maps Android API”匹配的行(或者,您也可以通过附加“> logcat.txt”将日志输出到文本文件)。
  4. 在设备上重现问题,并检查以下常见错误:
    • 清单中引用了错误的/意外的 API 密钥。
    • 项目未启用结算功能。
    • 项目 API 未启用相应 SDK。
    • API 密钥限制中添加了错误的 SHA1 指纹。
    • Google Play 服务依赖项未包含在 build.gradle 文件中。

网址签名

可以使用 JavaScript 对网址进行签名吗?

我们强烈建议您不要使用 JavaScript 对网址进行签名,因为这样会将您的网址签名密钥公开给最终用户。因此,仅应由服务器端组件生成签名。

为什么我的 Maps API 网络服务请求收到“HTTP 403 Forbidden”响应?

HTTP 403 响应表示存在权限问题,这可能是由于无法为此请求验证签名造成的。可能的原因如下:

  1. 签名不正确:指定的签名无法用于此请求。
  2. 此请求指定了 Google Maps Platform 专业版方案 API 密钥,但未指定签名,并且正在调用的服务要求使用 API 密钥发起的请求都应包含有效签名。
  3. 已指定签名,但未指定关联的 Google Maps Platform 专业版方案 API 密钥。