Migration Guide

Service version: 2

Last edit: 2026.06.25

TomTom Orbis Maps

Where do I find the new endpoint

This TomTom Orbis Maps endpoint is supported: Reverse Geocode.

Important note: The TomTom Maps Reverse Geocode API endpoint CrossStreet Lookup is not supported.

The new Orbis Reverse Geocode API endpoint has the following prefix:

get

URL request example

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

instead of:

get

URL request example

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

Necessary changes in parameters and headers

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

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)	Reverse Geocode API with TomTom Maps	Reverse Geocode API with TomTom Orbis Maps
query	Query is required as a path parameter. Example query for Amsterdam Centraal's lat-lon: '52.379115,4.900285': `/reverseGeocode/52.379115,4.90028.json`	Position (input coordinates) is required as a query parameter (named `position`). New position uses `longitutde,latitude` format. Example query for Amsterdam Centraal's lat-lon: '52.379115,4.900285': `/reverseGeocode?position=4.900285,52.379115`
API Key	Your API key is required as the `key` input parameter value. Example query with a key: `/reverseGeocode/52.379115,4.90028.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/reverseGeocode/`. 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
`heading`	`vehicleHeadingInDegrees`	Renamed. Ignored when `areaTypes` is set.
`radius`	`radiusInMeters`	Renamed.
`entityType`	`areaTypes`	Renamed. Values were changed - e.g., `municipality` instead of `Municipality`, `postalCode` instead of `PostalCodeArea`, `neighborhood` instead of `Neighbourhood`.
`view`	`geopoliticalView`	Renamed.
`returnSpeedLimit`	Not available	Removed.
`returnRoadClass`	Not available	Removed.
`returnRoadUse`	Not available	Removed.
`roadUse`	Not available	Removed.
`callback`	Not available	Removed.
`language`	Not available	Removed from parameters. Use the `Accept-Language` request header instead.
`allowFreeformNewline`	Not available	Removed.
`returnMatchType`	Not available	Removed.
`mapcodes`	Not available	Removed.
`filter`	Not available	Removed.

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

Please check the respective endpoint's documentation page for details.