Developer

Asynchronous Snap to Roads Submission

Service version: 1
Last edit: 2022.12.19

Purpose

This endpoint enables the Asynchronous Snap To Roads Submission. It responds with a unique job id which can be used to check the job status and download its result when available.

Run this endpoint

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

Request data

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 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/batch/{versionNumber}?key={Your_API_Key}
post
URL request example
https://api.tomtom.com/snapToRoads/batch/1?key={Your_API_Key)
post
curl command request example
1curl -X POST 'https://api.tomtom.com/snapToRoads/batch/1/?key={Your_API_Key) -d '{
2  "batchItems": [
3    {
4      "query": "/snapToRoads/1?fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedRestrictions{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric",
5      "post": {
6        "points": [
7          {
8            "type": "Feature",
9            "geometry": {
10              "type": "Point",
11              "coordinates": [
12                19.4389141359581,
13                51.78057462411982
14              ]
15            },
16            "properties": {}
17          },
18          {
19            "type": "Feature",
20            "geometry": {
21              "type": "Point",
22              "coordinates": [
23                19.439257458711324,
24                51.78057794294989
25              ]
26            },
27            "properties": {}
28          },
29          {
30            "type": "Feature",
31            "geometry": {
32              "type": "Point",
33              "coordinates": [
34                19.43963296797358,
35                51.78064100067553
36              ]
37            },
38            "properties": {}
39          },
40          {
41            "type": "Feature",
42            "geometry": {
43              "type": "Point",
44              "coordinates": [
45                19.44012113001449,
46                51.780690783028064
47              ]
48            },
49            "properties": {}
50          }
51        ]
52      }
53    },
54{
55      "query": "/snapToRoads/1?fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=imperial",
56      "post": {
57        "points": [
58          {
59            "type": "Feature",
60            "geometry": {
61              "type": "Point",
62              "coordinates": [
63                19.4389141359581,
64                51.78057462411982
65              ]
66            },
67            "properties": {}
68          },
69          {
70            "type": "Feature",
71            "geometry": {
72              "type": "Point",
73              "coordinates": [
74                19.439257458711324,
75                51.78057794294989
76              ]
77            },
78            "properties": {}
79          },
80          {
81            "type": "Feature",
82            "geometry": {
83              "type": "Point",
84              "coordinates": [
85                19.43963296797358,
86                51.78064100067553
87              ]
88            },
89            "properties": {}
90          },
91          {
92            "type": "Feature",
93            "geometry": {
94              "type": "Point",
95              "coordinates": [
96                19.44012113001449,
97                51.780690783028064
98              ]
99            },
100            "properties": {}
101          }
102        ]
103      }
104    }
105  ]
106}'

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.

Note: There are no optional parameters in this endpoint.

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.

POST body request schema

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 the field is not nullable. For example:

  • String! - is non-nullable
  • [String!] - list of non-null objects
  • [String]! - list cannot be null, but it can contain null values
post
POST body request schema
1{
2  type BatchQuery {
3    batchItems : [Query!]!
4  }
5

6  type Query {
7    query: String!
8    post: [Point!]!
9  }
10

11  type Point {
12    type: String!
13    geometry: Geometry!
14    properties: Properties
15  }
16

17  type Geometry {
18    type: String!
19    coordinates : [longitude, latitude]!
20  }
21

22  type Properties {
23    heading: Float
24    timestamp: String
25  }
26}

Fields to submit to the Asynchronous Snap To Roads Submission

Structure of the BatchQuery object
FieldDescription

batchItems
array

  • Array of Query elements.

  • It should contain at least 1 and at most 100 elements.

Structure of the Query object
FieldDescription

query
string

Query to the Snap To Roads service.

post
array

An array of Point elements.

  • The array has to contain at least 2 elements.
  • The array cannot contain more than 5000 elements.
  • If you require a higher limit, check our Pricing and Contact Sales.
Structure of the Point object
FieldDescription

type
string

The value is always set as a Feature.

geometry
Geometry

Object in GeoJSON format that represents a single point.

properties
Properties

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

Point's longitude and latitude coordinates.
Structure of the Properties object
FieldDescription

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 body request example - JSON
1{
2  "batchItems": [
3    {
4      "query": "/snapToRoads/1?fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric",
5      "post": {
6        "points": [
7          {
8            "type": "Feature",
9            "geometry": {
10              "type": "Point",
11              "coordinates": [19.4389141359581, 51.78057462411982]
12            },
13            "properties": {}
14          },
15          {
16            "type": "Feature",
17            "geometry": {
18              "type": "Point",
19              "coordinates": [19.439257458711324, 51.78057794294989]
20            },
21            "properties": {}
22          },
23          {
24            "type": "Feature",
25            "geometry": {
26              "type": "Point",
27              "coordinates": [19.43963296797358, 51.78064100067553]
28            },
29            "properties": {}
30          },
31          {
32            "type": "Feature",
33            "geometry": {
34              "type": "Point",
35              "coordinates": [19.44012113001449, 51.780690783028064]
36            },
37            "properties": {}
38          }
39        ]
40      }
41    },
42    {
43      "query": "/snapToRoads/1?fields={projectedPoints{type,geometry{type,coordinates},properties{routeIndex,snapResult}},route{type,geometry{type,coordinates},properties{id,speedLimits{value,unit},address{roadName,roadNumbers,municipality,countryName,countryCode,countrySubdivision},elementType,traveledDistance,privateRoad,partOfTunnel,frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,ferry,publicRoad,privateRoad,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=imperial",
44      "post": {
45        "points": [
46          {
47            "type": "Feature",
48            "geometry": {
49              "type": "Point",
50              "coordinates": [19.4389141359581, 51.78057462411982]
51            },
52            "properties": {}
53          },
54          {
55            "type": "Feature",
56            "geometry": {
57              "type": "Point",
58              "coordinates": [19.439257458711324, 51.78057794294989]
59            },
60            "properties": {}
61          },
62          {
63            "type": "Feature",
64            "geometry": {
65              "type": "Point",
66              "coordinates": [19.43963296797358, 51.78064100067553]
67            },
68            "properties": {}
69          },
70          {
71            "type": "Feature",
72            "geometry": {
73              "type": "Point",
74              "coordinates": [19.44012113001449, 51.780690783028064]
75            },
76            "properties": {}
77          }
78        ]
79      }
80    }
81  ]
82}

HTTP request headers

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

Note: There are no required headers in this endpoint.

Optional headersDescription

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 checkRFC 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

Snap To Roads Submission schema

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

  • String! - is non-nullable
  • [String!] - list of non-null objects
  • [String]! - list cannot be null, but it can contain null values
Exclamation mark ( ! ) example
1type BatchResponse {
2  batchId: String!
3}

Response field structure

The following table describes JSON element fields that can appear in a response.

Structure of the BatchResponse object
FieldDescription

batchId
string

A unique identifier ( UUID ) of the asynchronous request.

Successful response

For a valid Asynchronous Snap To Roads Submission request, the endpoint returns its response body in JSON format.

Successful response example
1{
2"batchId": "45e0909c-625a-4822-a060-8f7f88498c0e"
3}

Error response

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

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 - JSON
1{
2  "detailedError": {
3    "code": "INVALID_REQUEST",
4    "message": "Payload is not a valid JSON format."
5  }
6}

HTTP response codes

CodeMeaning & possible causes

200

OK

400

Bad request

403

Forbidden: The supplied API Key is not valid for this request.

405

Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.

429

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error

503

Service currently unavailable: The service is currently unavailable.

596

Service 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 Asynchronous Snap to Roads Submission endpoint.

HeaderDescription

Access-Control-Allow-Origin

Indicates that cross-origin resource sharing (CORS) is allowed.
Value: *

Allow

Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD, POST

Content-Encoding

Indicates which encodings were applied to the response body.
Value: gzip

Content-Length

Contains information about the size of the response body.
Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.
Value: <application/json; charset=utf-8>

Date

Contains the date and time at which the message was originated. For details check RFC 7231.
Value: <http-date>

Tracking-ID

An 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>