TomTom Orbis maps versioning

Introduction

With the release of Orbis APIs, we changed our approach to versioning. The version of the API is now provided as a header (TomTom-Api-Version) or query parameter (apiVersion) instead of having it in the path.

Previously

In the past, you would call Search API with the version in the path:

1GET /search/2/search/Paris.json?key={apiKey} HTTP/1.1
2Host: api.tomtom.com
3Content-Type: application/json

The endpoint is structured as follow:

1GET {serviceName}/{versionNumber}/{serviceOperation}/{query}.json?key={apiKey} HTTP/1.1
2Host: api.tomtom.com
3Content-Type: application/json

Now

As an example, the new service Orbis Places API now moves the version out of the Path to the Header TomTom-Api-Version:

1GET https://api.tomtom.com/maps/orbis/places/search/Paris.json?key={apiKey} HTTP/1.1
2Host: api.tomtom.com
3TomTom-Api-Version: 1
4Content-Type: application/json

We acknowledge that certain customers prefer to work with Query Parameters instead of Headers (especially for Web Browser to avoid preflight requests). It is also possible to provide the version number with apiVersion query parameter:

1GET https://api.tomtom.com/maps/orbis/places/search/Paris.json?key={apiKey}&apiVersion=1 HTTP/1.1
2Host: api.tomtom.com
3Content-Type: application/json

The endpoint is structured as follow:

1GET https://api.tomtom.com/maps/orbis/{{{} {serviceName}/{serviceOperation}/{query}.json?key={apiKey} HTTP{}}}/1.1
2Host: api.tomtom.com
3TomTom-Api-Version: {versionNumber}
4Content-Type: application/json

Please note that If both are provided, the query parameter will always take precedence.

To know which endpoints are affected by the new strategy, you can always refer to the documentation.

Services structure

As a general approach on how we apply the versioning change, existing API endpoints remain unchanged ensuring forward compatibility.

As we move forward to a new generation of services powered by Orbis Maps, we adopt a new structure to how API endpoints are organized:

Existing services using the old versioning strategy are still accessible at:

{*}`https://api.tomtom.com/\ {serviceName}/{versionNumber}/`

New services implementing the new versioning strategy and not relying on Orbis are accessible at https://api.tomtom.com/maps/\{serviceName}

Services implementing the new versioning strategy and based on Orbis are accessible at:

{*}`https://api.tomtom.com/maps/orbis/\ {serviceName}