主要概念

如需生成等时线，请向 API 提供起点、出行方式（例如驾车、骑车或步行）和时间限制。您还可以调整路线偏好设置以及生成的多边形的视觉外观。

时间范围

您提供给服务的主要约束条件是 travel_duration。这定义了计算的时间范围。

• 最长时长：该 API 支持 DRIVE 模式下的最长行程时间为 3600 秒（1 小时），WALK 和 BICYCLE 模式下的最长行程时间为 7200 秒（2 小时）。
• 性能：计算时间会随着所请求的时长和所选的出行方式而变化。与 1 小时的步行等时线相比，1 小时的驾车等时线覆盖的地理区域和道路网络要大得多，因此驾车请求的延迟时间更长。
• 格式：由于该 API 使用 google.protobuf.Duration，因此时长必须采用以“s”结尾的字符串格式（例如 "3600s"），而不是整数。

起点和道路贴合

您可以通过两种方式指定等时线的起点：

• 坐标：纬度和经度对 (location)。
• 地点 ID：Google 地图上特定地点的唯一标识符 (place)。如果您提供地点 ID，该服务会将相应地点的质心用作原点。请注意，该 API 需要资源名称格式，例如 places/ChIJ...。如需详细了解地点 ID，请参阅地点 ID。

无论采用哪种输入方法，如果确切的实体点不在道路上（例如在公园或建筑物内），该 API 都不会计算从该点出发的出行时间。为了应对这种情况，该服务会使用道路贴合功能。道路贴合具有以下功能：

• 智能贴合：该服务会尝试将起点贴合到最近的可通行路段。
• 模式感知：贴靠逻辑会考虑您的 travel_mode。如果您请求 DRIVE，API 会忽略仅供行人通行的道路，并寻找最近的可行驶街道。如果您请求 WALK，API 会优先考虑可步行的小路和人行道。
• 失败情况：如果 API 在起点的大约 100 米范围内找不到合适的道路段，则会返回 404 NOT_FOUND 错误。这通常表示该点距离道路网络太远，或者位于地图数据不支持所请求出行方式的区域。

旅行方向（入境与出境）

您可以使用 travelDirection 参数计算入站和出站可达性：

• FROM（出站）：计算在指定时间限制内从原点可到达的区域。这适用于配送区域或服务覆盖范围等使用情形。
• TO（入界）：计算在指定时间限制内可从哪些区域到达原点的区域。这适用于确定集水区，例如员工可以从哪些地方通勤到中央办公室。

流量意识

使用 routing_preference 参数控制路况数据对生成的多边形的影响：

• TRAFFIC_UNAWARE（默认）：使用限速和道路分层结构生成等时面多边形。这样会生成一个确定性形状，不会因一天中的时间而波动。此形参非常适合进行一般分析或基准情景规划。
• TRAFFIC_AWARE：使用请求时的实时或预测交通状况计算等时线，导致可达区域在拥堵时缩小，在非高峰时段扩大。注意：只有在 travelMode 设置为 DRIVE 时，才支持流量感知型路由。

平滑度和保真度

您可以使用 polygon_fidelity 和 enable_smoothing 参数自定义输出多边形的外观和精确度。虽然这些选项是独立的，但它们共同决定了最终的形状。

• polygon_fidelity：控制用于计算可达区域的底层网格单元的大小。

  • LOW：使用更大的网格单元。最适合覆盖大面积区域而不留空隙，从而形成广义形状。
  • MEDIUM：平衡精度。
  • HIGH：使用较小的网格单元。可更紧密地贴合道路网络，但如果道路网络稀疏，可能会产生空白区域或孔洞。
  • POLYGON_FIDELITY_UNSPECIFIED：如果未指定，服务会根据请求的出行时长动态选择保真度。

    

• enable_smoothing：控制是否将保真度定义的网格单元格的尖锐边缘圆角化。

  • false（原始）：默认值。返回精确的几何计算结果。 边缘呈锯齿状或阶梯状。最适合需要高分析准确度的场景，例如严格的“点在多边形内”测试。延迟时间比平滑处理后更短。
  • true（平滑）：应用后处理算法来使边角变圆。最适合在地图上直观显示。