getDeltaLayerByTileId

Last edit: 2026.11.04

Returns a smart layer tile with data only for the layers that changed since your map data component last downloaded the tile. Use it to keep tiles current with less over-the-air data.

How a delta update works

Your map data component keeps its cached tiles current in three stages.

Once per service: your map data component checks which methods the service supports. The service lists them in its openapi.json.
- If getDeltaLayerByTileId is listed, the service supports delta updates. getTileServiceCapabilities reports this as the GET_DELTA_LAYER_BY_TILE_ID flag.
- If it isn’t listed, the service doesn’t offer delta updates. Download whole tiles with getLayerByTileId.
When downloading a tile: your map data component stores the layer versions from the tile’s header with the cached tile.
When checking the tile for changes: your map data component sends those versions in a getDeltaLayerByTileId request. The service compares them with its current versions and returns only the layers that changed. Your map data component replaces those layers in its cached tile.

To skip a layer your map data component doesn’t need, send VERSION_ID_NO_UPDATE as its version.

Request data

HTTP method: `POST`

URL request format

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

Field	Contains
`tileId`	The ID of the tile you’re checking.
`sourceLayerInfo`	The layers your map data component holds for that tile, in the three fields below.
`sourceLayerInfo.availableLayers`	The layer IDs.
`sourceLayerInfo.numDataLayers`	The number of layers.
`sourceLayerInfo.versionId`	The version of each layer, in the same order as `availableLayers`.

The versions come from the tile’s header, which your map data component received with the tile.

The service compares your versions with its own, and sends data only for the layers that differ.

Skip a layer

To leave a layer out of the response, keep its ID in availableLayers and send VERSION_ID_NO_UPDATE as its version in versionId. The service then omits the layer, even if it was deleted.

Don’t remove the layer ID from availableLayers. The service then adds that layer to the response anyway, in full and not delta-encoded.

VERSION_ID_NO_UPDATE is the NDS.Live schema’s constant for the reserved version 0xFFFFFFFFFFFFFFFF. Code generated with zserio from NDS.Live schema version 2026.06 or later includes this constant, so you can use it by name. With an older schema version, or without generated code, use its value, 0xFFFFFFFFFFFFFFFF.

HTTP request headers

Header	Description
`Content-Type`	`application/x-zserio-object`, the zserio media type.

Response data

Response body

On success, the body is a zserio-encoded SmartLayerTile object. Each layer’s header carries a delta encoding type:

Delta encoding type	What it means	Payload
`NO_UPDATE`	Your version of the layer is the current one.	None
`NO_DELTA`	The service now has a different version of the layer.	The current, whole layer
`LAYER_DELETED`	The layer is in your request, but the service doesn’t have it.	None

NO_UPDATE is a delta encoding type that the service sends. Don’t confuse it with VERSION_ID_NO_UPDATE, which your map data component sends to skip a layer.

Delta updates work per layer, not as a byte-level difference: a changed layer comes back whole. Other delta encoding types in the schema, such as VCDIFF, aren’t used by TomTom’s service.

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 a `SmartLayerTile` with only the modified layers.
`204`	The tile is empty, or outside the area your product covers. Cache the empty result and don’t retry.
`400`	Bad request. The request body can’t be processed.
`404`	Not found.
`410`	Gone. The Smart Layer Tile Service is decommissioned. Ask the NDS.Live Registry for another service.
`500`	Internal server error.