Migration Guide
The Traffic 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 Traffic 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) |
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:
attributesquery 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.Attributesrequest 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-Excluderequest 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:
| 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 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:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y}
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/map/4/tile/flow/{type}/{zoom}/{x}/{y}.pbf
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/map/{versionNumber}/tile/flow/{type}/{zoom}/{x}/{y}.pbf | /maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y} |
| Version mechanism | versionNumber path parameter (value: 4) | apiVersion query parameter or TomTom-Api-Version header (value: 2) |
type | Required path parameter to specify flow type | Removed from path. Vector flow tiles no longer use such path 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. |
| Not available | attributes | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. Takes precedence over Attributes-Attributes-Exclude headers pair. |
margin | Not available | Removed. |
tags | Not available | Replaced by the tags attribute (e.g., tags(road_category,road_subcategory)), available via the attributes query parameter or the Attributes header. |
roadTypes | Not available | Replaced by the roadCategories attribute (e.g., roadCategories(motorway,trunk)), available via the attributes query parameter or the Attributes header. |
trafficLevelStep | Not available | Removed. |
Changes in request headers
| Header name | TomTom Maps | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Not available | Required (value: 2). |
Attributes | Not available | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. |
Attributes-Exclude | Not available | Optional. Specifies which attributes should be omitted in the response. |
Accept | Not available | Optional. Value: application/vnd.mapbox-vector-tile. |
Supported attributes
| Attribute name | Notes |
|---|---|
tags | Allows the choice of tile tags in the requested tile. |
roadCategories | Allows the choice of road category types in the requested tile. |
Changes in vector tile tags
| TomTom Maps tag | Orbis v2 tag | Notes |
|---|---|---|
road_type (default) | Not available | Removed. Use road_category/road_subcategory tags instead. |
road_category (on-demand) | road_category (default) | Contains wider range of road categories. |
road_subcategory (on-demand) | road_subcategory (default) | Contains wider range of road subcategories. |
traffic_level (default) | Not available | Removed. In TomTom Maps, traffic_level carried either absolute or relative values depending on the style. In Orbis v2, corresponding tags relative_speed and absolute_speed are available. |
| Not available | relative_speed (default) | New. Provides the value indicating the speed relative to free-flow traffic. |
| Not available | absolute_speed (on-demand) | New. Provides the absolute speed in km/h as a separate tag. |
traffic_road_coverage (default) | part_of_two_way_road (on-demand) | Changed. TomTom Maps used string values (one_side, full). Orbis v2 variant reflects the information via boolean tag. |
left_hand_traffic (default) | left_hand_traffic (default) | No change. |
road_closure (default) | road_closure (default) | No change. |
| Not available | display_class (default) | New. Ranking of the road based on importance; can be used for content filtering. |
| Not available | openlr (on-demand, explicit) | New. The OpenLR code describing the flow section. Explicit tag. |
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
| TomTom Maps | Orbis v2 |
|---|---|
image/pbf | application/vnd.mapbox-vector-tile |
Changes in response headers
| TomTom Maps header | Orbis v2 header | Notes |
|---|---|---|
Expires | Cache-Control | Expires header is replaced with Cache-Control. |
Flow raster tiles endpoint
Where do I find the new endpoint
The new Orbis v2 Flow raster tiles endpoint has the following path:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y}
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/map/4/tile/flow/{style}/{zoom}/{x}/{y}.png
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/map/{versionNumber}/tile/flow/{style}/{zoom}/{x}/{y}.png | /maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y} |
| Version mechanism | versionNumber path parameter (value: 4) | apiVersion query parameter or TomTom-Api-Version header (value: 2) |
style | Required path parameter for style selection | Removed from path. Raster tiles endpoint uses the style 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. |
| Not available | style | Replaces path parameter. Available styles: light, dark. |
tileSize | tileSize | No change. Values: 256, 512. |
thickness | Not available | Removed. |
Changes in request headers
| Header name | TomTom Maps | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Not available | Required (value: 2). |
Accept | Accept | Only return types for successful requests are allowed (image/png). |
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:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y}
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/map/4/tile/incidents/{zoom}/{x}/{y}.pbf
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/map/{versionNumber}/tile/incidents/{zoom}/{x}/{y}.pbf | /maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y} |
| Version mechanism | versionNumber path parameter (value: 4) | 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. |
| Not available | attributes | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. Takes precedence over Attributes-Attributes-Exclude headers pair. |
tags | Not available | Replaced by the tags attribute (e.g., tags(road_category,road_subcategory)), available via the attributes query parameter or the Attributes header. |
language | Not available | Removed. 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). |
Attributes | Not available | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. |
Attributes-Exclude | Not available | Optional. Specifies which attributes should be omitted in the response. |
Accept-Language | Not available | Optional. Replaces the language query parameter. |
Accept | Not available | Optional. Value: application/vnd.mapbox-vector-tile. |
Supported attributes
| Attribute name | Notes |
|---|---|
tags | Allows the choice of tile tags in the requested tile. |
roadCategories | Allows the choice of road category types in the requested tile. |
iconCategories | Allows the choice of icon categories in the requested tile. |
timeValidity | Allows the choice of incidents presence based on their occurrence in time (present and/or future). |
Changes in protobuf tags
| TomTom Maps tag | Orbis v2 tag | Notes |
|---|---|---|
id (on-demand) | id (mandatory) | It is now a mandatory tag added to each response. |
icon_category_[idx] integer (default) | icon_category_[idx] string (default) | Type changed from integer to string. Values changed from numeric codes (e.g., 0, 1, 6) to descriptive strings (e.g., unknown, accident, jam). |
icon_category integer (default) | Not available | Clusters are not supported, therefore related tag is also not available. |
magnitude integer (default) | magnitude_of_delay string (default) | Renamed. Type changed from integer to string. Values changed from numeric codes (e.g., 0–4) to descriptive strings (e.g., unknown, minor, moderate, major, undefined). |
left_hand_traffic (default) | left_hand_traffic (default) | No change. |
road_category (on-demand) | road_category (default) | Contains wider range of road categories. |
road_subcategory (on-demand) | road_subcategory (default) | Contains wider range of road subcategories. |
delay (default) | delay_in_seconds (default) | Renamed. |
clustered (default) | Not available | Clusters are not supported, therefore related tag is also not available. |
description (default) | Not available | Clusters are not supported, therefore related tag is also not available. |
description_[idx] (default) | description_[idx] (default) | Set from on-demand tag to default. |
| Not available | display_class (default) | New. Ranking of the road based on importance; can be used for filtering. |
| Not available | point_type (on-demand) | Specifies whether it is the start point of incident line (start_point), or standalone POI geometry (standalone_point). |
traffic_road_coverage (default) | part_of_two_way_road (on-demand) | Changed. TomTom Maps used string values (one_side, full). Orbis v2 variant reflects the information via boolean tag. |
| Not available | start_time (on-demand) | Start time of the incident, if available. |
end_date (on-demand) | end_time (on-demand) | Renamed. |
| Not available | time_validity (on-demand) | An enumeration string describing if the incident occurrence is now or the future. |
| Not available | average_speed_kmph (on-demand) | Shows average speed information associated with the incident, if present. |
| Not available | openlr (on-demand, explicit) | New. The OpenLR code describing the incident section. Explicit tag. |
probability_of_occurrence (on-demand) | probability_of_occurrence (on-demand, explicit) | Becomes explicit tag. |
number_of_reports (on-demand) | number_of_reports (on-demand, explicit) | Becomes explicit tag. |
last_report_time (on-demand) | last_report_time (on-demand, explicit) | Becomes explicit tag. |
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
| TomTom Maps | Orbis v2 |
|---|---|
image/pbf | application/vnd.mapbox-vector-tile |
Changes in response headers
| TomTom Maps header | Orbis v2 header | Notes |
|---|---|---|
| Not available | Content-Language | Content-Language header is introduced. |
| Not available | Cache-Control | Cache-Control header is introduced. |
Incident raster tiles endpoint
Where do I find the new endpoint
The new Orbis v2 Incident raster tiles endpoint has the following path:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/map/4/tile/incidents/{style}/{zoom}/{x}/{y}.png
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/map/{versionNumber}/tile/incidents/{style}/{zoom}/{x}/{y}.png | /maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y} |
| Version mechanism | versionNumber path parameter (value: 4) | apiVersion query parameter or TomTom-Api-Version header (value: 2) |
style | Required path parameter for style selection | Removed from path. Raster tiles endpoint uses the style 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. |
| Not available | style | Replaces path parameter. Available styles to be used are light and dark. |
tileSize | tileSize | No change. Values: 256, 512. |
Changes in request headers
| Header name | TomTom Maps | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Not available | Required (value: 2). |
Accept | Accept | Only return types for successful requests are allowed (image/png). |
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:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/incidents/details
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/services/4/incidentDetails/{style}/{boundingBox}/{zoom}/{trafficModelID}/{format}
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/services/{versionNumber}/incidentDetails/{style}/{boundingBox}/{zoom}/{trafficModelID}/{format} | /maps/orbis/traffic/incidents/details |
| Version mechanism | versionNumber path parameter (value: 4) | apiVersion query parameter or TomTom-Api-Version header (value: 2) |
style | style path parameter | There is no need to define style in requests paths. |
boundingBox | boundingBox path parameter to define corner areas of incidents to report in response | Replaced by bbox query parameter. |
zoom | zoom path parameter (values: 0..22) | Removed. There is no need to define zoom in requests paths. |
trafficModelID | trafficModelID path parameter | Removed. There is no need to define traffic model ID in requests paths. |
format | format path parameter (xml, json, jsonp) | Removed. Only json content type is supported. |
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 | bbox | Used instead of boundingBox path parameter. |
| Not available | ids | Comma-separated list of incident IDs. |
language | Not available | Removed. Use the Accept-Language request header instead. |
projection | Not available | Removed. Only EPSG:4326 projection is supported. |
geometries | Not available | Removed. |
expandCluster | Not available | Removed. Clusters are not supported. |
originalPosition | Not available | Removed. |
jsonp | Not available | Removed. jsonp is not supported. |
Changes in request headers
| Header name | TomTom Maps | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Not available | Required (value: 2). |
Attributes | Not available | Required. Specifies which response fields to return. Replaces fields query parameter. |
Attributes-Exclude | Not available | Optional. Specifies which response fields to omit. |
Accept | Not available | Optional. Value: application/json. |
Accept-Language | Not available | Optional. Replaces the language query parameter. |
Changes in response fields
| TomTom Maps field | Orbis v2 field | Notes |
|---|---|---|
<tm> | incidents | Main response property. Array of incidents. |
<poi> | incidents[index] | Single incident element. |
<cpoi> | Not available | Clusters are not supported. |
<id> | incidents.properties.id | Incident ID. |
<p> | Not available | Only GeoJSON geometry present under incidents.geometry object is present instead. |
<op> | Not available | Only GeoJSON geometry present under incidents.geometry object is present instead. |
<ic> | incidents.properties.iconCategory | Icon category. |
<ty> | incidents.properties.magnitudeOfDelay | Magnitude of delay. |
<cbl> | Not available | Only GeoJSON geometry present under incidents.geometry object is present instead. |
<ctr> | Not available | Only GeoJSON geometry present under incidents.geometry object is present instead. |
<cs> | Not available | Clusters are not supported. |
<d> | incidents.properties.events.description | Incident event description (each incident can have multiple events). |
<sd> | incidents.properties.startTime | Incident start time. |
<c> | Not available | Use events descriptions instead. |
<f> | incidents.properties.from | Start location of the incident. |
<t> | incidents.properties.to | End location of the incident. |
<l> | incidents.properties.lengthInMeters | Length of the incident in meters. |
<dl> | incidents.properties.delayInSeconds | Delay caused by the incident in seconds. |
<r> | incidents.properties.roadNumbers | Road numbers affected by the incident. |
<v> | incidents.geometry | List of coordinates creating incident geometry. |
For more information about response fields available in Orbis v2 counterpart, check this documentation.
Changes in response headers
| TomTom Maps header | Orbis v2 header | Notes |
|---|---|---|
Content-Language | Content-Language | Content-Language values are changed (check language codes for Orbis v2 counterpart). |
Cache-Control | Cache-Control | Cache-Control values are changed. |
Changes in response content type
| TomTom Maps | Orbis v2 |
|---|---|
application/json, application/javascript, text/xml | application/json |
Incident details v5 endpoint
Where do I find the new endpoint
The new Orbis v2 Incident details endpoint has the following path:
get
Orbis v2 URL format
https://api.tomtom.com/maps/orbis/traffic/incidents/details
instead of:
get
TomTom Maps URL format
https://api.tomtom.com/traffic/services/5/incidentDetails
Changes in the endpoint base path
| Aspect | TomTom Maps | Orbis v2 |
|---|---|---|
| Base path | /traffic/services/{versionNumber}/incidentDetails | /maps/orbis/traffic/incidents/details |
| Version mechanism | versionNumber path parameter (value: 5) | 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. |
bbox | bbox | No change. |
ids | ids | No change. |
fields | Not available | Removed. Use the Attributes and Attributes-Exclude request headers instead to select response fields. |
language | Not available | Removed. Use the Accept-Language request header instead. |
categoryFilter | iconCategories | Renamed. Values changed from numeric integers (e.g., 0, 1, 6) to descriptive strings (e.g., unknown, accident, jam). |
timeValidityFilter | timeValidity | Renamed. |
Changes in request headers
| Header name | TomTom Maps | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Not available | Required (value: 2). |
Attributes | Not available | Required. Specifies which response fields to return. Replaces fields query parameter. |
Attributes-Exclude | Not available | Optional. Specifies which response fields to omit. |
Accept | Not available | Optional. Value: application/json. |
Accept-Language | Not available | Optional. Replaces the language query parameter. |
Changes in response fields
| TomTom Maps field | Orbis v2 field | Notes |
|---|---|---|
incidents.properties.iconCategory integer | incidents.properties.iconCategory string | Type changed from integer to string. Values changed from numeric codes (e.g., 8) to descriptive strings (e.g., roadClosed). |
incidents.properties.magnitudeOfDelay integer | incidents.properties.magnitudeOfDelay string | Type changed from integer to string. Values changed from numeric codes (e.g., 0–4) to descriptive strings. |
incidents.properties.length | incidents.properties.lengthInMeters | Renamed. |
incidents.properties.delay | incidents.properties.delayInSeconds | Renamed. |
incidents.properties.events.iconCategory int | incidents.properties.events.iconCategory string | Type changed from integer to string. |
incidents.properties.tmc | Not available | Removed. TMC data is no longer part of the response. |
Changes in response headers
| TomTom Maps header | Orbis v2 header | Notes |
|---|---|---|
| Not available | Content-Language | Content-Language header is introduced. |
| Not available | Cache-Control | Cache-Control header is introduced. |
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:
get
Orbis v1
https://api.tomtom.com/maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.pbf
get
Orbis v2
https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y}
Changes in the endpoint path
| Aspect | Orbis v1 | Orbis v2 |
|---|---|---|
| Path | /maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.pbf | /maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y} |
Changes in request query parameters
| Orbis v1 parameter | Orbis v2 parameter | Notes |
|---|---|---|
apiVersion (value: 1) | apiVersion (value: 2) | Version value changed. |
| Not available | attributes | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. Takes precedence over Attributes-Attributes-Exclude headers pair. |
tags | Not available | Replaced by the tags attribute (e.g., tags(road_category,road_subcategory)), available via the attributes query parameter or the Attributes header. |
roadCategoryFilter | Not available | Replaced by the roadCategories attribute (e.g., roadCategories(motorway,trunk)), available via the attributes query parameter or the Attributes header. |
Changes in request headers
| Header name | Orbis v1 | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Required (value: 1) | Required (value: 2). |
Attributes | Not available | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. |
Attributes-Exclude | Not available | Optional. Specifies which attributes should be omitted in the response. |
Accept | Not available | Optional. Value: application/vnd.mapbox-vector-tile. |
Supported attributes
| Attribute name | Notes |
|---|---|
tags | Allows the choice of tile tags in the requested tile. |
roadCategories | Allows the choice of road category types in the requested tile. |
Changes in protobuf tags
| Orbis v1 tag | Orbis v2 tag | Notes |
|---|---|---|
road_category (default) | road_category (default) | No change. |
road_subcategory (default) | road_subcategory (default) | No change. |
relative_speed (default) | relative_speed (default) | No change. |
left_hand_traffic (default) | left_hand_traffic (default) | No change. |
road_closure (default) | road_closure (default) | No change. |
display_class (on-demand) | display_class (default) | Set from on-demand tag to default tag. |
absolute_speed (on-demand) | absolute_speed (on-demand) | No change. |
part_of_two_way_road (on-demand) | part_of_two_way_road (on-demand) | No change. |
openlr (on-demand) | openlr (on-demand, explicit) | No change in functionality. Explicit tag. |
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
| Orbis v1 | Orbis v2 |
|---|---|
image/pbf | application/vnd.mapbox-vector-tile |
Flow raster tiles endpoint
Endpoint URL
The base path changes and the API version changes:
get
Orbis v1
https://api.tomtom.com/maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.png
get
Orbis v2
https://api.tomtom.com/maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y}
Changes in the endpoint path
| Aspect | Orbis v1 | Orbis v2 |
|---|---|---|
| Path | /maps/orbis/traffic/tile/flow/{zoom}/{x}/{y}.png | /maps/orbis/traffic/flow/raster/tile/{zoom}/{x}/{y} |
Changes in request query parameters
| Orbis v1 parameter | Orbis v2 parameter | Notes |
|---|---|---|
apiVersion (value: 1) | apiVersion (value: 2) | Version value changed. |
style | style | No change. Values: light, dark. |
tileSize | tileSize | No change. Values: 256, 512. |
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:
get
Orbis v1
https://api.tomtom.com/maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.pbf
get
Orbis v2
https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y}
Changes in the endpoint path
| Aspect | Orbis v1 | Orbis v2 |
|---|---|---|
| Path | /maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.pbf | /maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y} |
Changes in request query parameters
| Orbis v1 parameter | Orbis v2 parameter | Notes |
|---|---|---|
apiVersion (value: 1) | apiVersion (value: 2) | Version value changed. |
| Not available | attributes | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. Takes precedence over Attributes-Attributes-Exclude headers pair. |
tags | Not available | Replaced by the tags attribute (e.g., tags(road_category,road_subcategory)), available via the attributes query parameter or the Attributes header. |
roadCategoryFilter | Not available | Replaced by the roadCategories attribute (e.g., roadCategories(motorway,trunk)), available via the attributes query parameter or the Attributes header. |
categoryFilter | Not available | Replaced by the iconCategories attribute (e.g., iconCategories(accident,jam)), available via the attributes query parameter or the Attributes header. |
timeValidityFilter | Not available | Replaced by the timeValidity attribute (e.g., timeValidity(present)), available via the attributes query parameter or the Attributes header. |
language | Not available | Removed. 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). |
Attributes | Not available | Optional. Specifies which attributes should be applied to the response. Replaces tags and filter query parameters. |
Attributes-Exclude | Not available | Optional. Specifies which attributes should be omitted in the response. |
Accept-Language | Not available | Optional. Replaces the language query parameter. |
Accept | Not available | Optional. Value: application/vnd.mapbox-vector-tile. |
Supported attributes
| Attribute name | Notes |
|---|---|
tags | Allows the choice of tile tags in the requested tile. |
roadCategories | Allows the choice of road category types in the requested tile. |
iconCategories | Allows the choice of icon categories in the requested tile. |
timeValidity | Allows the choice of incidents presence based on their occurrence in time (present and/or future). |
Changes in protobuf tags
| Orbis v1 tag | Orbis v2 tag | Notes |
|---|---|---|
id string (mandatory) | id string (mandatory) | No change. |
icon_category_[idx] integer (default) | icon_category_[idx] string (default) | Type changed from integer to string. Values changed from numeric codes (e.g., 0, 1, 6) to descriptive strings (e.g., unknown, accident, jam). |
magnitude_of_delay integer (default) | magnitude_of_delay string (default) | Type changed from integer to string. Values changed from numeric codes (e.g., 0–4) to descriptive strings (e.g., unknown, minor, moderate, major, undefined). |
left_hand_traffic (default) | left_hand_traffic (default) | No change. |
road_category (default) | road_category (default) | No change. |
road_subcategory (default) | road_subcategory (default) | No change. |
point_type (default) | point_type (on-demand) | Marked as on-demand tag. |
delay (on-demand) | delay_in_seconds (default) | Renamed and set from on-demand tag to default. |
description_[idx] (on-demand) | description_[idx] (default) | Set from on-demand tag to default. |
display_class (on-demand) | display_class (default) | Set from on-demand tag to default. |
part_of_two_way_road (on-demand) | part_of_two_way_road (on-demand) | No change. |
start_time (on-demand) | start_time (on-demand) | No change. |
end_time (on-demand) | end_time (on-demand) | No change. |
time_validity (on-demand) | time_validity (on-demand) | No change. |
average_speed_kmph (on-demand) | average_speed_kmph (on-demand) | No change. |
openlr (on-demand) | openlr (on-demand, explicit) | Becomes explicit tag. |
probability_of_occurrence (on-demand) | probability_of_occurrence (on-demand, explicit) | Becomes explicit tag. |
number_of_reports (on-demand) | number_of_reports (on-demand, explicit) | Becomes explicit tag. |
last_report_time (on-demand) | last_report_time (on-demand, explicit) | Becomes explicit tag. |
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
| Orbis v1 header | Orbis v2 header | Notes |
|---|---|---|
| Not available | Content-Language | Content-Language header is introduced. |
Changes in response content type
| Orbis v1 | Orbis v2 |
|---|---|
image/pbf | application/vnd.mapbox-vector-tile |
Incident raster tiles endpoint
Endpoint URL
The base path changes and the API version changes:
get
Orbis v1
https://api.tomtom.com/maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.png
get
Orbis v2
https://api.tomtom.com/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}
Changes in the endpoint path
| Aspect | Orbis v1 | Orbis v2 |
|---|---|---|
| Path | /maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.png | /maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y} |
Changes in request query parameters
| Orbis v1 parameter | Orbis v2 parameter | Notes |
|---|---|---|
apiVersion (value: 1) | apiVersion (value: 2) | Version value changed. |
style | style | No change. Values: light, dark. |
tileSize | tileSize | No change. Values: 256, 512. |
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:
get
Orbis v1
https://api.tomtom.com/maps/orbis/traffic/incidentDetails
get
Orbis v2
https://api.tomtom.com/maps/orbis/traffic/incidents/details
Changes in the endpoint path
| Aspect | Orbis v1 | Orbis v2 |
|---|---|---|
| Path | /maps/orbis/traffic/incidentDetails | /maps/orbis/traffic/incidents/details |
Changes in request query parameters
| Orbis v1 parameter | Orbis v2 parameter | Notes |
|---|---|---|
apiVersion (value: 1) | apiVersion (value: 2) | Version value changed. |
bbox | bbox | No change. |
ids | ids | No change. |
fields | Not available | Removed. Use the Attributes and Attributes-Exclude request headers instead. |
language | Not available | Removed. Use the Accept-Language request header instead. |
categoryFilter | iconCategories | Renamed. Values changed from numeric integers (e.g., 0, 1, 6) to descriptive strings (e.g., unknown, accident, jam). |
timeValidityFilter | timeValidity | Renamed. |
Changes in request headers
| Header name | Orbis v1 | Orbis v2 |
|---|---|---|
TomTom-Api-Version | Required (value: 1) | Required (value: 2). |
Attributes | Not available | Required. Specifies which response fields to return. Replaces fields query parameter. |
Attributes-Exclude | Not available | Optional. Specifies which response fields to omit. |
Accept | Not available | Optional. Value: application/json. |
Accept-Language | Not available | Optional. Replaces the language query parameter. |
Changes in response fields
| Orbis v1 field | Orbis v2 field | Notes |
|---|---|---|
incidents.properties.iconCategory integer | incidents.properties.iconCategory string | Type changed from integer to string. Values changed from numeric codes (e.g., 8) to descriptive strings (e.g., roadClosed). |
incidents.properties.magnitudeOfDelay integer | incidents.properties.magnitudeOfDelay string | Type changed from integer to string. Values changed from numeric codes (e.g., 0–4) to descriptive strings. |
incidents.properties.length | incidents.properties.lengthInMeters | Renamed. |
incidents.properties.delay | incidents.properties.delayInSeconds | Renamed. |
incidents.properties.events.iconCategory integer | incidents.properties.events.iconCategory string | Type changed from integer to string. |
incidents.properties.tmc | Not available | Removed. TMC data is no longer part of the response. |
Changes in response headers
| Orbis v1 header | Orbis v2 header | Notes |
|---|---|---|
| Not available | Content-Language | Content-Language header is introduced. |