---
title: "Snap a GPS trace to roads."
method: POST
path: "/map-matching/v1"
tags: ["Routing"]
---

# Snap a GPS trace to roads.

`POST /map-matching/v1`

## Request

- Base URL: `https://api.rijwind.com`
- URL: `https://api.rijwind.com/map-matching/v1`
- Auth: HTTP bearer

Snap a noisy GPS trace to the road network and return a clean, route-shaped result — the same response envelope as `/directions/v1`. Provide the trace as a `shape` array or an `encodedPolyline`.

**Quota cost:** 1 unit per call. The `shape` array is capped at 100 points; requests beyond that return 400 without charging quota.

## Request body

- MapMatchingRequest: Snap a noisy GPS trace to the road network. Provide the trace either as a `shape` array of `(lat, lon)` points or as an `encodedPolyline` string — exactly one is required.
  - `costing` 'auto' | 'bicycle' | 'pedestrian', required: Routing profile. `auto` (car), `bicycle`, or `pedestrian` (foot).
  - `encodedPolyline` string, nullable: The GPS trace as a single encoded polyline (precision 6). An alternative to `shape` for compact transport of long traces.
  - `shape` LngLat[], nullable: The GPS trace as ordered `(lat, lon)` points. Capped at 100 points; use `encodedPolyline` for longer traces. Omit when using `encodedPolyline`.
    - `lat` number, double, required
    - `lon` number, double, required
  - `shapeMatch` string, nullable: How aggressively to snap to roads. `map_snap` (default) matches to the road network; `walk_or_snap` and `edge_walk` trade accuracy for speed on dense traces.
  - `units` 'kilometers' | 'miles'

## Response `200`

Matched route.

- RouteResponse: Route response. The interesting fields are `trip.summary` (totals) and `trip.legs[i].shape` (an encoded polyline ready to render).
  - `trip` Trip, required
    - `language` string, required
    - `legs` RouteLeg[], required
      - `maneuvers` RouteManeuver[], required
        - `beginShapeIndex` integer, required
        - `endShapeIndex` integer, required
        - `instruction` string, required
        - `length` number, double, required
        - `time` number, double, required
      - `shape` string, required: Encoded polyline at 1e-6 precision (the standard Google polyline algorithm with 6 decimals instead of 5). Decoders are available for every major language — in JavaScript, `@mapbox/polyline` with the precision set to 6 returns `[lat, lon]` pairs.
      - `summary` RouteSummary, required
        - `length` number, double, required: Total length in the requested units.
        - `maxLat` number, double, nullable
        - `maxLon` number, double, nullable
        - `minLat` number, double, nullable
        - `minLon` number, double, nullable
        - `time` number, double, required: Total travel time in seconds.
    - `status` integer, required
    - `statusMessage` string, required
    - `summary` RouteSummary, required
      - `length` number, double, required: Total length in the requested units.
      - `maxLat` number, double, nullable
      - `maxLon` number, double, nullable
      - `minLat` number, double, nullable
      - `minLon` number, double, nullable
      - `time` number, double, required: Total travel time in seconds.
    - `units` string, required

## Other responses

- `400`: Body malformed, costing unsupported, or trace exceeds 100 points.
- `401`: Missing, malformed, or revoked API key.
- `429`: Monthly quota exhausted.

---

[API](https://skmtc.dev/rijwind/apis/rijwind-api.md) · [All operations](https://skmtc.dev/rijwind/apis/rijwind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rijwind/apis/rijwind-api/revisions/01d72fb6aa4d?raw)