Migration Guide

Service version: 2

Last edit: 2026.04.09

TomTom Orbis Maps

The Map Display API Orbis v2 is now available as a Public Preview. We recommend migrating to take advantage of the latest features. See the Public Preview page to learn what this means.

This guide helps you migrate to the Map Display API Orbis v2 endpoints. It covers differences from both the TomTom Maps endpoints and the Orbis v1 endpoints.

General changes

Changes in authentication

Aspect	Orbis v2
API Key (header)	`TomTom-Api-Key` header (recommended)
API Key (query)	`key` query parameter (still supported, but shouldn't be treated as the default option)

Error message format

Error messages are returned in JSON format in the following structure:

Field	Description
`detailedError`	Main object of the error response. Consists of `code` and `message` properties.
`detailedError.code`	One of a server-defined set of error codes.
`detailedError.message`	A human-readable description of the error code.

Exemplary error message
1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Invalid tile position arguments"
5  }
6}

Migrating from TomTom Maps

This section describes the changes when migrating from the TomTom Maps Map Display API endpoints to the Orbis v2 endpoints.

Vector tile v1 endpoint

Where do I find the new endpoint

The new Orbis v2 Vector Tile endpoint has the following path:

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.pbf

Changes in the endpoint base path

Aspect	TomTom Maps	Orbis v2
Base path	`/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.pbf`	`/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}`
Version mechanism	`versionNumber` path parameter (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)
`layer`	Required path parameter (`basic`, `hybrid`, `labels`, `poi`)	Moved to optional query parameter.
`style`	Required path parameter (`main`)	Removed. Not applicable in Orbis v2 vector tiles.

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.
`view`	`geopoliticalView`	Renamed.
Not available	`layer`	Moved from the request path. Available value(s): `basic`.
`language`	Not available	Removed. All available translations for the specific features are included in the tile by default.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/vnd.mapbox-vector-tile`.

Changes in response content type

TomTom Maps	Orbis v2
`image/pbf`	`application/vnd.mapbox-vector-tile`

The detailed information about TomTom Orbis Maps tile content can be found on the Tile Content page.

Vector tile v2 endpoint

Where do I find the new endpoint

The new Orbis v2 Vector Tile endpoint has the following path:

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/tile/{layer}/{zoom}/{X}/{Y}.pbf

Changes in the endpoint base path

Aspect	TomTom Maps	Orbis v2
Base path	`/map/{versionNumber}/tile/{layer}/{zoom}/{X}/{Y}.pbf`	`/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}`
Version mechanism	`versionNumber` path parameter (value: `2`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)
`layer`	Required path parameter (`basic`, `hybrid`, `labels`, `poi`)	Moved to optional query parameter.

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.
`view`	`geopoliticalView`	Renamed.
Not available	`layer`	Moved from the request path. Available value(s): `basic`.
`include`	Not available	Road restrictions are not supported by the Orbis tiles.
`vehicleWeight`	Not available	Road restrictions are not supported by the Orbis tiles.
`vehicleAxleWeight`	Not available	Road restrictions are not supported by the Orbis tiles.
`numberOfAxles`	Not available	Road restrictions are not supported by the Orbis tiles.
`vehicleWidth`	Not available	Road restrictions are not supported by the Orbis tiles.
`vehicleHeight`	Not available	Road restrictions are not supported by the Orbis tiles.
`generalLoadType`	Not available	Road restrictions are not supported by the Orbis tiles.
`dangerousGoodsLoadType`	Not available	Road restrictions are not supported by the Orbis tiles.
`adrCategory`	Not available	Road restrictions are not supported by the Orbis tiles.
`commercialVehicle`	Not available	Road restrictions are not supported by the Orbis tiles.
`travelMode`	Not available	Road restrictions are not supported by the Orbis tiles.
`emissionClass`	Not available	Road restrictions are not supported by the Orbis tiles.
`engineType`	Not available	Road restrictions are not supported by the Orbis tiles.
`travelModeProfile`	Not available	Road restrictions are not supported by the Orbis tiles.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/vnd.mapbox-vector-tile`.

Changes in response content type

TomTom Maps	Orbis v2
`image/pbf`	`application/vnd.mapbox-vector-tile`

The detailed information about TomTom Orbis Maps tile content can be found on the Tile Content page.

Raster tile endpoint

Where do I find the new endpoint

The new Orbis v2 Raster Map Tile endpoint has the following path:

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/raster/tile/{zoom}/{X}/{Y}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.{format}

Changes in the endpoint base path

Aspect	TomTom Maps	Orbis v2
Base path	`/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.{format}`	`/maps/orbis/display/raster/tile/{zoom}/{X}/{Y}`
Version mechanism	`versionNumber` path parameter (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)
`layer`	Required path parameter (`basic`, `hybrid`, `labels`)	Removed from path. Orbis v2 raster endpoint serves `basic` layer only.
`style`	Required path parameter (`main`, `night`)	Moved to optional query parameter (`street-light`, `street-dark`).
`format`	Required path parameter (`png`, `jpg`)	Removed from path. Response format is `image/png` by default.

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.
Not available	`style`	Optional. Values: `street-light`, `street-dark`.
`tileSize`	`tileSize`	No change. Values: `256`, `512`.
`view`	`geopoliticalView`	Renamed.
`language`	Not available	Removed from query. Use the `Accept-Language` request header instead.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept-Language`	Not available	Optional. Replaces the `language` query parameter.
`Accept`	Not available	Optional. Value: `image/png`.

Changes in response content type

TomTom Maps	Orbis v2
`image/png`, `image/jpg`	`image/png`

Satellite Tile endpoint

Where do I find the new endpoint

The new Orbis v2 Satellite Tile endpoint has the following path:

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/satellite/tile/{zoom}/{X}/{Y}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/tile/sat/{style}/{zoom}/{X}/{Y}.jpg

Changes in the endpoint base path

Aspect	TomTom Maps	Orbis v2
Base path	`/map/{versionNumber}/tile/sat/{style}/{zoom}/{X}/{Y}.jpg`	`/maps/orbis/display/satellite/tile/{zoom}/{X}/{Y}`
Version mechanism	`versionNumber` path parameter (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)
`style`	Required path parameter (value: `main`)	Moved to optional query parameter. Value: `main`.

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.
Not available	`style`	Optional. Moved from request path. Value: `main`.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `image/jpg`.

Changes in response content type

TomTom Maps	Orbis v2
`image/jpg`	`image/jpg`

Hillshade tile endpoint

Where do I find the new endpoint

The new Orbis v2 Hillshade Tile endpoint has the following path:

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/tile/{layer}/{type}/{zoom}/{X}/{Y}.png

Changes in the endpoint base path

Aspect	TomTom Maps	Orbis v2
Base path	`/map/{versionNumber}/tile/{layer}/{type}/{zoom}/{X}/{Y}.png`	`/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}`
Version mechanism	`versionNumber` path parameter (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)
`layer`	Required path parameter (value: `hill`)	Removed. Dedicated hillshade endpoint path used instead.
`type`	Required path parameter (value: `main`)	Moved to optional query parameter with default value: `dem`.

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.
Not available	`type`	Optional. Default value: `dem`.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `image/png`.

Changes in response content type

TomTom Maps	Orbis v2
`image/png`	`image/png`

Copyrights endpoint

Map copyrights

Where do I find the new endpoint

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/copyrights

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/copyrights

Changes in the endpoint path

Aspect	TomTom Maps	Orbis v2
Path	`/map/{versionNumber}/copyrights`	`/maps/orbis/copyrights`
Version mechanism	`versionNumber` path parameter (value: `2`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/json`.

Changes in response content type

TomTom Maps	Orbis v2
`text/plain`	`application/json`

Map service copyrights (Caption)

Where do I find the new endpoint

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/copyrights/caption?apiVersion=2&key={Your_API_Key}

instead of:

get

TomTom Maps URL format

https://api.tomtom.com/map/{versionNumber}/copyrights/caption.json

Changes in the endpoint path

Aspect	TomTom Maps	Orbis v2
Path	`/map/{versionNumber}/copyrights/caption.json`	`/maps/orbis/copyrights/caption`
Version mechanism	`versionNumber` path parameter (value: `2`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`apiVersion`	Required (query parameter or `TomTom-Api-Version` header). Supported value is `2`.

Changes in request headers

Header name	TomTom Maps	Orbis v2
`TomTom-Api-Version`	Not available	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/json`.

Changes in response content type

TomTom Maps	Orbis v2
`application/json`	`application/json`

Migrating from Orbis v1

This section describes the changes when migrating from the Orbis v1 Map Display API endpoints to the Orbis v2 endpoints.

Vector tile endpoint

Endpoint URL

The base path has changed. The API version also changes:

get

Orbis v1 URL format

https://api.tomtom.com/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.pbf

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.pbf`	`/maps/orbis/display/vector/tile/{zoom}/{X}/{Y}`
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.
`layer`	`layer`	No change.
`view`	`geopoliticalView`	Renamed.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Required (value: `1`)	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/vnd.mapbox-vector-tile`.

Changes in response content type

Orbis v1	Orbis v2
`image/pbf`	`application/vnd.mapbox-vector-tile`

Raster map tile endpoint

Endpoint URL

The base path has changed. The API version also changes:

get

Orbis v1 URL format

https://api.tomtom.com/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.png

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/raster/tile/{zoom}/{X}/{Y}

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.png`	`/maps/orbis/display/raster/tile/{zoom}/{X}/{Y}`
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.
`style`	`style`	No change.
`tileSize`	`tileSize`	No change.
`view`	`geopoliticalView`	Renamed.
`language`	Not available	Removed from query. Use the `Accept-Language` request header instead.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Required (value: `1`)	Required (value: `2`).
`Accept-Language`	Not available	Optional. Replaces the `language` query parameter.
`Accept`	Not available	Optional. Value: `image/png`.

Changes in response content type

Orbis v1	Orbis v2
`image/png`	`image/png`

Satellite tile endpoint

Endpoint URL

The base path has changed. The API version also changes:

get

Orbis v1 URL format

https://api.tomtom.com/maps/orbis/map-display/tile/satellite/{zoom}/{X}/{Y}.jpg

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/satellite/tile/{zoom}/{X}/{Y}

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/map-display/tile/satellite/{zoom}/{X}/{Y}.jpg`	`/maps/orbis/display/satellite/tile/{zoom}/{X}/{Y}`
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.
`style`	`style`	No change.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Optional (value: `1`)	Required (value: `2`).
`Accept`	Not available	Optional. Value: `image/jpg`.

Changes in response content type

Orbis v1	Orbis v2
`image/jpg`	`image/jpg`

Hillshade tile endpoint

Endpoint URL

The base path has changed. The API version also changes:

get

Orbis v1 URL format

https://api.tomtom.com/maps/orbis/map-display/tile/hillshade/{zoom}/{X}/{Y}.png

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/map-display/tile/hillshade/{zoom}/{X}/{Y}.png`	`/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}`
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.
`type`	`type`	No change.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Optional (value: `1`)	Required (value: `2`).
`Accept`	Not available	Optional. Value: `image/png`.

Changes in response content type

Orbis v1	Orbis v2
`image/png`	`image/png`

Copyrights endpoint

Map copyrights

Endpoint URL

The base URL path stays the same. Only the API version changes:

get

Orbis v1/v2 URL format

https://api.tomtom.com/maps/orbis/copyrights

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/copyrights`	The same path.
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Required (value: `1`)	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/json`.

Changes in response content type

Orbis v1	Orbis v2
`text/plain`	`application/json`

Map service copyrights (Caption)

Endpoint URL

get

Orbis v1 URL format

https://api.tomtom.com/maps/orbis/copyrights/caption.json

get

Orbis v2 URL format

https://api.tomtom.com/maps/orbis/copyrights/caption

Changes in the endpoint path

Aspect	Orbis v1	Orbis v2
Path	`/maps/orbis/copyrights/caption.json`	`/maps/orbis/copyrights/caption`
Version mechanism	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `1`)	`apiVersion` query parameter or `TomTom-Api-Version` header (value: `2`)

Changes in request query parameters

Orbis v1 parameter	Orbis v2 parameter	Notes
`apiVersion`	`apiVersion`	Required. Value changed from `1` to `2`.

Changes in request headers

Header name	Orbis v1	Orbis v2
`TomTom-Api-Version`	Required (value: `1`)	Required (value: `2`).
`Accept`	Not available	Optional. Value: `application/json`.

Changes in response content type

Orbis v1	Orbis v2
`application/json`	`application/json`