---
title: "Fit a GPS trace to the road network"
method: POST
path: "/map-match"
tags: ["navigation"]
---

# Fit a GPS trace to the road network

`POST /map-match`

## Request

- Base URL: `https://api.mapsource.io`
- URL: `https://api.mapsource.io/map-match`
- Auth: HTTP bearer

Returns matched geometry, confidence scores, and OSM way IDs for an ordered GPS trace.

When to use: Match recorded travel coordinates to the road network.

## Request body

- object
  - `shape` unknown[], required: The trace, in order.
    - unknown
  - `costing` string: Travel mode.
  - `shapeMatch` 'map_snap' | 'edge_walk': map_snap tolerates noise; edge_walk assumes the trace already follows the network.

## Response `200`

Fit a GPS trace to the road network

- object
  - `schema` string
  - `profile` string: The costing model that produced this result.
  - `units` object
    - `distance` string
    - `duration` string
  - `graph` object
    - `engine` string
    - `tilesetBuiltAt` string, nullable
  - `geometryAvailable` 'inline' | 'handle': Where the geometry is. handle means read geometryRef.
  - `meta` object
    - `requestId` string
    - `computeMs` integer
    - `requestedAt` string, date-time
    - `sources` object[]
      - `dataset` string
      - `observedAt` string, nullable
      - `license` string
    - `freshness` object, nullable
    - `licenses` string[]
    - `attribution` string[]
  - `confidence` number, nullable: Matching confidence from 0 to 1, or null when unavailable.
  - `geometry` object
  - `wayIds` unknown[]
    - unknown
  - `matchedPoints` unknown[]: Match status and associated network edge for each input point.
    - unknown
  - `edges` unknown[]
    - unknown

## Other responses

- `400`: Error with a stable machine code.
- `401`: Error with a stable machine code.
- `429`: Error with a stable machine code.
- `500`: Error with a stable machine code.

---

[API](https://skmtc.dev/mapsource/apis/mapsource-overpass-api.md) · [All operations](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/revisions/8af8c2769e7b?raw)