Map matching

Map matching lets you snap sets of GPS points to the road network with very high accuracy. Only POST method is supported.

API endpoint

https://analytics.api.sygic.com/v1/api/matching

Parameters

To create a valid request, path OR coordinates must be included in the request.

Parameters Data type Values Descripion
path string Path is a representation of sets of GPS positions using Google polyline encoding utility. This method is more compact than listing all GPS coordinates.

Example: "path": "c~ffH}okjBeAmJ"
coordinates array of strings {latitude},{longitude} Set of GPS coordinates for map matching.

Example: "coordinates": ["48.37362,17.595033","48.37397,17.59686"]
accuracies array of decimal values Set of radiuses of uncertainty for the corresponding locations, measured in meters. This field is not required. When is omitting we will use default values for best results.

Example: "accuracies": [9.5,10]
timestamps array of integers array of UTC time Set of timestamps in seconds since midnight, January 1, 1970 UTC.

Example: "timestamps":[1464691627,1464691698]
units string array of UTC time Set of timestamps in seconds since midnight, January 1, 1970 UTC.

Example: "timestamps":[1464691627,1464691698]

The number of accuracies and timestamps must match number of coordinates.

Parameters with default value don't have to be included in the request.

Default parameter Type Default Value Description
units string metric metric
imperial
Units’ format.

Request

Example body with path:

{
    "path": "wsfxHzxsC??@FFv@EZu@~@???@aDzAKAm@HCPF^V^t@ZvFgE`KmLjEuH??NE^NNNzBz@VIjAmBiCcUcH_YuIsXaKeXyKwWgLcVoLmU",
    "accuracies": [
        9,9,10,10,10,11,11,11,11,10,11,11,11,11,11,10,10,10,10,10,10,9,11,10,11,11,11,11,11,11,11,9
    ]
}



Example body with coordinates:

{
    "coordinates": [
        "51.321075,-0.7619",
        "51.321075,-0.7619",
        "51.32107,-0.761935",
        "51.321026,-0.76222",
        "51.321056,-0.762356",
        "51.321327,-0.762678",
        "51.321327,-0.762678",
        "51.321335,-0.762686",
        "51.322136,-0.763151",
        "51.322205,-0.763136",
        "51.32243,-0.76319",
        "51.322445,-0.763276",
        "51.322407,-0.763443",
        "51.32229,-0.763601",
        "51.322025,-0.763736",
        "51.320778,-0.762741",
        "51.318855,-0.760593",
        "51.317833,-0.759043",
        "51.317833,-0.759043",
        "51.317753,-0.759006",
        "51.317585,-0.759088",
        "51.31751,-0.759166",
        "51.31689,-0.759473",
        "51.316772,-0.759421",
        "51.316387,-0.758868",
        "51.317085,-0.755328",
        "51.31854,-0.751173",
        "51.320248,-0.74707",
        "51.322178,-0.74304",
        "51.32423,-0.739085",
        "51.326355,-0.735376",
        "51.32851,-0.731793"
    ],
    "accuracies": [
        9,9,10,10,10,11,11,11,11,10,11,11,11,11,11,10,10,10,10,10,10,9,11,10,11,11,11,11,11,11,11,9
    ]
}

Response

{
    "route": "krfxHzzsC??eBnB]J[Cc@n@sAGYZEj@JLFZj@^hAOzAgAtAiAhGyGxEsGjB_D?ML_@\\AHLt@p@r@VPDh@Il@i@Xi@Pu@FyAEY}@}HY{ASaAI_@OmAaB_HeCwJ
        _@qA{B{HGWsF{PqCeIuCsHuEiL}CoHwCwGwLgWeK}R",
    "distance": {
        "value": 3349,
        "text": "3.35 km"
    },
    "status": "OK",
    "copyright": "© 2018 Sygic a.s."
}

Route format

Sygic Routing API is using Google Encoded Polyline that stores a series of coordinates into a single string. More information about Encoded Polyline can be found on this link.

Tool for visualization of the Google Encoded Polyline can be found on this link.

Make sure to always escape the backslashes in encoded strings! Not doing so will result in the backslash to be interpreted as an escape character, yielding either wrong polyline or a polyline that can't be decoded. This problem will not occur if the polylines are passed around programatically in memory.

Polyline below is encoded from two coordinates "41.6076,-88.21549","41.60745,-88.21537":

on}|FxqlyO\W

it contains characters ['o', 'n', '}', '|', 'F', 'x', 'q', 'l', 'y', 'O', '\', 'W'], therefore if used as string literal in code, it has to be declared as:

var polyline = "on}|FxqlyO\\W";


Overview

Map matching lets you snap sets of GPS points to the road network with very high accuracy.

Live Example

This example demonstrates the use of the Map matching service. Click on icons to see code on Github or play with it in JSFiddle:

  • Request

    API Reference

    https://analytics.api.sygic.com/v1/api/matching?key=yourAPIkey

    Request authentication is done via parameter key, which must be included in the request URL.

    Methods

    • POST

    Parameters

    Required Parameters

    To create a valid request, path OR coordinates must be included in the request.

    Parameter Data type Description
    path string Path is a representation of sets of GPS positions using Google polyline encoding utility. This method is more compact than listing all GPS coordinates.

    Example: "path": "c~ffH}okjBeAmJ"
    coordinates array of strings Set of GPS coordinates for map matching.

    Example: "coordinates": ["48.37362,17.595033","48.37397,17.59686"]

    Optional Parameters

    Parameter Data type Description
    accuracies array of decimal values Set of radiuses of uncertainty for the corresponding locations, measured in meters. This field is not required. When is omitting we will use default values for best results.

    Example: "accuracies": [9.5,10]
    timestamps array of integers Set of timestamps in seconds since midnight, January 1, 1970 UTC.

    Example: "timestamps":[1464691627,1464691698]
    units string Units' format. Default value is "metric".

    Values: metric, imperial

    The number of accuracies and timestamps must match number of coordinates.

    Response

    POST

    POST https://analytics.api.sygic.com/v1/api/matching?key=yourAPIkey
    
    Content-Type: application/json

    Request Body

    Example body with path:

    {
        "path": "u{ydH}dogBp@oEj@eSd@eQCqC}QeJw@sAAqANwGq@mFiFi]aFg^m@eD`AALM^kB",
        "accuracies": [9,9,10,10,9,10,9,10,11,11,9,10,10,9,9,11]
    }

    Example body with coordinates:

    {
        "coordinates": [
            "48.14283,17.12223",
            "48.14258,17.12327",
            "48.14236,17.12650",
            "48.14217,17.12941",
            "48.14219,17.13014",
            "48.14522,17.13193",
            "48.14550,17.13235",
            "48.14551,17.13276",
            "48.14543,17.13416",
            "48.14568,17.13535",
            "48.14685,17.14020",
            "48.14798,17.14520",
            "48.14821,17.14603",
            "48.14788,17.14604",
            "48.14781,17.14611",
            "48.14765,17.14665"
            ],
        "accuracies": [9,9,10,10,9,10,9,10,11,11,9,10,10,9,9,11]
    }

    Both of the above requests produce the same result.

    Response Body

    {
        "route": "s{ydH{dogB@EDQPw@Hs@XwGFmABsALgFNyEFqBH{C@mAB}A@qA@k@YOIEo@]cAg@oL_GIEi@c@a@aBBi@JmCC{CI}@DSOyAOu@Yo@G_@Ga@]{BKm@s@aFIg@My@i@kDo@mE_@_Ce@gD]{BEW_@uB[oBM{@CU_AaHSwAhAKJ]ZmA",
        "status": "OK",
        "distance": {
            "value": 2130,
            "text": "2.13 km"
        },
        "copyright": "© 2018 Sygic a.s."
    }