Synchronous Snap to Roads

Service version: 1
Last edit: 2022.03.10
Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

We welcome your contribution to the development of this version. Please share your observations and suggestions on our forum or send an email to our software engineers.

We appreciate your feedback, and we will keep you posted on how it's used.

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 endpont

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.

URL format

GET
URL request format
https://{baseURL}/snap-to-roads/{versionNumber}/snap-to-roads?key={Your_API_Key}&points={longitude,latitude;...}&headings={string}&timestamps={string}&fields={string}&vehicleType={string}&measurementSystem={string}

Example (only speed limits)

GET
Example (only speed limits)
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric

curl command (only speed limits)

GET
curl command (only speed limits)
curl 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric'

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

GET
Example (projected points and road elements with geometry, speed limits, and IDs)
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric&offroadMargin=50

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

GET
Example (projected points and road elements with geometry, speed limits, and IDs)
curl 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric&offroadMargin=50'

Example (all possible data)

GET
Example (all possible data))
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},traveledDistance,privateRoad,partOfTunnel,elementType,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage},trafficSign{signType,chainage},trafficLight}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric&offroadMargin=50

curl command (all possible data)

GET
curl command (all possible data)
curl 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?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}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},traveledDistance,privateRoad,partOfTunnel,elementType,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage},trafficSign{signType,chainage},trafficLight}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric&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 parametersDescription
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 4000 while the minimum is 2.
  • The maximum road distance between two consecutive points cannot exceed 3000 meters.

Value: longitude,latitude;...
Optional parametersDescription
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 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    }
11  },
12  route{
13    type,
14    geometry{
15      type,
16      coordinates
17    },
18    properties{
19      id,
20      speedRestrictions{
21        maximumSpeed{
22          value,
23          unit
24        }
25      },
26      address{
27        roadName,
28        roadNumbers,
29        municipality,
30        countryName,
31        countryCode,
32        countrySubdivision
33      },
34      traveledDistance,
35      privateRoad,
36      partOfTunnel,
37      elementType,
38      frc,
39      formOfWay,
40      roadUse,
41      laneInfo{
42        numberOfLanes
43      },
44      heightInfo{
45        height,
46        chainage
47      },
48      trafficSign{
49        signType,
50        chainage
51      },
52      trafficLight
53    }
54  },
55  distances{
56    total,
57    ferry,
58    road,
59    privateRoad,
60    publicRoad,
61    offRoad
62  }
63}
vehicleType
string		It can contribute to a more accurate road identification by possibly excluding roads which are not suited for a given value.
Default value: PassengerCar
Allowed values:
  • PassengerCar
  • Bus
  • Truck
measurementSystem
string		Indicates measurement system in which client requests data.
Default value: metric
Allowed values:
  • 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.

URL format

POST
URL request example
https://{baseURL}/snap-to-roads/{versionNumber}/snap-to-roads?key={Your_API_Key}&fields={string}&vehicleType={string}&measuremenSystem={string}

Example (only speed limits)

POST
Example (only speed limits)
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key={Your_API_Key}&fields={route{properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric

curl command (only speed limits)

POST
Example (only speed limits)
1curl -X POST 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key={Your_API_Key}&fields={route{properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric' -d '{
2"points": [
3    {
4      "type": "Feature",
5      "geometry": {
6        "type": "Point",
7        "coordinates": [4.6104919036936565,52.37576529649988]
8      },
9      "properties": {
10        "heading": 0
11      }
12    },
13    {
14      "type": "Feature",
15      "geometry": {
16        "type": "Point",
17        "coordinates": [4.614096792595859,52.38341473290629]
18      },
19      "properties": {
20        "heading": 0
21      }
22    }
23  ]
24}'

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

POST
Example (projected points and road elements with geometry, speed limits, and IDs)
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key={Your_API_Key}&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric

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

POST
curl command (projected points and road elements with geometry, speed limits, and IDs)
1curl -X POST 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}}}}}&vehicleType=PassengerCar&measurementSystem=metric' -d '{
2"points": [
3    {
4      "type": "Feature",
5      "geometry": {
6        "type": "Point",
7        "coordinates": [4.6104919036936565,52.37576529649988]
8      },
9      "properties": {
10        "heading": 0
11      }
12    },
13    {
14      "type": "Feature",
15      "geometry": {
16        "type": "Point",
17        "coordinates": [4.614096792595859,52.38341473290629]
18      },
19      "properties": {
20        "heading": 0
21      }
22    }
23  ]
24}'

Example (all possible data)

POST
Example (all possible data)
https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage},trafficSign{signType,chainage},trafficLight}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric&offroadMargin=50

curl command (all possible data)

POST
curl command (all possible data)
1curl -X POST 'https://api.tomtom.com/snap-to-roads/1/snap-to-roads?key=Your_API_Key&fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{maximumSpeed{value,unit}},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes},heightInfo{height,chainage},trafficSign{signType,chainage},trafficLight}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric&offroadMargin=50' -d '
2{
3"points": [
4    {
5      "type": "Feature",
6      "geometry": {
7        "type": "Point",
8        "coordinates": [4.6104919036936565,52.37576529649988]
9      },
10      "properties": {
11        "heading": 0
12      }
13    },
14    {
15      "type": "Feature",
16      "geometry": {
17        "type": "Point",
18        "coordinates": [4.614096792595859,52.38341473290629]
19      },
20      "properties": {
21        "heading": 0
22      }
23    }
24  ]
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 parametersDescription
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 parametersDescription
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    }
11  },
12  route{
13    type,
14    geometry{
15      type,
16      coordinates
17    },
18    properties{
19      id,
20      speedRestrictions{
21        maximumSpeed{
22          value,
23          unit
24        }
25      },
26      address{
27        roadName,
28        roadNumbers,
29        municipality,
30        countryName,
31        countryCode,
32        countrySubdivision
33      },
34      traveledDistance,
35      privateRoad,
36      partOfTunnel,
37      elementType,
38      frc,
39      formOfWay,
40      roadUse,
41      laneInfo{
42        numberOfLanes
43      },
44      heightInfo{
45        height,
46        chainage
47      },
48      trafficSign{
49        signType,
50        chainage      
51      },
52      trafficLight
53    }
54  },
55  distances{
56    total,
57    ferry,
58    road,
59    privateRoad,
60    publicRoad,
61    offRoad
62  }
63}
vehicleType
string		It can contribute to a more accurate road identification by possibly excluding roads which are not suited for the given value.
Default value: PassengerCar
Allowed values:
  • PassengerCar
  • Bus
  • Truck
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.

Request schema

Exclamation mark ! means that this field is required.

POST
POST body request schema - JSON
1{
2  type Query {
3      points: [Point!]!
4  }
5  type Point {
6      type: GeojsonFeatureType!
7      geometry: GeojsonPoint!
8      properties: Properties
9  }
10  type GeojsonPoint {
11      type: GeojsonPointType!
12      coordinates: [Float!]!
13  }
14  type Properties {
15      heading: Float
16      timestamp: String
17  }
18  enum GeojsonPointType {
19      Point
20  }
21  enum GeojsonFeatureType {
22      Feature
23  }
24}

Fields of the request body

Structure of the root object
FieldDescription
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 4000 points.
Structure of the point object
FieldDescription
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
FieldDescription
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
FieldDescription
heading
integer		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 algorithm to determine end time of selected restrictions.
  • The timestamp value must be compliant with ISO 8601 date and time format.

Example

POST
POST request body example - JSON
1{
2"points": [
3    {
4      "type": "Feature",
5      "geometry": {
6        "type": "Point",
7        "coordinates": [4.6104919036936565,52.37576529649988]
8      },
9      "properties": {
10        "heading": 0,
11        "timestamp": "2021-01-01T12:00:00Z"
12      }
13    },
14    {
15      "type": "Feature",
16      "geometry": {
17        "type": "Point",
18        "coordinates": [4.614096792595859,52.38341473290629]
19      },
20      "properties": {
21        "heading": 0,
22        "timestamp": "2021-01-01T12:00:01Z"
23      }
24    }
25  ]
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 headersDescription
Accept-EncodingContains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip
Tracking-IDSpecifies 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.

Request 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
Request schema
1{
2  union AnyElement = RoadElement | FerryElement
3  type Query {
4      projectedPoints: [ProjectedPoint!]!
5      route: [AnyElement!]!
6      distances: Distances
7  }
8  type Distances {
9      total: Int
10      ferry: Int
11      road: Int
12      privateRoad: Int
13      publicRoad: Int
14      offRoad: Int
15  }
16  type ProjectedPoint {
17      type: GeojsonFeatureType!
18      geometry: GeojsonPoint
19      properties: ProjectedPointProperties
20  }
21  type ProjectedPointProperties {
22      routeIndex: Int
23  }
24  type FerryElement {
25      type: GeojsonFeatureType!
26      geometry: GeojsonLinestring!
27      properties: FerryElementProperties!
28  }
29  type RoadElement {
30      type: GeojsonFeatureType!
31      geometry: GeojsonLinestring!
32      properties: RoadElementProperties!
33  }
34  type RoadElementProperties {
35      id: String!
36      address: RoadAddress!
37      speedRestrictions: SpeedRestriction!
38      elementType: ElementType!
39      frc: Int!
40      formOfWay: String!
41      roadUse: String!
42      laneInfo: LaneInfo
43      traveledDistance: Int!
44      privateRoad: String!
45      partOfTunnel: String!
46      heightInfo: [HeightInfo!]!
47      trafficLight: String
48      trafficSigns: [TrafficSign]
49  }
50  
51  type FerryElementProperties {
52      id: String!
53      address: FerryAddress!
54      elementType: ElementType!
55      frc: Int!
56      traveledDistance: Int!
57      privateRoad: String!
58      partOfTunnel: String!
59  }
60  
61  type LaneInfo {
62      numberOfLanes: Int
63  }
64  
65  type SpeedRestriction {
66      maximumSpeed: SpeedWithUnit
67  }
68  
69  type FerryAddress {
70      roadName: String
71      roadNumbers: [String]
72  }
73  
74  type RoadAddress {
75      roadName: String
76      roadNumbers: [String]
77      municipality: String
78      countryName: String
79      countryCode: String
80      countrySubdivision: String
81  }
82  
83  type SpeedWithUnit {
84      unit: SpeedUnit!
85      value: Int!
86  }
87  
88  type HeightInfo {
89      height: Int
90      chainage: Int
91  }
92  
93  type TrafficSign {
94    signType: String!
95    chainage: Int!
96  }
97

98  enum SpeedUnit {
99      kmph,
100      mph
101  }
102  
103  enum ElementType {
104      Road,
105      Ferry
106  }
107  
108  type GeojsonPoint {
109      type: GeojsonPointType!
110      coordinates: [Float!]!
111  }
112  
113  type GeojsonLinestring {
114      type: GeojsonLinestringType!
115      coordinates: [[Float!]!]!
116  }
117  
118  enum GeojsonLinestringType {
119      LineString
120  }
121  
122  enum GeojsonPointType {
123      Point
124  }
125  
126  enum GeojsonFeatureType {
127      Feature
128  }
129}

Response field structure

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

Structure of the root object
FieldDescription
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
FieldDescription
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
FieldDescription
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 to any road element.
Structure of the FerryElement object
FieldDescription
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
FieldDescription
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
FieldDescription
id
string		Unique ID of the ferry element.
address
object		Address information relevant to the ferry element.
elementType
string		Type of the element.
Allowed values:
  • 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
integer		The traveled distance within the ferry segment in meters or feet depending on the chosen measurement system.
privateRoad
string		Ferry element ownership.
Allowed values:
  • true
  • false
partOfTunnel
string		Ferry element that is a part of a tunnel.
Allowed values:
  • true
  • false
Structure of the RoadElementProperties object
FieldDescription
id
string		Unique ID of the road element.
speedRestrictions
object		Speed restriction for a given vehicleType.
address
object		Address information relevant to the road element.
elementType
string		Type of the element.
Allowed values:
  • 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
integer		The traveled distance within the road segment in meters or feet depending on the chosen measurement system.
privateRoad
string		Road element ownership.
Allowed values:
  • true
  • false
partOfTunnel
string		Road element is a part of a tunnel.
Allowed values:
  • true
  • false
heightInfo
HeightInfo		Information about the road element's height.
trafficSign
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
Structure of the FerryAddress object
FieldDescription
roadName
string		Road name in NGT format.
roadNumbers
array of strings		The list of road numbers.
Structure of the RoadAddress object
FieldDescription
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 LaneInfo object
FieldDescription
numberOfLanes
integer		Number of lanes the road segment has.
Allowed values (if applicable): null, above or equal to 1.
Structure of the SpeedRestriction object
FieldDescription
maximumSpeed
object		Maximum allowed speed. It contains two fields:
  • value with the actual value of speed.
  • unit with the name of the used unit.
Structure of the Distances object
FieldDescription
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.
Structure of the HeightInfo object
FieldDescription
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.
Structure of the TrafficSign object
FieldDescription
signType
string		Information about the type of the traffic sign. Currently, the service only returns information about StopSign.
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.

Successful response examples

Example response (only speed limits) - JSON
1{
2  "route" : [
3    {
4      "properties" : {
5        "id" : "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
6        "speedRestrictions" : {
7          "maximumSpeed" : {
8            "value" : 70,
9            "unit" : "kmph"
10          }
11        }
12      }
13    },
14    ...
15    {
16      "properties" : {
17        "id" : "c23e417c-ac30-4764-9272-9909b7448f87",
18        "speedRestrictions" : {
19          "maximumSpeed" : {
20            "value" : 70,
21            "unit" : "kmph"
22          }
23        }
24      }
25    },
26    {
27      "properties" : {
28        "id" : "cd03f919-c6c5-48ca-8c0f-130db62d77b7",
29        "speedRestrictions" : {
30          "maximumSpeed" : {
31            "value" : 70,
32            "unit" : "kmph"
33          }
34        }
35      }
36    },
37    {
38      "properties" : {
39        "id" : "bc4a05a8-5340-49e4-82fb-a8abba07a8a6",
40        "speedRestrictions" : {
41          "maximumSpeed" : {
42            "value" : 70,
43            "unit" : "kmph"
44          }
45        }
46      }
47    }
48  ]
49}
Example response (projected points and road elements with geometry, speed limits, and IDs) - JSON
1{
2  "route" : [
3    {
4      "type" : "Feature",
5      "geometry" : {
6        "type" : "LineString",
7        "coordinates" : [[4.6109198034,52.3757167161],[4.6109291911,52.3757502437],[4.6110069752,52.3759138584],[4.6110418439,52.3759916425],[4.6110659838,52.3760412633]]
8      },
9      "properties" : {
10        "id" : "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
11        "speedRestrictions" : {
12          "maximumSpeed" : {
13            "value" : 70,
14            "unit" : "kmph"
15          }
16        }
17      }
18    },
19    ...
20    {
21      "type" : "Feature",
22      "geometry" : {
23        "type" : "LineString",
24        "coordinates" : [[4.6134424210,52.3791351914],[4.6134652197,52.3791633546],[4.6137334406,52.3795053363],[4.6138648689,52.3796957731],[4.6139051020,52.3797588050]]
25      },
26      "properties" : {
27        "id" : "c23e417c-ac30-4764-9272-9909b7448f87",
28        "speedRestrictions" : {
29          "maximumSpeed" : {
30            "value" : 70,
31            "unit" : "kmph"
32          }
33        }
34      }
35    },
36    {
37      "type" : "Feature",
38      "geometry" : {
39        "type" : "LineString",
40        "coordinates" : [[4.6139051020,52.3797588050],[4.6140727401,52.3800149560],[4.6141116321,52.3800887167]]
41      },
42      "properties" : {
43        "id":"cd03f919-c6c5-48ca-8c0f-130db62d77b7",
44        "speedRestrictions" : {
45          "maximumSpeed" : {
46            "value" : 70,
47            "unit" : "kmph"
48          }
49        }
50      }
51    },
52    {
53      "type" : "Feature",
54      "geometry" : {
55        "type" : "LineString",
56        "coordinates" : [[4.6141116321,52.3800887167],[4.6141947806,52.3802402616]]
57      },
58      "properties" : {
59        "id":"bc4a05a8-5340-49e4-82fb-a8abba07a8a6",
60        "speedRestrictions" : {
61          "maximumSpeed" : {
62            "value" : 70,
63            "unit" : "kmph"
64          }
65        }
66      }
67    }
68  ],
69  "projectedPoints" : [
70    {
71      "type" : "Feature",
72      "geometry" : {
73        "type" : "Point",
74        "coordinates" : [4.6109191758,52.3757173113]
75      },
76      "properties" : {
77        "routeIndex" : 0
78      }
79    },
80    {
81      "type" : "Feature",
82      "geometry" : {
83        "type" : "Point",
84        "coordinates" : [4.6147588418,52.3834214472]
85      },
86      "properties" : {
87        "routeIndex" : 10
88      }
89    }
90  ]
91}
Example response (all possible data) - JSON
1{
2  "route" : [
3    {
4      "type" : "Feature",
5      "geometry" : {
6        "type" : "LineString",
7        "coordinates" : [[4.6109198034,52.3757167161],[4.6109291911,52.3757502437],[4.6110069752,52.3759138584],[4.6110418439,52.3759916425],[4.6110659838,52.3760412633]]
8      },
9      "properties" : {
10        "id" : "88a7637c-db86-448c-aca9-b7d1f1b66ea0",
11        "speedRestrictions" : {
12          "maximumSpeed" : {
13            "value" : 70,
14            "unit" : "kmph"
15          }
16        },
17        "address" : {
18          "roadName" : "Westelijke Randweg",
19          "roadNumbers" : ["N208"],
20          "municipality" : "Haarlem",
21          "countryName" : "Nederland",
22          "countryCode" : "NLD",
23          "countrySubdivision" : "Noord-Holland"
24        },
25        "traveledDistance": 123,
26        "privateRoad":"false",
27        "partOfTunnel":"false",
28        "elementType": "Road",
29        "frc" : 2,
30        "formOfWay" : "DualCarriageway",
31        "roadUse" : "Arterial",
32        "laneInfo" : {
33          "numberOfLanes" : 2
34        },
35        "heightInfo":[
36          {
37            "height":394,
38            "chainage":0
39          },
40          {
41            "height":1575,
42            "chainage":197
43          },
44          {
45            "height":2756,
46            "chainage":315
47          }
48        ],
49        "trafficSign":[
50          {
51            "signType": "StopSign",
52            "chainage": 329
53          }
54        ],
55        "trafficLight": "Start"
56      }
57    },
58    ...
59    {
60      "type" : "Feature",
61      "geometry" : {
62        "type" : "LineString",
63        "coordinates" : [[4.6134424210,52.3791351914],[4.6134652197,52.3791633546],[4.6137334406,52.3795053363],[4.6138648689,52.3796957731],[4.6139051020,52.3797588050]]
64      },
65      "properties" : {
66        "id" : "c23e417c-ac30-4764-9272-9909b7448f87",
67        "speedRestrictions" : {
68          "maximumSpeed" : {
69            "value" : 70,
70            "unit" : "kmph"
71          }
72        },
73        "address" : {
74          "roadName" : "Westelijke Randweg",
75          "roadNumbers" : ["N208"],
76          "municipality" : "Haarlem",
77          "countryName" : "Nederland",
78          "countryCode" : "NLD",
79          "countrySubdivision" : "Noord-Holland"
80        },
81        "traveledDistance":321,
82        "privateRoad":"false",
83        "partOfTunnel":"false",
84        "elementType": "Road",
85        "frc" : 2,
86        "formOfWay" : "DualCarriageway",
87        "roadUse" : "Arterial",
88        "laneInfo" : {
89          "numberOfLanes" : 4
90        },
91        "heightInfo":[
92          {
93            "height":252,
94            "chainage":0
95          },
96          {
97            "height":678,
98            "chainage":211
99          }
100        ],
101        "trafficSign":[
102          {
103            "signType": "StopSign",
104            "chainage": 678
105          }
106        ],
107        "trafficLight": "Both"  
108      }
109    },
110    {
111      "type" : "Feature",
112      "geometry" : {
113        "type" : "LineString",
114        "coordinates" : [[4.6139051020,52.3797588050],[4.6140727401,52.3800149560],[4.6141116321,52.3800887167]]
115      },
116      "properties" : {
117        "id" : "cd03f919-c6c5-48ca-8c0f-130db62d77b7",
118        "speedRestrictions" : {
119          "maximumSpeed" : {
120            "value" : 70,
121            "unit" : "kmph"
122          }
123        },
124        "address" : {
125          "roadName" : "Westelijke Randweg",
126          "roadNumbers" : ["N208"],
127          "municipality" : "Haarlem",
128          "countryName" : "Nederland",
129          "countryCode" : "NLD",
130          "countrySubdivision" : "Noord-Holland"
131        },
132        "traveledDistance": 456,
133        "privateRoad":"false",
134        "partOfTunnel":"false",
135        "elementType": "Road",
136        "frc" : 2,
137        "formOfWay" : "DualCarriageway",
138        "roadUse" : "Arterial",
139        "laneInfo" : {
140          "numberOfLanes" : 3
141        },
142        "heightInfo":[
143          {
144            "height":354,
145            "chainage":0
146          },
147          {
148            "height":125,
149            "chainage":137
150          },
151          {
152            "height":756,
153            "chainage":244
154          }
155        ],        
156        "trafficLight": "End"
157      }
158    },
159    {
160      "type" : "Feature",
161      "geometry" : {
162        "type" : "LineString",
163        "coordinates" : [[4.6141116321,52.3800887167],[4.6141947806,52.3802402616]]
164      },
165      "properties" : {
166        "id" : "bc4a05a8-5340-49e4-82fb-a8abba07a8a6",
167        "speedRestrictions" : {
168          "maximumSpeed" : {
169            "value" : 70,
170            "unit" : "kmph"
171          }
172        },
173        "address" : {
174          "roadName" : "Westelijke Randweg",
175          "roadNumbers" : ["N208"],
176          "municipality" : "Haarlem",
177          "countryName" : "Nederland",
178          "countryCode" : "NLD",
179          "countrySubdivision" : "Noord-Holland"
180        },
181        "traveledDistance": 654,
182        "privateRoad":"false",
183        "partOfTunnel":"false",
184        "elementType": "Road",
185        "frc" : 2,
186        "formOfWay" : "DualCarriageway",
187        "roadUse" : "Arterial",
188        "laneInfo" : {
189          "numberOfLanes" : 3
190        },
191        "heightInfo":[
192          {
193            "height":1394,
194            "chainage":0
195          },
196          {
197            "height":1675,
198            "chainage":97
199          },
200          {
201            "height":1756,
202            "chainage":215
203          }
204        ]  
205      }
206    }
207  ]
208  "projectedPoints" : [
209    {
210      "type" : "Feature",
211      "geometry" : {
212        "type" : "Point",
213        "coordinates" : [4.6109191758,52.3757173113]
214      },
215      "properties" : {
216        "routeIndex" : 0
217      }
218    },
219    {
220      "type" : "Feature",
221      "geometry" : {
222        "type" : "Point",
223        "coordinates" : [4.6147588418,52.3834214472]
224      },
225      "properties" : {
226        "routeIndex" : 10
227      }
228    }
229  ],
230  "distances": {
231    "total": 909,
232    "ferry": 0,
233    "publicRoad": 909,
234    "privateRoad": 0,
235    "offRoad": 0,
236    "road": 909
237  }
238}

Error response

The Synchronous Snap to Roads endpoint, for an invalid single request, returns a response body in JSON format.

Error response field structure

FieldDescription
detailedError
object		Main object of the error response.
code
string		One of a server-defined set of error codes.
message
string		A human-readable description of the error code.

Error response example

Error response example - JSON
1{
2  "detailedError" : {
3    "code" : "INVALID_REQUEST",
4    "message" : "Missing points parameter."
5  }
6}

HTTP response codes

CodeMeaning & possible causes
200OK
400Bad request
403Forbidden: The supplied API Key is not valid for this request.
405Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.
429Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500Internal Server Error
503Service currently unavailable: The service is currently unavailable.
596Service Not Found: Unknown version of the service.

HTTP response headers

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

HeaderDescription
Access-Control-Allow-OriginIndicates that cross-origin resource sharing (CORS) is allowed.
Value: *
AllowLists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD, POST
Content-EncodingIndicates which encodings were applied to the response body.
Value: gzip
Content-LengthContains information about the size of the response body.
Value: <decimal number>
Content-TypeIndicates the media type of the resource returned.
Value: <application/json; charset=utf-8>
DateContains the date and time at which the message was originated. For details check RFC 7231.
Value: <http-date>
Tracking-IDAn identifier for the request.
  • If the Tracking-ID header was specified in the request, it is replicated in the response.
  • Otherwise, it is generated automatically by the service. For details check RFC 4122.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: <string>