Skip to content

Match GPS coordinates to the road network

MapMatchResult mapMatch().match(, )

POST/api/v1/map-match

Match GPS coordinates to the road network

ParametersExpand Collapse

MapMatchMatchParams params

MapMatchRequest mapMatchRequest

GPS trace to snap to the road network. Provide an array of coordinate objects representing the GPS points. Maximum 50 points per request.

ReturnsExpand Collapse

class MapMatchResult:

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.

List<Feature> features

Snapped tracepoint Features in input order

GeoJsonGeometry geometry

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

Coordinates coordinates

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

One of the following:

List<double>

List<List<double>>

List<List<List<double>>>

List<List<List<List<double>>>>

Type type

Geometry type

One of the following:

POINT("Point")

LINE_STRING("LineString")

POLYGON("Polygon")

MULTI_POINT("MultiPoint")

MULTI_LINE_STRING("MultiLineString")

MULTI_POLYGON("MultiPolygon")

Properties properties

Optional<Double> distanceM

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

Optional<Long> edgeId

Road edge ID the point was snapped to

Optional<Long> matchingsIndex

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

Optional<String> name

Road name at the snapped point

Optional<List<Double>> original

Original GPS coordinate as [lng, lat]

Optional<Long> waypointIndex

Index of this tracepoint in the original coordinates array

Type type

List<Matching> matchings

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

Type type

Match GPS coordinates to the road network

package com.plazafyi.example;

import com.plazafyi.client.PlazaClient;
import com.plazafyi.client.okhttp.PlazaOkHttpClient;
import com.plazafyi.models.mapmatch.MapMatchMatchParams;
import com.plazafyi.models.mapmatch.MapMatchRequest;
import com.plazafyi.models.mapmatch.MapMatchResult;
import java.util.List;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        PlazaClient client = PlazaOkHttpClient.fromEnv();

        MapMatchRequest params = MapMatchRequest.builder()
            .coordinates(List.of(
              MapMatchRequest.Coordinate.builder()
                  .lat(48.8566)
                  .lng(2.3522)
                  .build(),
              MapMatchRequest.Coordinate.builder()
                  .lat(48.857)
                  .lng(2.353)
                  .build(),
              MapMatchRequest.Coordinate.builder()
                  .lat(48.8575)
                  .lng(2.354)
                  .build()
            ))
            .build();
        MapMatchResult mapMatchResult = client.mapMatch().match(params);
    }
}

{
  "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"
}