Asynchronous Snap to Roads Submission
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.
https://{baseURL}/snapToRoads/batch/{versionNumber}?key={Your_API_Key}
https://api.tomtom.com/snapToRoads/batch/1?key={Your_API_Key)
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.7805746241198214 ]15 },16 "properties": {}17 },18 {19 "type": "Feature",20 "geometry": {21 "type": "Point",22 "coordinates": [23 19.439257458711324,24 51.7805779429498925 ]26 },27 "properties": {}28 },29 {30 "type": "Feature",31 "geometry": {32 "type": "Point",33 "coordinates": [34 19.43963296797358,35 51.7806410006755336 ]37 },38 "properties": {}39 },40 {41 "type": "Feature",42 "geometry": {43 "type": "Point",44 "coordinates": [45 19.44012113001449,46 51.78069078302806447 ]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.7805746241198265 ]66 },67 "properties": {}68 },69 {70 "type": "Feature",71 "geometry": {72 "type": "Point",73 "coordinates": [74 19.439257458711324,75 51.7805779429498976 ]77 },78 "properties": {}79 },80 {81 "type": "Feature",82 "geometry": {83 "type": "Point",84 "coordinates": [85 19.43963296797358,86 51.7806410006755387 ]88 },89 "properties": {}90 },91 {92 "type": "Feature",93 "geometry": {94 "type": "Point",95 "coordinates": [96 19.44012113001449,97 51.78069078302806498 ]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 parameters | Description |
---|---|
| The base URL for calling TomTom services. |
| The version of the service to call. |
| The authorization key for access to the API. |
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
1{2 type BatchQuery {3 batchItems : [Query!]!4 }56 type Query {7 query: String!8 post: [Point!]!9 }1011 type Point {12 type: String!13 geometry: Geometry!14 properties: Properties15 }1617 type Geometry {18 type: String!19 coordinates : [longitude, latitude]!20 }2122 type Properties {23 heading: Float24 timestamp: String25 }26}
Fields to submit to the Asynchronous Snap To Roads Submission
Structure of the BatchQuery object | |
---|---|
Field | Description |
|
|
Structure of the Query object | |
---|---|
Field | Description |
| Query to the Snap To Roads service. |
| An array of Point elements.
|
Structure of the Point object | |
---|---|
Field | Description |
| The value is always set as a |
| Object in GeoJSON format that represents a single point. |
| It may contain data in order to increase the likelihood of correctly snapping the point. |
Structure of the Geometry object | |
---|---|
Field | Description |
| The value is always set as a |
| Point's longitude and latitude coordinates. |
Structure of the Properties object | |
---|---|
Field | Description |
| The directional heading of the vehicle in degrees for travel along a segment of roadway.
|
| The timestamp of obtained point.
|
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 headers | Description |
---|---|
Contains the content encoding (usually a compression algorithm), that
the client is able to understand. | |
Tracking-ID | Specifies an identifier for the request.
Value: |
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
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 | |
---|---|
Field | Description |
| A unique identifier ( |
Successful response
For a valid Asynchronous Snap To Roads Submission request, the endpoint returns its response body in JSON format.
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.
Field | Description |
---|---|
| Main |
| One of a server-defined set of error codes. |
| A human-readable description of the error code. |
1{2 "detailedError": {3 "code": "INVALID_REQUEST",4 "message": "Payload is not a valid JSON format."5 }6}
HTTP response codes
Code | Meaning & possible causes |
---|---|
| OK |
| Bad request |
| Forbidden: The supplied API Key is not valid for this request. |
| Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource. |
| Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key. |
| Internal Server Error |
| Service currently unavailable: The service is currently unavailable. |
| 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.
Header | Description |
---|---|
Indicates that cross-origin resource sharing (CORS) is allowed. | |
Lists the set of supported HTTP methods. The header is sent in case a
| |
Indicates which encodings were applied to the response body. | |
Contains information about the size of the response body. | |
Indicates the media type of the resource returned. | |
Contains the date and time at which the message was originated. For
details check
RFC 7231. | |
Tracking-ID | An identifier for the request.
Value: |