# Map Match ## Match GPS coordinates to the road network `$ plaza map-match match` **post** `/api/v1/map-match` Match GPS coordinates to the road network ### Parameters - `--coordinate: array of object { lat, lng }` GPS coordinates to match, in order of travel (max 50 points) - `--radius: 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. ### Returns - `map_match_result: 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: object { 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. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: 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 - `"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"` - `"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"` - `"FeatureCollection"` ### Example ```cli plaza map-match match \ --api-key 'My API Key' \ --coordinate '{lat: 48.8566, lng: 2.3522}' \ --coordinate '{lat: 48.857, lng: 2.353}' \ --coordinate '{lat: 48.8575, lng: 2.354}' ``` #### Response ```json { "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" } ``` ## Domain Types ### Map Match Request - `map_match_request: object { coordinates, radiuses }` GPS trace to snap to the road network. Provide an array of coordinate objects representing the GPS points. Maximum 50 points per request. - `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) - `lng: number` Longitude in decimal degrees (-180 to 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. ### Map Match Result - `map_match_result: 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: object { 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. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: 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 - `"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"` - `"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"` - `"FeatureCollection"`