Maps Static API 中的错误消息

当出现问题时,Maps Static API 可能会发出错误或警告。本指南介绍了每种错误消息,并进一步说明了如何解决错误。

无效请求

如果请求无效,Maps Static API 会返回 HTTP 4xx 状态代码和一条描述问题的消息。以下是此类错误情况的示例。注意:以上并未列出所有可能的错误。请查看 API 返回的实际错误代码和消息,了解有关特定问题的详细信息。

错误状况示例 状态代码
请求包含无效参数,或缺少必需的参数。例如,size 参数不在预期的数值范围内,或者请求中缺少该参数。 400 BAD REQUEST
请求中包括的 API 密钥无效。 403 FORBIDDEN

导致地图无法显示的错误

如果请求有效,但发生了另一个导致地图无法显示的错误,Maps Static API 会返回文本或错误图片(而不是地图),具体取决于错误。此类错误条件的一个例子是应用超出其用量限额

显示错误图像而非地图
图:显示的错误图片而非地图

如果您在没有 API 密钥的情况下使用 Maps Static API,或者您的帐号未启用结算功能,页面会显示错误图片(而不是地图),以及指示错误类型的链接。例如,“g.co/staticmaperror/key”。

无密钥错误与解决方案
使用限制错误:超出提供的每日地图加载次数限制 您正在使用 Maps Static API,而没有使用 API 密钥。如需解决此问题,您必须:
  1. 获取 API 密钥
  2. 启用结算功能
  3. 对网址进行签名
使用限制错误:请求网址缺少数字签名 您的请求缺少数字签名(必填)。如需解决此问题,请 为您的网址签名

警告

对于某些错误情况,API 会返回一个地图,但地图中可能缺少一些信息。发生这种情况时,系统会在以下情况下通知您:

  • 第一,地图显示,但地图顶部会叠加一个黄色错误栏,并附有文本“Map error: g.co/staticmaperror”。
  • 其次,API 会以名为 X-Staticmap-API-Warning 的 HTTP 标头的形式返回警告。

例如,以下网址的 markers 参数中包含意外值:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

API 会返回一个地图,但会在图片上叠加显示黄色错误栏,并显示“Map error: g.co/staticmaperror”:

地图显示,但会在地图上显示错误信息:g.co/staticmaperror

API 也会返回以下 HTTP 标头:

X-Staticmap-API-Warning:Error geocoding: marker 1

下表介绍了 API 可能会以 HTTP 标头形式发出的警告:

X-Staticmap-API-Warning 标头中的警告
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* 尝试对请求进行地理编码时出错。此消息有许多变体,具体取决于地理编码失败的元素(center、marker、visible 或 path)以及失败的元素数量。如上例所示,X-Staticmap-API-Warning:Error geocoding: marker 1 就是此警告的一个示例。
Too many geocoded markers requested (max is 15). 请求指定的具有人类可读地址的标记数量超过了允许的最大数量。最大值为 15。请注意,此限制仅适用于指定为需要进行地理编码的直观易懂的地址的标记。并不适用于以纬度/经度坐标指定的标记。
Too many geocoded polyline vertices requested (max is 15). 请求指定的具有人类可读地址的多段线数量超出允许的上限。最大值为 15。请注意,此限制仅适用于将顶点指定为需要进行地理编码的直观易懂的地址的多段线。不适用于通过纬度/经度坐标指定的多段线。

您可以在 Chrome 开发者工具控制台Firefox Web 控制台或浏览器中的其他等效工具中查看 HTTP 标头警告。