指南

为 GPX 路线文件添加海拔数据

用手机或基础 GPS 设备记录的 GPX 文件,其海拔值常常完全缺失或明显不准确,因为消费级 GPS 的高度读数通常远不如它记录的纬度和经度可靠。

提取轨迹点

解析 GPX 文件的轨迹点,只提取每个点的纬度和经度,并丢弃您打算替换的现有海拔值。

<trkpt lat="45.8326" lon="6.8652"><ele>1050</ele></trkpt>

查询正确的海拔

将提取出的坐标发送到 /v1/elevation:较小的文件可以使用 points 参数,较大的文件则使用批量 POST 数组。

POST /v1/elevation
Content-Type: application/json

[{"lat": 45.8326, "lon": 6.8652}, {"lat": 45.8400, "lon": 6.8700}]
{
  "status": "ok",
  "results": [
    {"lat": 45.8326, "lon": 6.8652, "elevation_m": 1035},
    {"lat": 45.8400, "lon": 6.8700, "elevation_m": 1210}
  ]
}

第二个示例:检查单个步道起点

并非每种用途都需要处理整条轨迹。在发布徒步路线介绍之前,一次调用即可确认步道起点本身的海拔。

GET /v1/elevation?lat=45.8326&lon=6.8652

这会返回结构相同、只含一个条目的结果,适合抽查步道说明中引用的起点或终点海拔数值,而无需处理整个 GPX 文件。

写回数值

结果的返回顺序与您发送的坐标顺序相同,因此按位置对应,将 elevation_m 写回每个轨迹点的 ele 标签,用查询得到的值替换原先记录的值。

<trkpt lat="45.8326" lon="6.8652"><ele>1035</ele></trkpt>

需要避免的常见错误

在同一个任务中,不要混用 points 查询参数格式和批量 POST 请求体,除非您在将结果对应回轨迹点时保持一致。points 参数和 JSON 数组都按给定顺序返回结果,但如果通过查询参数获取一个点、通过批量 POST 获取其余的点,再凭假设而不是通过明确的坐标匹配来合并两组响应,就很容易在写回的文件中引入错位一位的错误。

决定要补充多少个点

GPX 文件可能包含以很短间隔记录的数千个轨迹点。为每一个点补充数据就是每个点一次请求,在一条很长的轨迹上会累积很多。在查询海拔之前先降采样到较粗的间隔,然后在查询得到的值之间为中间的点做插值,是在减少请求数量的同时仍能生成看起来准确的剖面图的合理方法。

一个边界情况:沿海和低洼地区的点

沿海岸线下行或穿过低洼三角洲的轨迹,完全可能返回等于或接近零的 elevation_m 值,对于低于海平面的陆地,偶尔还会返回较小的负数。这两种情况都不是错误。请把接近零的值视为该地形合理的真实读数,而不要当作坏数据点过滤掉。

成本是多少

每个补充数据的点就是一次请求。一条中等长度的徒步轨迹,从大得多的原始记录降采样到几百个点后,完全在每个密钥附带的每天 2,500 次免费请求之内。

用这种方式清理海拔数据,可以把手机记录的粗糙轨迹变成值得分享或分析的数据。海拔查询文档介绍了 points 参数和批量请求格式。