Request and response patterns

Each Smart Layer Tile Service offers a set of methods, such as getLayerByTileId. You call a method by sending an HTTP POST request to its URL. All methods follow the same patterns: how you build the request, how you read the response, and what your map data component does with each HTTP status code. This page describes them once, so the method pages only list what’s specific to each method.

Requests

URL format

The endpoint URLs in your onboarding email end with /openapi.json. That address returns the service’s OpenAPI description: a JSON file that lists the service’s methods. To call a method, replace /openapi.json with the method name:

1
https://{serviceURL}/{method}?apiKey={Your_API_Key}

For example, for the Intelligent Speed Assistance (ISA) evaluation endpoint from the Endpoint quick start:

1
https://api.tomtom.com/ndslive/smart-layer-service/eval/6/ISA-2026-06/XXX-ae556b96e330/getLayerByTileId?apiKey={Your_API_Key}

Authentication

Add your API key as the apiKey query parameter to every request.

HTTP method and request body

The NDS.Live standard defines each Smart Layer Tile Service as a set of named methods, and the last part of the URL is the method’s name. So the HTTP method doesn’t tell what a request does, as it often does in web APIs: you call every method with POST, including methods that only return data, such as getServiceNodeLegalInfo.

• Call every method with an HTTP POST request, even if it takes no request body.
• Fetch the service description, openapi.json, with GET.

Whether a method needs a request body depends on its type:

• Tile methods return map data for one tile, so the body tells the service which tile you want, or which layer of it.
• Service metadata methods return information about the service itself, such as the layers it contains, the area it covers, or the methods it implements. They need no body.

Each method page lists its request body.

Bodies are zserio

Request and response bodies are binary objects encoded with zserio, the schema language and serialization framework that NDS.Live is defined in. They aren’t JSON or text, so you can’t read or write them by hand. Your map data component encodes every request body and decodes every response:

For example, the request body of getLayerByTileId for tile 545419775 is 4 bytes, the tile ID as a 32-bit integer:

1
20 82 71 FF

The response begins with the same tile ID, followed by the tile’s header: the number of layers, and their IDs.

1
20 82 71 FF  0A  01 02 03 04 08 09 0A 0B 0C 0D  ...
2
tile ID      10  layer IDs 1, 2, 3, 4, 8, 9, 10, 11, 12, 13

Because the bodies are binary, two common tools only partly work with this API:

• curl: works for openapi.json, which is plain JSON. While curl is a quick way to validate your API key and endpoint, it can’t encode a request body or decode a tile. It can only send a body you’ve already encoded, from a file, and save the binary response to a file.
• OpenAPI client generators, such as OpenAPI Generator: don’t produce a working client, because they expect JSON or XML and don’t support zserio.

Responses

On success, the response body is a zserio-encoded object. The returned object type depends on the method: for example, getLayerByTileId returns a SmartLayerTile, and getHeaderOnlyByTileId returns a SmartLayerHeader. Method pages in this section list zserio objects each method returns.

The methods getLayerByTileId, getHeaderOnlyByTileId, getServiceDefinition and getSpatialExtent answer with 303 See Other and a Location header that points to a file on a TomTom content delivery network. Make sure your HTTP client follows redirects. The Location URL carries a short-lived access token, so don’t cache it or write it to logs.

An error response can have a JSON body, but base your map data component’s error handling on the HTTP status code only.

HTTP status codes

The table lists HTTP status codes, their meaning, and what your map data component should do when it gets one.

¹When a product isn’t granted or doesn’t exist, the Smart Layer Tile Service returns 403 or 404. The NDS.Live Registry returns 200 with an empty node list.

When you contact TomTom support, include the full request URL without your API key, the HTTP status code and the time of the request in UTC.

Error messages

An error response can have a body that says what went wrong. The formats aren’t aligned yet, and the messages can change, so rely on the HTTP status code only. Depending on which part of TomTom’s platform answers, the body has one of these JSON formats:

1
{
2
  "message": "Requested layer id 5 was not found",
3
  "code": 404
4
}

1
{
2
  "detailedError": {
3
    "code": "Unauthorized",
4
    "message": "You are missing valid authentication credentials"
5
  }
6
}

1
{
2
  "timestamp": "2026-10-12T10:04:31.466Z",
3
  "status": 404,
4
  "error": "Not Found",
5
  "path": "/eval/6/ADAS-road-2026-06/XXX-000000000000/getTileServiceCapabilities"
6
}

The table lists the errors seen on TomTom’s ADAS Road Model evaluation service, with their cause:

Why 410 matters

A Smart Layer Tile Service can be permanently shut down (decommissioned). This can happen, for example, when TomTom moves to a module version that older map data components can’t read. From then on, every method of that service returns 410. There’s no grace period: discard all data your map data component cached from that service.

What happens next depends on how your map data component finds its services:

• Through the NDS.Live Registry — your map data component switches to the replacement on its own, with no change to its code or configuration.
• With a hardcoded service URL, as in an evaluation setup — your map data component stops getting data until you replace the URL in its code or configuration. In a vehicle, that means shipping an update. Get the new URL from the NDS.Live Registry. TomTom also tells you about the decommissioning by email.

A file store isn’t affected, because your integration reads it locally and doesn’t call the service.

Tracking IDs

Every response from the TomTom API gateway, which sits in front of the Smart Layer Tile Services, has a Tracking-Id header that identifies the request. If you send your own Tracking-Id request header, the response returns the same value. Otherwise, the gateway generates one.

A file that a method redirects you to comes from a content delivery network and has no Tracking-Id. For those methods, the tracking ID is in the 303 response. If your HTTP client follows redirects without showing the 303, set your own Tracking-Id request header, so you know the ID.

When you report a problem with a request, include its tracking ID.

Keeping tiles up to date

Map data changes over time: TomTom updates the map regularly, and every layer in a tile carries a version and a lifetime. A map data component that downloads every tile again to stay current wastes bandwidth, which is costly on a vehicle’s mobile data connection, and takes longer to get the data that did change. For example, a full request for one level-13 tile returned about 360 KB. A delta request for the same, unchanged tile returned 637 bytes.

Three patterns help your map data component find out what changed and download only those changes:

• Conditional requests — get a resource only if it changed since your last request
• Header-only checks — read a tile’s layer versions without downloading its payload
• Delta updates — get only the layers of a tile that changed

Conditional requests

A conditional request returns a resource only if it changed since your last request. If nothing changed, the service returns 304, and your map data component keeps its cached copy. You can send conditional requests with these methods:

• getLayerByTileId
• getHeaderOnlyByTileId
• getServiceDefinition
• getSpatialExtent

getRegistryMetadata doesn’t support conditional requests, although its OpenAPI description lists them.

Header-only checks

getHeaderOnlyByTileId returns only a tile’s header, with its layer versions and lifetime, and no payload. Use it to check whether a tile changed before you download it.

Delta updates

To get only the layers of a tile that changed since your map data component last downloaded it, use getDeltaLayerByTileId.

Related resources

• Smart Layer Tile Service: the list of methods
• Access and accounts: Your endpoints
• Endpoint quick start: Step 4: SLS endpoint check
• getLayerByTileId
• getHeaderOnlyByTileId
• getDeltaLayerByTileId
• getSingleDataLayerByTileId
• getServiceDefinition
• getServiceModuleDefinition
• getServiceNodeLegalInfo
• getServiceNodeSystemReference
• getTileServiceCapabilities
• getSpatialExtent
• getRegistryMetadata
• Architecture overview: NDS.Live Registry
• Ways to get map data: streaming tiles from an endpoint compared with downloading a file store in bulk
• Access and accounts: get an API key with NDS.Live enabled
• zserio on GitHub
• OpenAPI Generator
• pack.nds.live