主要概念

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

出行方式

使用必需的 travelMode (travel_mode) 参数指定交通方式：

• DRIVE：使用公布的限速、道路层级、转弯惩罚和（可选）实时路况信息，计算轿车沿可行驶道路的可达性。
• TWO_WHEELER：使用特定于模式的道路通行规则以及低于 DRIVE 的高速公路建模速度，计算两轮机动车（例如摩托车或踏板车）的可达性。因此，TWO_WHEELER 等时线通常覆盖的区域大于 BICYCLE，但小于沿高速公路的 DRIVE。
• BICYCLE：计算骑行者沿自行车可通行街道、自行车道和共用道路的可达性，并根据道路类型和坡度调整速度，不包括高速公路和管制出入的高速公路。
• WALK：计算行人沿人行道、小径、步道和行人可通行街道的可达性，并根据坡度调整步行速度。步行遍历会忽略单向车辆限制。

时间范围

您向服务提供的主要限制条件是 travelDuration (travel_duration)。这定义了计算的时间范围。

• 时长下限和上限：时长必须至少为 "1s"（1 秒）。零 ("0s")、负时长和小于 1 秒的亚秒级时长（例如 "0.5s"）会返回 400 INVALID_ARGUMENT 错误。该 API 支持 DRIVE 和 TWO_WHEELER 模式下的最长行程时间为 3,600 秒（1 小时），WALK 和 BICYCLE 模式下的最长行程时间为 7,200 秒（2 小时）。
• 最小多边形下限：由于 API 会将到达的路段转换为空间网格单元，因此非常短的时长会返回一个覆盖吸附起点周围网格单元的小多边形。
• 性能：计算时间会根据请求的时长和所选的出行方式而变化。一小时驾车等时线覆盖的地理区域和路网明显大于一小时步行等时线，这会导致驾车请求的延迟时间更长。
• 格式设置：由于 API 使用 google.protobuf.Duration，因此时长必须设置为以 "s" 结尾的字符串（例如 "3600s"），而不是整数。

起点和道路吸附

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

• 坐标 (location)：纬度和经度对。同时提供 latitude（以 [-90, 90] 为单位）和 longitude（以 [-180, 180] 为单位）。如果您省略其中一个，API 会将其视为 0.0，从而将该点置于赤道或本初子午线上。如果您同时省略了这两者 ({}) 或发送了 (0, 0)，API 会返回 400 INVALID_ARGUMENT 错误。
• 地点 ID (place)：Google 地图上特定地点的唯一标识符。当您提供地点 ID 时，该服务会将地点解析为其形心坐标，并将该点吸附到最近的道路。使用以 places/ 开头的资源名称格式（例如 places/ChIJIQBpAG2ahYAR_6128GcTUEo）；不带 places/ 前缀的裸地点 ID 也可以接受。如需详细了解地点 ID，请参阅地点 ID。

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

• 智能贴靠：服务会尝试将起点贴靠到最近的可通行路段。
• 模式感知：贴靠逻辑会考虑您的 travel_mode。如果您请求 DRIVE 或 TWO_WHEELER，API 会忽略仅限行人通行的道路，并寻找最近的可驾车街道。如果您请求 WALK，该 API 会优先考虑可步行的路径和人行道。
• 失败情况：如果 API 在起点最大吸附距离（约 200 米，WALK 和 BICYCLE 的距离更短）内找不到合适的路段，则会返回 404 NOT_FOUND 错误。大型地貌（例如公园、园区或观景台）的地点 ID 形心可能超出与出行方式可用的最近道路之间的贴靠距离；在这种情况下，请改为传递道路入口的显式 location 坐标。

通行方向（入站与出站）

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

• FROM（去程）：计算在指定时间限制内从起点可到达的区域。这适用于自送区域或服务覆盖范围等应用场景。
• TO（入界）：计算在指定时间限制内，您可以从哪些区域前往起点。这适用于确定集水区，例如员工可以从哪里通勤到中央办公室。

流量感知

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

• TRAFFIC_UNAWARE（默认）：使用自由流速度限制和道路层级生成等时线多边形。这会产生一个确定性的形状，不会根据一天中的时间而波动。此参数非常适合进行一般分析或基准情景方案规划。
• TRAFFIC_AWARE：使用处理请求时的实时路况信息计算等时线（在 v1 中，无法配置自定义的未来或历史出发/到达时间戳）。这会导致可达区域在拥堵期间缩小，在非高峰时段扩大；在自由流动或非高峰时段，TRAFFIC_AWARE 和 TRAFFIC_UNAWARE 可能会返回几乎相同的多边形。注意：仅当 travelMode 设置为 DRIVE 或 TWO_WHEELER 时，才支持考虑路况的路线规划。

平滑度和保真度

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

• polygonFidelity：控制用于近似可达边界的空间网格单元分辨率：

  • LOW：使用最大的网格单元（跨度为几百米）。 最适合用较少的顶点覆盖大面积区域，且内部没有间隙，从而形成一个概括性的形状，这可能会高估沿狭窄道路走廊的可达区域。
  • MEDIUM：平衡精度和顶点数。
  • HIGH：使用最小的网格单元格（大约 100-150 米宽）。这样可以更紧密地贴合所到达的道路网络，但在道路网络稀疏的地方可能会产生内部空洞。
  • POLYGON_FIDELITY_UNSPECIFIED：如果未指定，服务会根据出行方式和时长自动选择分辨率，对于短时长和 WALK 使用更精细的单元格，对于长时长使用更粗略的单元格。如需比较不同时长或出行方式的等时线，请明确设置 polygonFidelity。

    

• enableSmoothing：控制是否对保真度定义的网格单元格的阶梯边缘进行圆角处理。

  • false（原始）：默认值。返回网格对齐的边界。边缘沿网格单元呈阶梯状。最适合分析准确性，例如严格的点在多边形内测试。
  • true（平滑）：对尖角进行圆角处理，以便在地图上直观显示，同时大致保留每个环的面积。边界不再遵循网格单元。