Synchronous Snap to Roads

Service version: 1

Last edit: 2022.12.19

Purpose

The Synchronous Snap to Roads endpoint provides detailed information of a reconstructed road in an efficient way. The Snap to Roads endpoint matches the received points to the map road network and reconstructs the driven road. Points given as input to the Snap to Roads endpoint are related to themselves and are a part of the same route from the same client.

The matching algorithm chooses the driven road fitting to all of the given points, or in case of a few possibilities takes into account additional restrictions provided by the client. This endpoint can also provide extended data related to a matched route. This endpoint can be used for:

Reconstructing the driven road and getting the detailed insights for it.
Providing innovative information in order to build applications with advanced map data.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer and follow the directions.

Request data

HTTPS method: `GET`

For ease of viewing and identification:

Constants and parameters enclosed in curly brackets { } must be replaced with their values.
Please see the following GET request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

GET

URL request format

https://{baseURL}/snapToRoads/{versionNumber}?key={Your_API_Key}&points={longitude,latitude...}&headings={string}&timestamps={string}&fields={string}&vehicleType={string}&measurementSystem={string}

GET

URL request example (only speed limits)

https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={route{properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto

GET

curl command request example (only speed limits)

curl 'https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={route{properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto'

GET

URL request example (projected points and road elements with geometry, speed limits, and IDs)

https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50

GET

curl command request example (projected points and road elements with geometry, speed limits, and IDs)

curl 'https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629<&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50'

GET

URL request example (all possible data))

https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,linearReference,speedLimits{value,unit,type},speedProfile{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},maximumDimensions{height{value,unit},length{value,unit},width{value,unit},totalWeight{value,unit},weightPerAxle{value,unit}},traveledDistance{value,unit},privateRoad,partOfTunnel,urbanArea,elementType,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage,unit},trafficSigns{signType,chainage,unit},trafficLight,confidence,emissionRegulations{restrictionType,emissionClass,engineType}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad,unit}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50

GET

curl command request example (all possible data)

curl 'https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&points=4.6104919036936565,52.37576529649988;4.614096792595859,52.38341473290629&headings=0;0&timestamps=2021-01-01T00:00:00Z;2021-01-01T00:01:00Z&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit,type},speedProfile{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},maximumDimensions{height{value,unit},length{value,unit},width{value,unit},totalWeight{value,unit},weightPerAxle{value,unit}},traveledDistance{value,unit},privateRoad,partOfTunnel,urbanArea,elementType,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage,unit},trafficSigns{signType,chainage,unit},trafficLight,confidence,emissionRegulations{restrictionType,emissionClass,engineType}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad,unit}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50'

GET request parameters

The following table describes the parameters that can be used in a request.

Required parameters must be used or the call will fail.
Parameters and values are case-sensitive.
Optional parameters may be used.

Required parameters	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`versionNumber` string	The version of the service to call. Value: The current value is `1`.
`key` string	The authorization key for access to the API. Value: Your valid `API Key`.
`points` float,float	Semicolon separated list of points. Each must have a longitude and a latitude field separated by a comma. Longitude and latitude must be calculated using EPSG:4326 projection (also known as WGS84 ). The maximum allowed number of points in a request is `5000` while the minimum is `2`. The maximum road distance between two consecutive points cannot exceed 6000 meters. Value: `longitude,latitude;...`

Optional parameters	Description
`headings` string	A semicolon-separated list indicating the direction of movement. If provided, the heading will be taken into account by the map matching algorithm. The number of headings must be the same as the number of points. It is possible to skip the heading value for a given point by leaving it blank (see example ). The heading value is represented in degrees, `0` is North, `90` is East, etc. Default value: `none` Allowed values: `0..360`
`timestamps` string	A semicolon-separated list indicating the timestamps of obtained points. If provided, the timestamp will be taken into account by the matching algorithm to determine end time of selected restrictions. The number of timestamps must be the same as the number of points. It is possible to skip the timestamp value for a given point by leaving it blank (see example ). The timestamp value must be compliant with ISO 8601 date and time format.
`fields` string	The fields to be included in the response, nested as in the response schema. In order to obtain all of the data, it is necessary to place the whole object in the query (see below). An empty object (empty `{ }` ) in a `fields` string is treated as a malformed request. Default value: `{route{{geometry{coordinates}}}` Value needed to obtain all data - JSON 1{ 2 projectedPoints{ 3 type, 4 geometry{ 5 type, 6 coordinates 7 }, 8 properties{ 9 routeIndex, 10 snapResult 11 } 12 }, 13 route{ 14 type, 15 geometry{ 16 type, 17 coordinates 18 }, 19 properties{ 20 id, 21 linearReference, 22 speedLimits{ 23 value, 24 unit, 25 type 26 }, 27 speedProfile{ 28 value, 29 unit 30 }, 31 address{ 32 roadName, 33 roadNumbers, 34 municipality, 35 countryName, 36 countryCode, 37 countrySubdivision 38 }, 39 maximumDimensions{ 40 height{ 41 value, 42 unit 43 }, 44 length{ 45 value, 46 unit 47 }, 48 width{ 49 value, 50 unit 51 }, 52 totalWeight{ 53 value, 54 unit 55 }, 56 weightPerAxle{ 57 value, 58 unit 59 } 60 }, 61 traveledDistance{ 62 value, 63 unit 64 }, 65 privateRoad, 66 partOfTunnel, 67 urbanArea, 68 elementType, 69 frc, 70 formOfWay, 71 roadUse, 72 laneInfo{ 73 numberOfLanes 74 }, 75 heightInfo{ 76 height, 77 chainage, 78 unit 79 }, 80 trafficSigns{ 81 signType, 82 chainage, 83 unit 84 }, 85 trafficLight, 86 confidence, 87 emissionRegulations { 88 restrictionType, 89 emissionClass, 90 engineType 91 } 92 } 93 }, 94 distances{ 95 total, 96 ferry, 97 road, 98 privateRoad, 99 publicRoad, 100 offRoad, 101 unit 102 } 103}
`vehicleType` string	It can contribute to a more accurate road identification by possibly excluding roads that are not suited for a given value. If the `Emergency` value is given, no roads are excluded. Default value: `PassengerCar` Allowed values: `PassengerCar` `Bus` `Truck` `Emergency` `Taxi`
`measurementSystem` string	Indicates the measurement system in which the client requests data. If `auto` is set, the measurement system is detected based on the location of the first matched road. For example, if the first matched road element is located in the USA, then values are given in the imperial measurement system where applicable. Default value: `auto` Allowed values: `auto` `metric` `imperial`
`offroadMargin` float	It can contribute to detect an offroad movement of the vehicle. Any input point being further (from any road segment) than this value is considered as an offroad point. Default value: `50` (metric) or `164` (imperial) Allowed values: `metric: from 20 to 100` `imperial: from 66 to 328`

HTTPS method: `POST`

For ease of viewing and identification:

Constants and parameters enclosed in curly brackets must be replaced with their values.
Please see the following POST request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

POST

URL request format

https://{baseURL}/snapToRoads/{versionNumber}?key={Your_API_Key}&fields={string}&vehicleType={string}&measuremenSystem={string}

POST

URL request example (only speed limits)

https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&fields={route{properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto

POST
curl command request example (only speed limits)
1curl -X POST 'https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&fields={route{properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto' -d '{
2"points": [
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6104919036936565,52.37576529649988]
    },
    "properties": {
      "heading": 0
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.614096792595859,52.38341473290629]
    },
    "properties": {
      "heading": 0
    }
  }
]
24}'

POST

URL request example (projected points and road elements with geometry, speed limits, and IDs)

https://api.tomtom.com/snapToRoads/1?key={Your_API_Key}&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto

POST
curl command request example (projected points and road elements with geometry, speed limits, and IDs)
1curl -X POST 'https://api.tomtom.com/snapToRoads/1?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit,type}}}}&vehicleType=PassengerCar&measurementSystem=auto' -d '{
2"points": [
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6104919036936565,52.37576529649988]
    },
    "properties": {
      "heading": 0
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.614096792595859,52.38341473290629]
    },
    "properties": {
      "heading": 0
    }
  }
]
24}'

POST

URL request example (all possible data)

https://api.tomtom.com/snapToRoads/1?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,linearReference,speedLimits{value,unit,type},speedProfile{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},maximumDimensions{height{value,unit},length{value,unit},width{value,unit},totalWeight{value,unit},weightPerAxle{value,unit}},elementType,traveledDistance{value,unit},privateRoad,partOfTunnel,urbanArea,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage,unit},trafficSigns{signType,chainage,unit},trafficLight,confidence,emissionRegulations{restrictionType,emissionClass,engineType}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad,unit}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50

POST
curl command request example (all possible data)
1curl -X POST 'https://api.tomtom.com/snapToRoads/1?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,linearReference,speedLimits{value,unit,type},speedProfile{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},maximumDimensions{height{value,unit},length{value,unit},width{value,unit},totalWeight{value,unit},weightPerAxle{value,unit}},elementType,traveledDistance{value,unit},privateRoad,partOfTunnel,urbanArea,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage,unit},trafficSigns{signType,chainage,unit},trafficLight,confidence,emissionRegulations{restrictionType,emissionClass,engineType}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad,unit}}&vehicleType=PassengerCar&measurementSystem=auto&offroadMargin=50' -d '
2{
3"points": [
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6104919036936565,52.37576529649988]
    },
    "properties": {
      "heading": 0
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.614096792595859,52.38341473290629]
    },
    "properties": {
      "heading": 0
    }
  }
]
25}'

POST request parameters

The following table describes the parameters that can be used in a request.

Required parameters must be used or the call will fail.
Parameters and values are case-sensitive.
Optional parameters may be used.

Required parameters	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`versionNumber` string	The version of the service to call. Value: The current value is `1`.
`key` string	The authorization key for access to the API. Value: Your valid `API Key`.

Optional parameters Description

Optional parameters	Description
`fields` string	The fields to be included in the response, nested as in the response schema. In order to obtain all data, it is necessary to place the whole object in the query (see below). An empty object (empty `{ }` ) in a `fields` string is treated as a malformed request. Default value: `{route{geometry{coordinates}}}` Value needed to obtain all data - JSON 1{ 2 projectedPoints{ 3 type, 4 geometry{ 5 type, 6 coordinates 7 }, 8 properties{ 9 routeIndex, 10 snapResult 11 } 12 }, 13 route{ 14 type, 15 geometry{ 16 type, 17 coordinates 18 }, 19 properties{ 20 id, 21 linearReference, 22 speedLimits{ 23 value, 24 unit, 25 type 26 }, 27 speedProfile{ 28 value, 29 unit 30 }, 31 address{ 32 roadName, 33 roadNumbers, 34 municipality, 35 countryName, 36 countryCode, 37 countrySubdivision 38 }, 39 maximumDimensions{ 40 height{ 41 value, 42 unit 43 }, 44 length{ 45 value, 46 unit 47 }, 48 width{ 49 value, 50 unit 51 }, 52 totalWeight{ 53 value, 54 unit 55 }, 56 weightPerAxle{ 57 value, 58 unit 59 } 60 }, 61 traveledDistance{ 62 value, 63 unit 64 }, 65 privateRoad, 66 partOfTunnel, 67 urbanArea, 68 elementType, 69 frc, 70 formOfWay, 71 roadUse, 72 laneInfo{ 73 numberOfLanes 74 }, 75 heightInfo{ 76 height, 77 chainage, 78 unit 79 }, 80 trafficSigns{ 81 signType, 82 chainage, 83 unit 84 }, 85 trafficLight, 86 confidence, 87 emissionRegulations { 88 restrictionType, 89 emissionClass, 90 engineType 91 } 92 } 93 }, 94 distances{ 95 total, 96 ferry, 97 road, 98 privateRoad, 99 publicRoad, 100 offRoad, 101 unit 102 } 103}
`vehicleType` string	It can contribute to a more accurate road identification by possibly excluding roads that are not suited for the given value. If the `Emergency` value is given, no roads are excluded. Default value: `PassengerCar` Allowed values: `PassengerCar` `Bus` `Truck` `Emergency` `Taxi`
`measurementSystem` string	Indicates the measurement system in which a client requests data. Default value: `metric` Allowed values: `metric` `imperial`

fields
string

The fields to be included in the response, nested as in the response schema.

In order to obtain all data, it is necessary to place the whole object in the query (see below).
An empty object (empty { } ) in a fields string is treated as a malformed request.

Default value: {route{geometry{coordinates}}}

Value needed to obtain all data - JSON

1{
projectedPoints{
  type,
  geometry{
    type,
    coordinates
  },
  properties{
    routeIndex,
    snapResult
  }
},
route{
  type,
  geometry{
    type,
    coordinates
  },
  properties{
    id,
    linearReference,
    speedLimits{
      value,
      unit,
      type
    },
    speedProfile{
      value,
      unit
    },
    address{
      roadName,
      roadNumbers,
      municipality,
      countryName,
      countryCode,
      countrySubdivision
    },
    maximumDimensions{
      height{
        value,
        unit
      },
      length{
        value,
        unit
      },
      width{
        value,
        unit
      },
      totalWeight{
        value,
        unit
      },
      weightPerAxle{
        value,
        unit
      }
    },
    traveledDistance{
      value,
      unit
    },
    privateRoad,
    partOfTunnel,
    urbanArea,
    elementType,
    frc,
    formOfWay,
    roadUse,
    laneInfo{
      numberOfLanes
    },
    heightInfo{
      height,
      chainage,
      unit
    },
    trafficSigns{
      signType,
      chainage,
      unit
    },
    trafficLight,
    confidence,
    emissionRegulations {
      restrictionType,
      emissionClass,
      engineType
    }
  }
},
distances{
  total,
  ferry,
  road,
  privateRoad,
  publicRoad,
  offRoad,
  unit
}
103}

vehicleType
string

It can contribute to a more accurate road identification by possibly excluding roads that are not suited for the given value. If the Emergency value is given, no roads are excluded.
Default value: PassengerCar
Allowed values:

PassengerCar
Bus
Truck
Emergency
Taxi

measurementSystem
string

Indicates the measurement system in which a client requests data.
Default value: metric
Allowed values:

metric
imperial

Request body

Follow the request body schema in order to prepare a valid POST request. The maximum size of the HTTP POST request body is 10 MB.

Request schema

An exclamation mark ! means that this field is required.

POST
POST body request schema - JSON
1{
type Query {
    points: [Point!]!
}
type Point {
    type: GeojsonFeatureType!
    geometry: GeojsonPoint!
    properties: Properties
}
type GeojsonPoint {
    type: GeojsonPointType!
    coordinates: [Float!]!
}
type Properties {
    heading: Float
    timestamp: String
}
enum GeojsonPointType {
    Point
}
enum GeojsonFeatureType {
    Feature
}
24}

Fields of the request body

Structure of the root object
`points` object	The list of points. Each of them must have a geometry field and may have a properties field. It should contain at least `2` points and at most `5000` points.

Structure of the root object

Field Description

points
object

The list of points.

Each of them must have a geometry field and may have a properties field.
It should contain at least 2 points and at most 5000 points.

Structure of the point object
Field	Description
`type` string	The value is always set as `Feature`.
`geometry` object	This is a GeoJSON object type which must contain the `type` and `coordinates` fields.
`properties` object	It may contain data in order to increase the likelihood of correctly snapping the point.

Structure of the geometry object
Field	Description
`type` string	The value is always set as a `Point`.
`coordinates` array	It must contain exactly two numbers which represent the longitude and latitude of the point.

Structure of the properties object
`heading` float	The directional heading of the vehicle in degrees for travel along a segment of roadway. It is represented in degrees, `0` is North, `90` is East, and so on. Values range `-360..360`.
`timestamp` string	The timestamp of obtained point. If provided, the timestamp will be taken into account by the matching algorithm to determine end time of selected restrictions. The timestamp value must be compliant with ISO 8601 date and time format.

Structure of the properties object

Field Description

heading
float

The directional heading of the vehicle in degrees for travel along a segment of roadway.

It is represented in degrees, 0 is North, 90 is East, and so on.
Values range -360..360.

timestamp
string

The timestamp of obtained point.

If provided, the timestamp will be taken into account by the matching algorithm to determine end time of selected restrictions.
The timestamp value must be compliant with ISO 8601 date and time format.

POST
POST request body example - JSON
1{
"points": [
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6104919036936565, 52.37576529649988]
    },
    "properties": {
      "heading": 0,
      "timestamp": "2021-01-01T12:00:00Z"
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.614096792595859, 52.38341473290629]
    },
    "properties": {
      "heading": 0,
      "timestamp": "2021-01-01T12:00:01Z"
    }
  }
]
26}

HTTP request headers

The following table lists HTTP request headers of particular interest to clients of the Synchronous Snap to Roads endpoint.

Note: There are no required headers in this endpoint.

Optional headers Description

Optional headers	Description
Accept-Encoding	Contains the content encoding (usually a compression algorithm), that the client is able to understand. Value: `gzip`
Tracking-ID	Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression `'^[a-zA-Z0-9-]{1,100}$'`. An example of the format that matches this regular expression is a UUID (e.g., `9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1` ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `<string>`

Accept-Encoding

Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip

Tracking-ID

Specifies an identifier for the request.

It can be used to trace a call.
The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122.
If specified, it is replicated in the Tracking-ID response header.
It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: <string>

Response data

Successful response

For a single valid request, the Synchronous Snap to Roads endpoint returns its response body in JSON format. The fields that appear in the JSON response depend on the value of the fields request parameter. By default, the client only gets the geometry of projected points.

Response schema

Exclamation mark ! means that the field is not nullable. For example:

Point! - is non-nullable
[Point!] - list of non-null objects
[Point]! - list cannot be null, but it can contain null values

POST
Response schema
1{
union AnyElement = RoadElement | FerryElement
type Query {
    projectedPoints: [ProjectedPoint!]!
    route: [AnyElement!]!
    distances: Distances!
}
8
type Distances {
    total: Int!
    ferry: Int!
    road: Int!
    privateRoad: Int!
    publicRoad: Int!
    offRoad: Int!
    unit: DistanceUnit!
}
18
type ProjectedPoint {
    type: GeojsonFeatureType!
    geometry: GeojsonPoint
    properties: ProjectedPointProperties!
}
24
type ProjectedPointProperties {
    routeIndex: Int
    snapResult: String!
}
29
type FerryElement {
    type: GeojsonFeatureType!
    geometry: GeojsonLinestring!
    properties: FerryElementProperties!
}
35
type RoadElement {
    type: GeojsonFeatureType!
    geometry: GeojsonLinestring!
    properties: RoadElementProperties!
}
41
type RoadElementProperties {
    id: String!
    linearReference: String!
    address: RoadAddress!
    maximumDimensions:MaximumDimension
    speedLimits: SpeedLimit
    speedProfile: SpeedProfile
    elementType: ElementType!
    frc: Int!
    formOfWay: String
    roadUse: String
    laneInfo: LaneInfo!
    traveledDistance: Distance!
    privateRoad: bool!
    partOfTunnel: bool!
    urbanArea: bool!
    heightInfo: [HeightInfo!]!
    trafficSigns: [TrafficSign!]!
    trafficLight: String
    confidence: Float!
    emissionRegulations: [EmissionRegulation!]
}
64
type FerryElementProperties {
    id: String!
    linearReference: String!
    address: FerryAddress!
    maximumDimensions:MaximumDimension
    elementType: ElementType!
    frc: Int!
    traveledDistance: Distance!
    privateRoad: bool!
    partOfTunnel: bool!
    urbanArea: bool!
    confidence: Float!
}
78
type LaneInfo {
    numberOfLanes: Int
}
82
type Distance {
    value: Int!
    unit: DistanceUnit!
}
87
type SpeedLimit {
    value: Int!
    unit: SpeedUnit!
    type: String!
}
93
type SpeedProfile {
    value: Int!
    unit: SpeedUnit!
}
98
type FerryAddress {
    roadName: String
    roadNumbers: [String!]!
}
103
type RoadAddress {
    roadName: String
    roadNumbers: [String!]!
    municipality: String
    countryName: String
    countryCode: String
    countrySubdivision: String
}
112
type MaximumDimension {
    height : Dimension
    length : Dimension
    width : Dimension
    totalWeight : Dimension
    weightPerAxle : Dimension
}
120
type Dimension {
  value : Int!
  unit : String!
}
125
type HeightInfo {
    height: Int!
    chainage: Int!
    unit: DistanceUnit!
}
131
type TrafficSign {
  signType: String!
  chainage: Int!
  unit: DistanceUnit!
}
137
type EmissionRegulation {
  restrictionType: String!
  emissionClass : [Int!]!
  engineType: [EngineType!]!
}
143
enum EngineType {
  LPG,
  CNG,
  LNG,
  Diesel,
  Petrol,
  Hydrogen,
  Electric,
  Hybrid,
  Plugin Hybrid
}
155
enum DistanceUnit {
  cm,
  m,
  ft
}
161
enum SpeedUnit {
    kmph,
    mph
}
166
enum ElementType {
    Road,
    Ferry
}
171
type GeojsonPoint {
    type: GeojsonPointType!
    coordinates: [Float!]!
}
176
type GeojsonLinestring {
    type: GeojsonLinestringType!
    coordinates: [[Float!]!]!
}
181
enum GeojsonLinestringType {
    LineString
}
185
enum GeojsonPointType {
    Point
}
189
enum GeojsonFeatureType {
    Feature
}
193}

Response field structure

The following tables describe JSON element fields that can appear in a response.

Structure of the root object
Field	Description
`projectedPoints` array	The list of the points projected on the road network which relates to the points from a request. Each object in this array corresponds to a particular point in the query. The order of objects in this array is the same as the order of the points from the query.
`route` array	The list of road elements forming the reconstructed route.
`distances` Distances	The traveled distance within the road segment or on the ferry in meters or feet depending on the chosen measurement system.

Structure of the ProjectedPoint object
Field	Description
`type` string	The value is set as `Feature` ( GeoJSON feature object).
`geometry` object	A GeoJSON feature of type `Point`. It always contains the `type` and `coordinates` fields. It is a projection of a request point on a particular matched road element. If the value is equal to `null`, it means that it is not possible to project a point because it is not able to be matched to any road element.
`properties` object	They contain information about a point.

Structure of the ProjectedPointProperties object
`routeIndex` integer	The index of a matching road element from the `route` array. It can be equal to `null` if a point is not able to be matched (see `snapResult` ) to any road element.
`snapResult` string	Stores the result given by the matching algorithm. Allowed values: Matched OffRoad MaxDistanceExceeded

Structure of the ProjectedPointProperties object

Field Description

routeIndex
integer

The index of a matching road element from the route array. It can be equal to null if a point is not able to be matched (see snapResult ) to any road element.

snapResult
string

Stores the result given by the matching algorithm.
Allowed values:

Matched
OffRoad
MaxDistanceExceeded

Structure of the FerryElement object
Field	Description
`type` string	The value is set as `Feature` ( GeoJSON feature object).
`geometry` object	A GeoJSON feature of type LineString. It always contains the `type` and `coordinates` fields.
`properties` object	Detailed information about the ferry element.

Structure of the RoadElement object
Field	Description
`type` string	The value is set as `Feature` ( GeoJSON feature object).
`geometry` object	A GeoJSON feature of type LineString. It always contains the `type` and `coordinates` fields.
`properties` object	Detailed information about the road element.

Structure of the FerryElementProperties object
Field	Description
`id` string	Unique ID of the ferry element.
`linearReference` string	Base64 encoded location reference expressed in OpenLR format. OpenLR is a method for map agnostic location. It enables systems to communicate location information when they use dissimilar maps.
`address` object	Address information relevant to the ferry element.
`maximumDimensions` object	Information about the maximum dimensions of a vehicle allowed to use this road.
`elementType` string	Type of the element. Allowed value: Ferry
`frc` integer	FRC (Functional Road Class) represents a classification of roads based on the importance that the constituting roads have in the road network. Allowed values (if applicable): `0..8`
`traveledDistance` object	The traveled distance within the ferry segment in meters or feet depending on the chosen measurement system.
`privateRoad` boolean	Ferry element ownership. Allowed values: `true` `false`
`partOfTunnel` boolean	Ferry element that is a part of a tunnel. Allowed values: `true` `false`
`urbanArea` boolean	Ferry element that is a part of an urban area. Allowed values: `true` `false`
`confidence` float	It represents the algorithm's confidence for the given ferry element. It's a float from the range (0,1].
`emissionRegulations` float	It provides information about the restriction (Ban or Fee) for a vehicle with a particular type of pollution emission according to a standard emission scheme.

Structure of the RoadElementProperties object
Field	Description
`id` string	Unique ID of the road element.
`linearReference` string	Base64 encoded location reference expressed in OpenLR format. OpenLR is a method for map agnostic location. It enables systems to communicate location information when they use dissimilar maps.
`speedLimits` object	Speed limits for a given `vehicleType`. If timestamps are NOT provided, then all available speed limits are taken into account by the matching algorithm. If timestamps are provided, then only speed limits matching the provided timeframe are taken into account by the matching algorithm.
`speedProfile` object	Speed profile represented as average speed in a given road segment in a given timeframe. The time frame is calculated from a GPS point timestamp which must be present for at least the first GPS point.
`address` object	Address information relevant to the road element.
`maximumDimensions` object	Information about the maximum dimensions of a vehicle allowed to use this road.
`elementType` string	Type of the element. Allowed value: Road
`frc` integer	FRC (Functional Road Class) represents a classification of roads based on the importance that the constituting roads have in the total road network. Allowed values (if applicable): `0..8`
`formOfWay` string	Form of way represents the physical form of a road. This is based on a number of certain physical characteristics and traffic properties. Allowed values (if applicable): DualCarriageway SingleCarriageway Roundabout MajorSlipRoad ParallelRoad RoadForAuthorities EntranceToOrExitFromACarPark SmallSlipRoad RoadInEnclosedTrafficArea RoadInPedestrianZone ServiceRoad ETAParkingArea SpecialTrafficFigure SmallMajorSlipRoad ETAParkingBuilding Walkway Stairs CulDeSac ETAGallery Connector Unknown
`roadUse` string	It specifies how the road element is used for travel. Allowed values: LimitedAccess Arterial Terminal Ramp Rotary LocalStreet
`laneInfo` string	Lane Information refers to the collection of lane-related information stored in a Road Element.
`traveledDistance` object	The traveled distance within the road segment in meters or feet depending on the chosen measurement system.
`privateRoad` boolean	Road element ownership. Allowed values: `true` `false`
`partOfTunnel` boolean	Road element is a part of a tunnel. Allowed values: `true` `false`
`urbanArea` boolean	Road element is a part of an urban area. Allowed values: `true` `false`
`heightInfo` HeightInfo	Information about the road element's height.
`trafficSigns` TrafficSign	Information about traffic signs along the traveled road.
`trafficLight` string	Position of a traffic light on the route segment. Allowed values: `Start` `End` `Both`
`confidence` float	It represents the algorithm's confidence for the given road element. It's a float from the range (0,1].
`emissionRegulations` float	It provides information about the restriction (Ban or Fee) for a vehicle with a particular type of pollution emission according to a standard emission scheme.

Structure of the FerryAddress object
Field	Description
`roadName` string	Road name in NGT format.
`roadNumbers` array of strings	The list of road numbers.

Structure of the RoadAddress object
Field	Description
`roadName` string	Road name in NGT format.
`roadNumbers` array of strings	The list of road numbers.
`municipality` string	City name in NGT format.
`countryName` string	Country name in NGT format.
`countryCode` string	ISO 3166-1 alpha-3 country code.
`countrySubdivision` string	State or province name in NGT format.

Structure of the MaximumDimension object
Field	Description
`height` Dimension	Maximum height of a vehicle.
`length` Dimension	Maximum length of a vehicle.
`width` Dimension	Maximum width of a vehicle.
`totalWeight` Dimension	Maximum weight of a vehicle.
`weightPerAxle` Dimension	Maximum weight per axle.

Structure of the Dimension object
Field	Description
`value` integer	Value of dimension.
`unit` String	Unit of dimension value.

Structure of the LaneInfo object
Field	Description
`numberOfLanes` integer	Number of lanes the road segment has. Allowed values (if applicable): `null`, above or equal to `1`.

Structure of the SpeedLimit object
Field	Description
`value` int	Value of the speed limit.
`unit` string	Unit of the speed limit.
`type` string	Type of the speed limit. Allowed values: Maximum Recommended

Structure of the Distance object
Field	Description
`value` int	Value of the driven distance.
`unit` string	Unit of the distance.

Structure of the Distances object
Field	Description
`total` int	Total traveled distance in meters or feet depending on the chosen measurement system.
`ferry` int	The traveled distance on a ferry in meters or feet depending on the chosen measurement system.
`road` int	Traveled distance within the road segment in meters or feet depending on the chosen measurement system.
`privateRoad` int	Traveled distance within the private road segment in meters or feet depending on the chosen measurement system.
`publicRoad` int	Traveled distance within the public road segment in meters or feet depending on the chosen measurement system.
`offRoad` int	Traveled distance out of the road segment in meters or feet depending on the chosen measurement system.
`unit` string	Unit of distances.

Structure of the HeightInfo object
Field	Description
`height` int	Represents the height of a road above a reference geoid EGM2008 at a specified location. Expressed in cm or feet depending on the measurement system.
`chainage` int	Represents the distance along a Road Element measured from a fixed reference point. Expressed in cm or feet depending on the measurement system.
`unit` string	Unit of the chainage.

Structure of the TrafficSign object
Field	Description
`signType` string	Information about the type of the traffic sign. Currently, the service returns information about: AccidentHazardSign AvalancheAreaSign BuiltUpAreaEntrySign BuiltUpAreaExitSign CenterLaneEndsSign ChildrenSign CongestionHazardSign CrossWindSign CyclistsSign DangerousCurveSign DomesticAnimalCrossingSign EndOfAllRestrictionsSign EndOfOvertakingRestrictionSign EndOfPriorityRoadSign EndOfSpeedRestrictionSign FallingRocksSign FogAreaSign GeneralWarningSign GuardedRailwayCrossingSign IcyConditionsSign IntersectionWithPriorityToTheRightSign LeftLaneEndsSign MovableBridgeSign NarrowingRoadAtLeftSign NarrowingRoadAtRightSign NarrowingRoadSign OvertakingLaneSign OvertakingRestrictionSign PedestrianCrossingSign PriorityOverOncomingVehiclesSign PriorityRoadSign RightLaneEndsSign RoundaboutAheadSign SharpCurveLeftSign SharpCurveRightSign SlipperyRoadSign SpeedSign SteepDeclineSign SteepInclineSign SteepSlopeSign StopSign TrafficLightAheadSign UnguardedRailwayCrossingSign VariableTrafficSign WildlifeCrossingSign WindingRoadStartingLeftSign WindingRoadStartingRightSign YieldSign YieldToOncomingVehiclesSign
`chainage` int	Represents the distance between the starting point of travel on the route segment and the traffic sign. Expressed in cm or feet depending on the measurement system.
`unit` string	Unit of the chainage.

Structure of the EmissionRegulation object
Field	Description
`restrictionType` string	The type of the restriction. Currently, the service returns information about: Ban - vehicle is forbidden to enter the road. Fee - vehicle is allowed to enter the road after paying the fee.
`emissionClass` array	The emission class represents the emission type according to a standard emission scheme.
`engineType` array	The type of engine the restriction applies to. Currently, the service returns information about the following engine types: LPG CNG LNG Diesel Petrol Hydrogen Electric Hybrid Plugin Hybrid

Successful response examples

Example response (only speed limits) - JSON

1{
"route": [
  {
    "properties": {
      "id": "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  ...
  {
    "properties": {
      "id": "c23e417c-ac30-4764-9272-9909b7448f87",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  {
    "properties": {
      "id": "cd03f919-c6c5-48ca-8c0f-130db62d77b7",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  {
    "properties": {
      "id": "bc4a05a8-5340-49e4-82fb-a8abba07a8a6",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  }
]
45}

Example response (projected points and road elements with geometry, speed limits, and IDs) - JSON

1{
"route": [
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6109198034,52.3757167161],[4.6109291911,52.3757502437],[4.6110069752,52.3759138584],[4.6110418439,52.3759916425],[4.6110659838,52.3760412633]]
    },
    "properties": {
      "id": "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  ...
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6134424210,52.3791351914],[4.6134652197,52.3791633546],[4.6137334406,52.3795053363],[4.6138648689,52.3796957731],[4.6139051020,52.3797588050]]
    },
    "properties": {
      "id": "c23e417c-ac30-4764-9272-9909b7448f87",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6139051020,52.3797588050],[4.6140727401,52.3800149560],[4.6141116321,52.3800887167]]
    },
    "properties": {
      "id":"cd03f919-c6c5-48ca-8c0f-130db62d77b7",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6141116321,52.3800887167],[4.6141947806,52.3802402616]]
    },
    "properties": {
      "id":"bc4a05a8-5340-49e4-82fb-a8abba07a8a6",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      }
    }
  }
],
"projectedPoints": [
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6109191758,52.3757173113]
    },
    "properties": {
      "routeIndex": 0,
      "snapResult": "Matched"
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [4.6147588418,52.3834214472]
    },
    "properties": {
      "routeIndex": 10,
      "snapResult": "Matched"
    }
  }
]
89}

Example response (all possible data) - JSON

1{
"route": [
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6109198034,52.3757167161],[4.6109291911,52.3757502437],[4.6110069752,52.3759138584],[4.6110418439,52.3759916425],[4.6110659838,52.3760412633]]
    },
    "properties": {
      "id": "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      },
      "speedProfile": {
        "value": 70,
        "unit": "kmph"
      },
      "address": {
        "roadName": "Westelijke Randweg",
        "roadNumbers": ["N208"],
        "municipality": "Haarlem",
        "countryName": "Nederland",
        "countryCode": "NLD",
        "countrySubdivision": "Noord-Holland"
      },
      "maximumDimensions":{
        "height": {
          "value":4,
          "unit":"m"
        },
        "length": {
          "value":10,
          "unit":"m"
        },
        "width": {
          "value":4,
          "unit":"m"
        },
        "totalWeight": {
          "value":6,
          "unit":"t"
        },
        "weightPerAxle": {
          "value":1.5,
          "unit":"t"
        }
      },
      "traveledDistance": {
        "value": 123,
        "unit": "m"
      },
      "privateRoad": false,
      "partOfTunnel": false,
      "urbanArea": true,
      "elementType": "Road",
      "frc": 2,
      "formOfWay": "DualCarriageway",
      "roadUse": "Arterial",
      "laneInfo": {
        "numberOfLanes": 2
      },
      "heightInfo":[
        {
          "height":394,
          "chainage":0,
          "unit": "cm"
        },
        {
          "height":1575,
          "chainage":197,
          "unit": "cm"
        },
        {
          "height":2756,
          "chainage":315,
          "unit": "cm"
        }
      ],
      "trafficSigns":[
        {
          "signType": "StopSign",
          "chainage": 329,
          "unit": "cm"
        }
      ],
      "trafficLight": "Start",
      "confidence": 0.67,
      "emissionRegulations": [
        {
          "restrictionType": "Ban",
          "emissionClass": [
            0,
            1,
            2,
            3,
            4
          ],
          "engineType": ["Diesel"]
        },
        {
          "restrictionType": "Fee",
          "emissionClass": [
            5
          ],
          "engineType": ["Petrol"]
        }
      ]
    }
  },
  ...
  {
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[4.6134424210,52.3791351914],[4.6134652197,52.3791633546],[4.6137334406,52.3795053363],[4.6138648689,52.3796957731],[4.6139051020,52.3797588050]]
    },
    "properties": {
      "id": "c23e417c-ac30-4764-9272-9909b7448f87",
      "speedLimits": {
        "value": 70,
        "unit": "kmph",
        "type": "Maximum"
      },
      "speedProfile": {
        "value": 70,
        "unit": "kmph"
      },
      "address": {
        "roadName": "Westelijke Randweg",
        "roadNumbers": ["N208"],
        "municipality": "Haarlem",
        "countryName": "Nederland",
        "countryCode": "NLD",
        "countrySubdivision": "Noord-Holland"
      },
      "maximumDimensions":{
        "height": {
          "value":4,
          "unit":"m",
        },
        "length": {
          "value":10,
          "unit":"m",
        },
        "width": {
          "value":4,
          "unit":"m",
        },
        "totalWeight": {
          "value":6,
          "unit":"t"
        },
        "weightPerAxle": {
          "value":1.5,
          "unit":"t",
        }
      },
      "traveledDistance": {
        "value": 321,
        "unit": "m"
      },
      "privateRoad": false,
      "partOfTunnel": false,
      "urbanArea": false,
      "elementType": "Road",
      "frc": 2,
      "formOfWay": "DualCarriageway",
      "roadUse": "Arterial",
      "laneInfo": {
        "numberOfLanes": 4
      },
      "heightInfo":[
        {
          "height": 252,
          "chainage": 0,
          "unit": "cm"
        },
        {
          "height": 678,
          "chainage": 211,
          "unit": "cm"
        }
      ],
      "trafficSigns":[
        {
          "signType": "StopSign",
          "chainage": 678,
          "unit": "cm"
        }
      ],
      "trafficLight": "Both",
      "confidence": 0.87,
      "emissionRegulations": [
        {
           "restrictionType": "Ban",
           "emissionClass": [
              0,
              1,
              2,
              3,
              4
          ],
          "engineType": ["Diesel"]
        },
        {

Synchronous Snap to Roads

Purpose

Run this endpoint

Request data

HTTPS method: GET

GET request parameters

HTTPS method: POST

POST request parameters

Request body

Request schema

Fields of the request body

HTTP request headers

Response data

Successful response

Response schema

Response field structure

Successful response examples

HTTPS method: `GET`

HTTPS method: `POST`