How API Versioning evolves

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:

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

The endpoint is structured as follow:

GET {serviceName}/{versionNumber}/{serviceOperation}/{query}.json?key={apiKey} HTTP/1.1
Host: api.tomtom.com
Content-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:

GET https://api.tomtom.com/maps/orbis/places/search/Paris.json?key={apiKey} HTTP/1.1
Host: api.tomtom.com
TomTom-Api-Version: 1
Content-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:

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

The endpoint is structured as follow

GET https://api.tomtom.com/maps/orbis/{{{} {serviceName}/{serviceOperation}/{query}.json?key={apiKey} HTTP{}}}/1.1
Host: api.tomtom.com
TomTom-Api-Version: {versionNumber}
Content-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.

The 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}