等时线 API 最佳实践

平滑度和保真度

您可以使用 polygon_fidelityenable_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):起点未能对准道路。尝试将坐标移近已知街道,或确保相应区域受支持。