getHeaderOnlyByTileId

Last edit: 2026.11.04

Returns only the smart layer header for one tile, with its layer versions and lifetime, without the payload. Use it to check whether a tile changed before you download it.

Request data

HTTP method: `POST`

URL request format

1
https://{serviceURL}/getHeaderOnlyByTileId?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

The body is a zserio-encoded TileId object.

HTTP request headers

Header	Description
`Content-Type`	`application/x-zserio-object`, the zserio media type.
`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 header. 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 SmartLayerHeader object. It’s the same header that starts a SmartLayerTile, without the layer data, so it’s small: for a tile with 10 layers, it’s 72 bytes.

The header has one entry per layer, in the same order in each list:

Field	Description
`numDataLayers`	The number of data layers in the tile.
`availableLayers`	The data layer IDs, in the order the layers appear in the tile.
`layerLifetime`	For each layer, its lifetime type, for example static, and its version ID.
`packagingDetails`	For each layer, how its data is packaged: compression, delta encoding, encryption and signature.
`legalInformation`	Optional. Legal information, such as copyright, for all layers.

To check whether a tile changed, compare the version IDs in layerLifetime with the ones you hold. Then request only the changed layers with getDeltaLayerByTileId.

HTTP response headers

Header	Description
`Location`	The URL of the file that holds the header.
`ETag`	The entity tag of the header, for conditional requests. If you send it in `If-None-Match` and the header 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 `SmartLayerHeader`.
`204`	The tile is empty, outside the area your product covers, or at a level the service doesn’t serve. Cache an empty result and don’t retry.
`303`	See other. The header is at the URL in the `Location` response header. TomTom’s service usually answers with this code.
`304`	Not modified since the version identified in `If-None-Match`.
`404`	Not found. The tile is outside the service’s spatial extent.
`410`	Gone. The Smart Layer Tile Service is decommissioned. Ask the NDS.Live Registry for another service.
`500`	Internal server error.