等时线 API 最佳实践

平滑度和保真度

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

  • polygon_fidelity：分辨率。用于控制计算可达区域时所用的底层网格单元（S2 单元）的大小。
    • LOW：使用较大的网格单元。最适合覆盖大面积区域，不会出现空白，从而形成概括的形状。
    • MEDIUM：平衡精确度。
    • HIGH：使用较小的网格单元。这样可以更紧密地贴合道路网络，但可能会在道路网络稀疏的区域产生空白区域或“孔洞”。
    • 默认值：如果未指定，服务会根据请求的出行时长动态选择保真度。
  • enable_smoothing：美观性。用于控制由保真度定义的网格单元格的尖锐边缘是否圆角化。
    • false（原始）：返回精确的几何计算结果。边缘显示为锯齿状或阶梯状，反映了网格单元。最适合需要高分析准确度的场景，例如严格的点在多边形内测试。
    • true（平滑）：应用后处理算法来使边角变圆。最适合在地图上直观显示。

互动方式：保真度设置了平滑算法所依据的基准细节。

  • 高保真度 + 平滑：生成详细的自然外观形状，与道路末端紧密贴合。
  • 低保真度 + 平滑处理：生成宽泛的概括性“块”形状。

载荷大小和呈现

大型等时线可能包含数千个坐标，有效负载可能介于 300 到 500 千字节之间。

  • 带宽：请注意，对于最长时长的请求，JSON 响应大小非常重要。
  • 渲染：渲染极其详细的多边形会影响性能。请考虑使用 enable_smoothing 参数或客户端简化库来减少要显示的顶点数量。

错误处理

针对 5xx 服务器错误实现指数退避算法重试逻辑。不过，请勿在不更改参数的情况下重试 4xx 客户端错误：

  • INVALID_ARGUMENT (400)：检查时长是否为正值，以及是否在所选模式的限制范围内，即 DRIVE 模式下最多为 3,600 秒，其他模式下最多为 7,200 秒。
  • NOT_FOUND (404)：起点未能对准道路。尝试将坐标移近已知街道，或确保相应区域受支持。