Migration Guide

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

General changes

Changes in authentication

Attributes mechanism

In Orbis v2 a unified Attributes mechanism is introduced for controlling response content. It provides a flexible way to specify which attributes, tags, data fields etc. to include or exclude in API responses.

The Attributes mechanism consists of:

• attributes query parameter — Available only for vector tiles endpoints (optional). Specifies which vector tile tags to include and which other attributes to apply (e.g., *,tags(road_category),roadCategories(motorway)). Takes precedence over headers when both are present.
• Attributes request header — For vector tiles: specifies which tags to include and which other attributes to apply. For Incident Details: specifies which JSON response fields to include (required).
• Attributes-Exclude request header — Specifies which tags or fields to omit. Optional for all endpoints, used only with Attributes request header.

This mechanism replaces previous parameters such as fields (for JSON response fields selection), tags (for vector tile tags selection) and several vector tiles-related filtering parameters (roadTypes, roadCategoryFilter, categoryFilter, timeValidityFilter).

For detailed information about Attributes syntax, available values, and usage examples, refer to the Attributes section in each respective Orbis v2 endpoint documentation.

Error message format

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

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 Traffic API endpoints to the Orbis v2 endpoints.

Flow vector tiles endpoint

Where do I find the new endpoint

The new Orbis v2 Flow vector tiles endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y}

instead of:

1
https://api.tomtom.com/traffic/map/4/tile/flow/{type}/{zoom}/{x}/{y}.pbf

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Supported attributes

Changes in vector tile tags

Note: Tags marked as explicit in Orbis v2 endpoints have to be explicitly listed in Attributes/Attributes-Exclude headers or attributes query parameter.
They are not included solely by using * wildcard.

Changes in response content type

Changes in response headers

Flow raster tiles endpoint

Where do I find the new endpoint

The new Orbis v2 Flow raster tiles endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y}

instead of:

1
https://api.tomtom.com/traffic/map/4/tile/flow/{style}/{zoom}/{x}/{y}.png

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response content type

Response content type for successful requests remains as image/png. Error messages are returned as application/json only.

Incident vector tiles endpoint

Where do I find the new endpoint

The new Orbis v2 Incident vector tiles endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y}

instead of:

1
https://api.tomtom.com/traffic/map/4/tile/incidents/{zoom}/{x}/{y}.pbf

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Supported attributes

Changes in protobuf tags

Note: Tags marked as explicit in Orbis v2 endpoints have to be explicitly listed in Attributes/Attributes-Exclude headers or attributes query parameter.
They are not included solely by using * wildcard.

Changes in response content type

Changes in response headers

Incident raster tiles endpoint

Where do I find the new endpoint

The new Orbis v2 Incident raster tiles endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}

instead of:

1
https://api.tomtom.com/traffic/map/4/tile/incidents/{style}/{zoom}/{x}/{y}.png

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response content type

Response content type for successful requests remains as image/png. Error messages are returned as application/json only.

Incident details v4 endpoint

Where do I find the new endpoint

The new Orbis v2 Incident details endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/incidents/details

instead of:

1
https://api.tomtom.com/traffic/services/4/incidentDetails/{style}/{boundingBox}/{zoom}/{trafficModelID}/{format}

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response fields

For more information about response fields available in Orbis v2 counterpart, check this documentation .

Changes in response headers

Changes in response content type

Incident details v5 endpoint

Where do I find the new endpoint

The new Orbis v2 Incident details endpoint has the following path:

1
https://api.tomtom.com/maps/orbis/traffic/incidents/details

instead of:

1
https://api.tomtom.com/traffic/services/5/incidentDetails

Changes in the endpoint base path

Changes in request query parameters

Changes in request headers

Changes in response fields

Changes in response headers

Migrating from Orbis v1

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

Flow vector tiles endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.pbf

1
https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y}

Changes in the endpoint path

Changes in request query parameters

Changes in request headers

Supported attributes

Changes in protobuf tags

Note: Tags marked as explicit in Orbis v2 endpoints have to be explicitly listed in Attributes/Attributes-Exclude headers or attributes query parameter.
They are not included solely by using * wildcard.

Changes in response content type

Flow raster tiles endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.png

1
https://api.tomtom.com/maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y}

Changes in the endpoint path

Changes in request query parameters

Changes in response content type

Response content type for successful requests remains as image/png. Error messages are returned as application/json only.

Incident vector tiles endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.pbf

1
https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y}

Changes in the endpoint path

Changes in request query parameters

Changes in request headers

Supported attributes

Changes in protobuf tags

Note: Tags marked as explicit in Orbis v2 endpoints have to be explicitly listed in Attributes/Attributes-Exclude headers or attributes query parameter.
They are not included solely by using * wildcard.

Changes in response headers

Changes in response content type

Incident raster tiles endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.png

1
https://api.tomtom.com/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}

Changes in the endpoint path

Changes in request query parameters

Changes in response content type

Response content type for successful requests remains as image/png. Error messages are returned as application/json only.

Incident details endpoint

Endpoint URL

The base path changes and the API version changes:

1
https://api.tomtom.com/maps/orbis/traffic/incidentDetails

1
https://api.tomtom.com/maps/orbis/traffic/incidents/details

Changes in the endpoint path

Changes in request query parameters

Changes in request headers

Changes in response fields

Changes in response headers