问题排查

错误

如果发生错误，系统会返回标准格式的错误响应正文，并将 HTTP 状态代码设为错误状态。

响应包含一个对象，其中包含一个具有以下键的 error 对象：

  • code：与响应的 HTTP 状态相同。
  • message：错误的简短说明。
  • status：一个状态代码，用于指示错误的性质。

例如，发送无效的 placeId 参数将返回以下错误：

{
  "error": {
    "code": 400,
    "message": "\"placeId\" value is malformed: \"aChIJqaknMTeuEmsRUYCD5Wd9ARM\"",
    "status": "INVALID_ARGUMENT"
  }
}

可能的错误包括：

代码 状态 消息 问题排查
400 INVALID_ARGUMENT 您提供的密钥无效。 您的 API 密钥无效或未包含在请求中。 请确保您已添加完整的密钥，并且已为此密钥启用 API。
400 INVALID_ARGUMENT \"path\" 参数包含无效值：☃" 您的请求包含无效参数。导致出现此错误的最可能原因如下：
  • 您的 path 参数存在问题。
    请确保您的分数至少为 1，且不超过 100 分。每个数据点应为一对以英文逗号分隔的数字，例如：48.409114,-123.369158。点应以竖线“|”分隔。
  • 您的请求包含无效的 placeId。
  • 您的请求同时包含 placeId 和 path。每个请求只能指定其中一个参数。

如果为已不存在的道路或非道路地点传递 placeId，则不会返回此错误。
403 PERMISSION_DENIED 未注册的请求被屏蔽。请使用 Google Developers Console 进行注册。 请求因以下一种或多种原因而被拒：
  • API 密钥缺失或无效。
  • 您的账号尚未启用结算功能。
  • 超出了您设定的用量上限。
  • 提供的付款方式不再有效（例如，信用卡已过期）。

为了使用 Google Maps Platform 产品，必须为账号启用结算功能，并且所有请求都必须包含有效的 API 密钥。如需解决此问题，请按以下步骤操作：
404 NOT_FOUND 此服务需要使用 HTTPS。 确保您将请求发送到 https://roads.googleapis.com/，而不是 http://roads.googleapis.com/。
429 RESOURCE_EXHAUSTED 由于已达到项目请求限制，因此请求被节流。 您已超出在 Google Cloud Platform 控制台中配置的请求限制。此限制通常设置为每天请求数、每 100 秒请求数和每个用户每 100 秒请求数。 您应配置此限制，以防止单个用户或一小群用户耗尽您的每日配额，同时仍允许所有用户获得合理的访问权限。如需配置这些限制，请参阅限制 API 用量。

指数退避算法

当请求失败时，您应确保使用指数退避算法重试请求。例如，如果请求失败一次，请在 1 秒后重试；如果再次失败，请在 2 秒后重试，然后在 4 秒后重试，依此类推。这可确保由于许多客户端会尝试非常快速地重试请求，因此损坏的请求或大规模失败不会使 Google 服务器过载。

问题排查常见问题解答

实施问题

我应该以什么频率采样车辆位置信息？
建议每 1-10 秒更新一次，以获得高质量的路线贴合结果。
每次查询可以发送的点数是否有上限？
是的，一个查询最多可以包含 100 个点。
我应该使用什么精度来存储经过截断处理的纬度/经度对？
为确保经过修剪的路径在所有缩放级别（即使在最大缩放级别）都沿着道路，您应将经过修剪的经纬度对存储为小数 7 位精度。
我可以使用编码的多段线来显示已捕获的路径吗？
编码的多段线的精度仅指定为小数点后 5 位，因此会导致误差约为 2 米。因此，如果您希望已修剪的路径在高缩放级别下沿着道路，则编码多段线不适合。

常见问题

某些点无法对齐，或者对齐的路径中存在间隔。如何更正此问题？
  • 如果您按时间间隔采样点，请确保采样点的间隔时间较短（每 1-10 秒采样一次）。如果使用较长的间隔时间（例如 60 秒），路线贴合算法可能无法准确确定所经道路。
  • 如果您手动点击地图来创建点，很容易创建点数较少或点状稀疏的路径，而这些路径会导致捕获算法无法正常处理。对彼此相近的点，贴靠算法效果最佳。试用“贴靠到道路”演示版，或使用道路检查器测试路径。
为什么我在放大时，已捕获的路径会锯齿状或与道路略有偏差？
  • 您是否会在显示已对齐的纬度/经度对之前截断其精度？如果以小于 7 位小数的精度存储已对齐的纬度/经度对，则在地图上显示已对齐的路径时会导致精度误差。
  • 您是否使用了编码多段线？编码多段线会将纬度/经度对截断为小数点后 5 位，这会导致出现几米的误差，从而导致线条在高缩放级别下锯齿状或与道路略有偏差。

如果不存在上述任何情况，则表示地图图块可能最近已更新，导致其与用于贴靠的道路索引不同步。如果只有少数查询受到影响，这可能就是原因。由于 Google 地图会定期更新，因此这种情况可能会偶尔发生。如果您经常查看地图上的旧路线（例如几周前拍摄的路线），这种情况可能会更频繁地发生。为了实现最佳可视化效果，您应在将旧路径显示在地图上之前重新对其进行贴靠，以最大限度地减少地图图块与用于贴靠的道路索引之间的不一致性。

什么原因会导致 X 路的限速显示不正确？
速度限制来自多个来源，这些来源的准确性和覆盖范围各不相同。如果您发现某种规律（例如特定道路类型或特定区域的限速值始终不正确），请按照以下步骤通知我们：
  1. 在桌面设备上打开 Google 地图，或在 Android 设备上打开 Google 地图应用。
  2. 打开左侧菜单。
  3. 选择发送反馈。注意：系统可能会提示您登录。
  4. 选择修改地图。
  5. 选择要修改的道路路段。
  6. 选择下一步。
  7. 在“其他”字段中，指明相应道路的限速有误。
  8. 选择提交。
您还可以在此处报告其他问题（例如道路名称有误、绘制有误、封闭或不对外开放）。
为什么我的路径会沿着路边截断，而不是沿着道路？
如需解决此问题，请检查以下各项：
  • 确保 interpolate 参数设置为 true。
  • 检查原始数据点的采样间隔是否足够接近（每 1-10 秒）。
为什么对于没有限速变化的道路，系统会在已对齐的路径中返回许多路段？
当 interpolate 参数设置为 true 时，贴合道路查询会返回沿着道路绕过拐角、弯道和环岛的多段线。如果道路弯曲，系统会返回多个道路路段，即使限速不变也是如此，以便创建紧贴道路几何图形的多段线。