Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Map Match

Match GPS coordinates to the road network

POST/api/v1/map-match

Match GPS coordinates to the road network

Body ParametersJSONExpand Collapse
coordinates: array of object { lat, lng }

GPS coordinates to match, in order of travel (max 50 points)

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
radiuses: optional array of number

Search radius per coordinate in meters. Must have the same length as coordinates or be omitted entirely. Default: 50m per point.

ReturnsExpand Collapse
MapMatchResult = object { features, matchings, type }

Map matching result as a GeoJSON FeatureCollection. Each Feature is a snapped tracepoint. The top-level matchings array contains the matched sub-routes connecting consecutive tracepoints.

features: array of object { geometry, properties, type }

Snapped tracepoint Features in input order

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Point = array of number

[longitude, latitude] or [longitude, latitude, elevation]

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = array of array of array of number

Array of linear rings / line strings

MultiPolygon = array of array of array of array of number

Array of polygons

type: "Point" or "LineString" or "Polygon" or 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: object { distance_m, edge_id, matchings_index, 3 more }
distance_m: optional number

Distance from the original GPS point to the snapped point in meters

edge_id: optional number

Road edge ID the point was snapped to

matchings_index: optional number

Index into the matchings array indicating which matching sub-route this point belongs to

name: optional string

Road name at the snapped point

original: optional array of number

Original GPS coordinate as [lng, lat]

waypoint_index: optional number

Index of this tracepoint in the original coordinates array

type: "Feature"
matchings: array of map[unknown]

Matched sub-routes. Each matching connects a contiguous sequence of tracepoints that could be matched to roads.

type: "FeatureCollection"

Match GPS coordinates to the road network

curl https://plaza.fyi/api/v1/map-match \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PLAZA_API_KEY" \
    -d '{
          "coordinates": [
            {
              "lat": 48.8566,
              "lng": 2.3522
            },
            {
              "lat": 48.857,
              "lng": 2.353
            },
            {
              "lat": 48.8575,
              "lng": 2.354
            }
          ]
        }'
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "distance_m": 0,
        "edge_id": 0,
        "matchings_index": 0,
        "name": "name",
        "original": [
          0,
          0
        ],
        "waypoint_index": 0
      },
      "type": "Feature"
    }
  ],
  "matchings": [
    {
      "foo": "bar"
    }
  ],
  "type": "FeatureCollection"
}
Returns Examples
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "distance_m": 0,
        "edge_id": 0,
        "matchings_index": 0,
        "name": "name",
        "original": [
          0,
          0
        ],
        "waypoint_index": 0
      },
      "type": "Feature"
    }
  ],
  "matchings": [
    {
      "foo": "bar"
    }
  ],
  "type": "FeatureCollection"
}