接口概述

用于将带噪声/偏移的 GPS 轨迹（GPX 格式）匹配到数字路网中，还原真实的行驶/移动路线，解决 GPS 点位漂移、遮挡导致的轨迹不准问题。

演示demo

演示页面(由于云服务器内存不足，请尽量请求点位少一点儿) (opens new window)

基本信息

项	说明
接口路径	/match
请求方法	POST
接口版本	v1
内容类型（入参）	application/xml、application/gpx+xml（仅支持 GPX 格式轨迹）
内容类型（出参）	application/json（默认）、application/xml、application/gpx+xml
适用场景	骑行/驾车轨迹校准、物流轨迹分析、运动APP路线记录等

请求参数

1. 请求体（必传）

格式：GPX 格式 XML 文本，要求包含且仅包含 1 条轨迹（trk 节点），示例如下：

前端geojson转GPX参考 https://github.com/tyrasd/togpx/tree/master

<gpx
        xmlns="http://www.topografix.com/GPX/1/1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd" version="1.1" creator="togpx">
    <metadata/>
    <trk>
        <name></name>
        <desc></desc>
        <trkseg>
            <trkpt lat="43.90890961627511" lon="87.35277501390237"/>
            //  等等点位
            <trkpt lat="43.90615840571064" lon="87.35611235454247"/>
        </trkseg>
    </trk>
</gpx>

2. URL 查询参数（可选）

参数名	类型	默认值	说明
way_point_max_distance	double	1	轨迹简化精度（米），值越大轨迹点越少，精度越低
type	string	json	输出格式：json/gpx/xml
instructions	boolean	true	是否返回导航指令（如“左转”“直行”）
calc_points	boolean	true	是否返回轨迹点坐标
elevation	boolean	false	是否返回高程（海拔）信息
points_encoded	boolean	true	是否对轨迹点做 Polyline 编码（压缩数据体积）
locale	string	en	语言（如 zh-CN 中文、en 英文）
profile	string	无	路由配置（必填，如 car_fastest 汽车、bike_fastest 自行车、foot_fastest 步行）
path_details	list	空	路径详情字段（如 road_class 道路等级、speed 速度）
gpx.route	boolean	true	输出 GPX 时是否包含 route 节点
gpx.track	boolean	true	输出 GPX 时是否包含 track 节点
traversal_keys	boolean	false	是否返回路网边的唯一标识（traversal_keys）
gps_accuracy	double	40	GPS 点位误差范围（米），用于优化匹配精度
max_visited_nodes	int	3000	匹配时最大访问节点数（防止计算过载）

响应示例

1. JSON 格式响应

{
  "hints": {},
  "info": {
    "copyrights": [
      "gishub",
      "北京图创时代科技有限公司2019-2025 路径规划服务v13.11"
    ],
    "took": 9
  },
  "paths": [
    {
      "distance": 404.341,
      "weight": 9.223372036854775E12,
      "time": 12657,
      "transfers": 0,
      "points_encoded": false,
      "bbox": [
        87.352674,
        43.906337,
        87.356332,
        43.90884
      ],
      "points": {
        "type": "LineString",
        "coordinates": [
          [
            87.352674,
            43.90884
          ],
          [
            87.353895,
            43.907938
          ],
          [
            87.355491,
            43.906875
          ],
          [
            87.356332,
            43.906337
          ]
        ]
      },
      "instructions": [
        {
          "distance": 404.341,
          "heading": 136.12,
          "sign": 0,
          "interval": [
            0,
            3
          ],
          "text": "Continue onto 乌奎高速公路",
          "time": 12657,
          "street_name": "乌奎高速公路"
        },
        {
          "distance": 0.0,
          "sign": 4,
          "last_heading": 131.6141351195014,
          "interval": [
            3,
            3
          ],
          "text": "Arrive at destination",
          "time": 0,
          "street_name": ""
        }
      ],
      "legs": [],
      "details": {},
      "ascend": 0.0,
      "descend": 0.0,
      "snapped_waypoints": {
        "type": "LineString",
        "coordinates": []
      }
    }
  ],
  "map_matching": {
    "original_distance": 532.9837395207085,
    "distance": 404.3407542018177,
    "time": 12657
  }
}

2. GPX 格式响应

<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="gpx 1.0">
  <metadata>
    <time>2024-03-18T10:00:00Z</time>
  </metadata>
  <trk>
    <name>match-route</name>
    <trkseg>
      <trkpt lat="52.516071" lon="13.377977"><time>2024-03-18T10:00:00Z</time></trkpt>
      <trkpt lat="52.516168" lon="13.378054"><time>2024-03-18T10:00:05Z</time></trkpt>
      <trkpt lat="52.516254" lon="13.378123"><time>2024-03-18T10:00:10Z</time></trkpt>
    </trkseg>
  </tr>
</gpx>

错误响应

1. 输入GPX无轨迹

{
  "message": "No tracks found in GPX document. Are you using waypoints or routes instead?",
  "details": "Bad Request",
  "status": 400
}

2. 输入GPX多轨迹

{
  "message": "GPX documents with multiple tracks not supported yet.",
  "details": "Bad Request",
  "status": 400
}

3. 同时使用profile和legacy参数

{
  "message": "Since you are using the 'profile' parameter, do not use the 'vehicle' parameter. You used 'vehicle=car'",
  "details": "Bad Request",
  "status": 400
}

调用示例（cURL）

curl -X POST \
  http://localhost:8989/match \
  -H 'Content-Type: application/gpx+xml' \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="gpx">
  <trk>
    <name>test-track</name>
    <trkseg>
      <trkpt lat="52.516071" lon="13.377977"><time>2024-03-18T10:00:00Z</time></trkpt>
      <trkpt lat="52.516168" lon="13.378054"><time>2024-03-18T10:00:05Z</time></trkpt>
    </trkseg>
  </tr>
</gpx>' \
  -G \
  --data-urlencode 'profile=car' \
  --data-urlencode 'elevation=true' \
  --data-urlencode 'gps_accuracy=30'

注意事项

1. GPX 输入必须包含 trk 节点（轨迹），不支持仅含 wpt（单点）或 rte（路线）的 GPX；
2. profile 参数为必填项，需与服务端配置的路由配置一致（参见介绍）；
3. points_encoded=true 时，轨迹点为 Polyline 编码字符串，需解码后使用；
4. 调整 gps_accuracy 可优化匹配精度：GPS 信号差时建议增大该值（如 50-100 米）。