Migration Guide

Service version: 2

Last edit: 2026.05.25

TomTom Orbis Maps

Where do I find the new endpoints

The new Orbis Geocode API endpoint has the following prefix:

get

URL request example

https://api.tomtom.com/maps/orbis/places/geocode/...

instead of:

get

URL request example

https://api.tomtom.com/search/{versionNumber}/geocode/...

Necessary changes in parameters and headers

This section provides the comparison of the supported parameters between Geocding API with TomTom Orbis Maps and with TomTom Maps. For details on the usage of the parameters please refer to API endpoint documentation pages.

If a parameter that you'd like to use is not supported, you can let us know using the Contact us form.

Important note:

The TomTom-Api-Version header needs to be present.

The TomTom-Api-Key header needs to be present.

The Attributes header needs to be present.

Parameter(s) / Header(s)	Geocode API with TomTom Maps	Geocode API with TomTom Orbis Maps
query	Query is required as a path parameter. Example query for 'Amsterdam': `/geocode/Amsterdam.json?parameterX=Y&...`	Query is required as a query parameter (named `query`). Example query for 'Amsterdam': `/geocode?query=Amsterdam&parameterX=Y`
API Key	Your API key is required as the `key` input parameter value. Example query for 'Amsterdam' with a key: `/geocode/Amsterdam.json?key={Your_API_Key}`	Your API key is required as the `TomTom-Api-Key` header value.
TomTom-Api-Version	The API version is specified in the path, notice `2` in the service path: `/search/2/geocode/`. Available values: `2`	The API version MUST be specified in all requests as a value of the `TomTom-Api-Version` header. Available values: `2`
response format - 'ext'	A valid response format: Values: `json`, `jsonp`, `js`, or `xml`	Support for other formats than `json` was removed. Added support for `Accept` header. Available values: `application/json`
`Attributes` header	There is no dedicated mechanism allowing to define which response fields should be returned.	The API consumer MUST specify which response fields they want in the response. `Attributes` header must be present in the call and it must contain correct value. You can request `results` root JSON object, but it is strongly suggested to limit the response fields only to fields that will be consumed by the consumer. Example values: `results` for full response, or `results.title` for just full formatted addresses.

Other changes

Changes in request query parameters

TomTom Maps parameter	Orbis v2 parameter	Notes
Not available	`types`	Allows filtering of result type(s), e.g., the value `address` limits results to house-number-level addresses.
`limit`	`maxResults`	Renamed.
`view`	`geopoliticalView`	Renamed.
`countrySet`	`countryCodesIso2`	Renamed. Please take a note: structured-geocode allows only one country passed via `countryCodeIso2` parameter. Only 2-letter codes are supported.
`radius`	`radiusInMeters`	Renamed. Has an effect only when `position` is set.
`entityTypeSet`	`areaTypes`	Renamed. Has an effect only when `types` is set and includes `area` type. Values were changed - e.g., `municipality` instead `Municipality`.
`lat`	`position`	Moved to `position` parameter (together with `lon`).
`lon`	`position`	Moved to `position` parameter (together with `lat`).
`topLeft`	`bbox`	Moved to `bbox` parameter (together with `btmRight`).
`btmRight`	`bbox`	Moved to `bbox` parameter (together with `topLeft`).
`language`	Not available	Removed from parameters. Use the `Accept-Language` request header instead.
`ofs`	Not available	Removed.
`typeahead`	Not available	Removed.
`storeResult`	Not available	Removed.
`extendedPostalCodesFor`	Not available	Removed.
`mapcodes`	Not available	Removed.

The detailed information about TomTom Orbis Maps Geocoding API content can be found on the Geocode page.