Sorry, you need to enable JavaScript to visit this website.

Asynchronous Snap to Roads Submission

 

Service version: 1
Last edit: 2021.11.22

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.

On this page

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.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the response.

Asynchronous Snap To Roads Submission

HTTPS method: POST

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
POST https://baseURL/snap-to-roads/batch/versionNumber?key=Your_API_Key

Example

POST https://api.tomtom.com/snap-to-roads/batch/1?key=Your_API_Key

curl command

curl -X POST 'https://api.tomtom.com/snap-to-roads/batch/1/?key=Your_API_Key -d '{
  "batchItems": [
    {
      "query": "/snap-to-roads?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},frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric",
      "post": {
        "points": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.4389141359581,
                51.78057462411982
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.439257458711324,
                51.78057794294989
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.43963296797358,
                51.78064100067553
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.44012113001449,
                51.780690783028064
              ]
            },
            "properties": {}
          }
        ]
      }
    },
{
      "query": "/snap-to-roads?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},frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=imperial",
      "post": {
        "points": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.4389141359581,
                51.78057462411982
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.439257458711324,
                51.78057794294989
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.43963296797358,
                51.78064100067553
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.44012113001449,
                51.780690783028064
              ]
            },
            "properties": {}
          }
        ]
      }
    }
  ]
}
' 

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
Parameter 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.

▲ Return to top

Request body

Follow the request body schema in order to prepare a valid POST request.

Request schema

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
{
    type BatchQuery {
        batchItems : [Query!]!
    }

    type Query {
        query: String!
        post: [Point!]!
    }

    type Point {
        type: String!
        geometry: Geometry!
        properties: Properties
    }

    type Geometry {
        type: String!
        coordinates : [longitude, latitude]!
    }

    type Properties {
        routeIndex: integer
    }
}

Fields to submit Asynchronous Snap To Roads Submission

Structure of the BatchQuery object
Field Description
batchItems
array
  • Array of Query elements.
  • It should contain at least 1 and at most 100 elements.
Structure of the Query object
Field Description
query
string
Query to Snap-To-Roads service.
post
array
  • Array of Point elements.
  • It should contain at least 2 and at most 100 000 elements.
Structure of the Point object
Field Description
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
Field Description
type
string
The value is always set as a Point.
coordinates
array
Point's longitude and latitude coordinates.
Structure of the Properties object
Field Description
routeIndex
integer
Route index to match the point to.

Example

{
  "batchItems": [
    {
      "query": "/snap-to-roads?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},frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=metric",
      "post": {
        "points": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.4389141359581,
                51.78057462411982
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.439257458711324,
                51.78057794294989
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.43963296797358,
                51.78064100067553
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.44012113001449,
                51.780690783028064
              ]
            },
            "properties": {}
          }
        ]
      }
    },
{
      "query": "/snap-to-roads?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},frc,formOfWay,roadUse,laneInfo{numberOfLanes}}},distances{total,road,offRoad}}&vehicleType=PassengerCar&measurementSystem=imperial",
      "post": {
        "points": [
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.4389141359581,
                51.78057462411982
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.439257458711324,
                51.78057794294989
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.43963296797358,
                51.78064100067553
              ]
            },
            "properties": {}
          },
          {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.44012113001449,
                51.780690783028064
              ]
            },
            "properties": {}
          }
        ]
      }
    }
  ]
}

▲ Return to top

HTTP request headers

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

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header 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>

▲ Return to top

Response data

Successful response

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

JSON schema

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

    type BatchResponse {
       batchId: String!
    }

Response field structure

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

Structure of the BatchResponse object
Field Description
batchId
string
A unique identifier (UUID) of the asynchronous request.

▲ Return to top

Successful response examples

Example response

  {
    "batchId": "45e0909c-625a-4822-a060-8f7f88498c0e"
  }

Error response

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

Error response field structure

Field Description
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

{
  "detailedError" : {
    "code" : "INVALID_REQUEST",
    "message" : "Payload is not a valid JSON format."
  }
}

▲ Return to top

HTTP response codes

Code Meaning & 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 Snap to Roads endpoint.

Header Description
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>

▲ Return to top