getServiceDefinition

Last edit: 2026.11.04

Returns the smart layer definition of the service: the data layers it contains. For each layer, it gives the layer ID, a readable name, the module and module version, and the zserio type of the layer data.

Your map data component needs this to decode tiles: the layer IDs in a tile header refer to the layers defined here. The definition changes only when the service’s layers change, so cache it and use a conditional request to check for a new version.

Request data

HTTP method: `POST`

URL request format

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

serviceURL is your Smart Layer Tile Service endpoint, without /openapi.json.
Your_API_Key is a My.TomTom API key with NDS.Live services enabled.

Request body

This method takes no request body.

HTTP request headers

Header	Description
`If-None-Match`	Optional. The entity tag for conditional requests.

Conditional requests

To send a conditional request:

Store the entity tag from the ETag response header, quotation marks included.
On the next request for the same resource, send it in If-None-Match.
If nothing changed, the service returns 304 with an empty body, and you keep using your cached copy. For a method that redirects to a file, the service answers 304 itself, without redirecting.

Send the entity tag in If-None-Match, not in an ETag request header. The ETag request header is deprecated.

Response data

Response body

TomTom’s Smart Layer Tile Service answers with 303 See Other. The Location response header points to a file on a TomTom content delivery network, which holds the definition. Make sure your HTTP client follows redirects. Most clients do this by default. The Location URL carries a short-lived access token, so don’t cache it or write it to logs.

The file is a zserio-encoded SmartLayerDefinition object, with a layerDefinitions list of one DataLayerDefinition per layer:

Field	Description
`dataLayerId`	The layer ID that tiles use in their header.
`name`	A readable name for the layer, for example `Road Layer`.
`contentType`	What the layer holds: features, geometry, attributes or relations.
`lifetime`	The lifetime type of the layer, for example static.
`layerDescriptor`	The module, for example `ROAD`; the module version, for example `2026.03`; the minimum module version your map data component needs to parse the data; and the zserio type of the layer data, for example `road.layer.RoadLayer`.
`layerMetadata`	Metadata for the layer, defined by its module.
`isCustomExtension`	`true` if the layer is a custom extension, not part of the NDS.Live standard.
`signatureDefinition`	Optional. How the layer is signed, if it’s signed.

HTTP response headers

Header	Description
`Location`	The URL of the file that holds the definition.
`ETag`	The entity tag of the definition, for conditional requests. The `303` response and the file have the same entity tag. If you send it in `If-None-Match` and the definition hasn’t changed, the service answers `304` without redirecting.

HTTP status codes

Besides the codes below, any method can return the common errors, for example 401 for a missing API key.

Code	Meaning
`200`	OK. The response body holds the `SmartLayerDefinition`.
`302`	Found. The service redirects a `GET` request with this code. The definition is at the URL in the `Location` response header.
`303`	See other. The service redirects a `POST` request with this code. The definition is at the URL in the `Location` response header. Follow it right away, and don’t cache it.
`304`	Not modified since the version identified in `If-None-Match`.
`404`	Not found.
`410`	Gone. The Smart Layer Tile Service is decommissioned. Ask the NDS.Live Registry for another service.
`500`	Internal server error.