Reverse Geocode

Service version: 2 Last edit: 2026.06.25 TomTom Orbis Maps

Purpose

The TomTom Orbis Maps Reverse Geocoding API Reverse Geocode endpoint gives users a tool to translate a coordinate (for example: -122.3862, 37.786505) into a human-understandable street address, street element, or geography. Most often, this is needed in tracking applications where you receive a GPS feed from the device or asset and you want to know the address.

The type of response depends on the available data:

address: Returns the most detailed information.
street element: Less detailed returned when there is no address data.
geography: Returns the smallest available geographic data.
- This is returned when there is no address or street element data.
- You can specify the level of geography (see the areaTypes parameter in the request parameters section) to get a geometry.

Request data

HTTPS Method: `GET`

For ease of viewing and identification:

Constants and parameters enclosed in curly brackets { } must be replaced with their values.
Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Important note: TomTom-Api-Version header is required for this version.

get

URL request format

1
https://{baseURL}/maps/orbis/places/reverseGeocode?position={position}&radiusInMeters={radiusInMeters}&areaTypes={areaTypes}&vehicleHeadingInDegrees={vehicleHeadingInDegrees}&geopoliticalView={geopoliticalView}

get

URL request example

1
https://api.tomtom.com/maps/orbis/places/reverseGeocode?position=5.22377,52.1578316&radiusInMeters=100&vehicleHeadingInDegrees=0

get

curl command request example

1
curl 'https://api.tomtom.com/maps/orbis/places/reverseGeocode?position=5.22377,52.157831&radiusInMeters=100&vehicleHeadingInDegrees=0' -H "TomTom-Api-Version:2" -H "TomTom-Api-Key:{Your_API_Key}" -H "Attributes:results"

Request parameters

The following table describes the parameters that can be used in a request.

Required parameters must be used or the call will fail.
Optional parameters may be used.
If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
The order of request parameters is not important.

Required parameters Description

Required parameters	Description
`baseURL` string	Base URL for calling the API. Value: `api.tomtom.com`
`position` string	This is specified as a comma-separated string composed by longitude and latitude. Format: `longitude,latitude` Value: A coordinate point. Example: `-122.453,37.553`.

baseURL

string

Base URL for calling the API.

Value: api.tomtom.com

position
string

This is specified as a comma-separated string composed by longitude and latitude.
Format: longitude,latitude
Value: A coordinate point.
Example: -122.453,37.553.

Optional parameters	Description
`radiusInMeters` integer	The maximum distance in meters from the specified `position` for the `reverseGeocode` to consider. Default value: `10000` meters (10 km). Maximum value: `5000000` meters (5000 km).
`areaTypes` string	A comma-separated list of ‘area’ sub-types used to filter the results. If no area types are specified then all possible values may occur. The following parameter is ignored when `areaTypes` is set: `vehicleHeadingInDegrees` Available values: `country` `countrySubdivision` `countrySecondarySubdivision` `countryTertiarySubdivision` `municipality` `municipalitySubdivision` `municipalitySecondarySubdivision` `postalCode` `neighborhood` Value: A comma-separated list of area types. Example: countrySubdivision,countrySecondarySubdivision
`vehicleHeadingInDegrees` float	The directional heading of the vehicle (degrees, 0..359). `0` represents North, `90` represents East, `180` represents South, and `270` represents West. The precision can include up to one decimal place. Values: Values range from `-360` to `360`.
`geopoliticalView` string	Geopolitical view. The context used to resolve the handling of addressing schemes in disputed territories. Available values: `Unified`, `AR`, `CN`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `TW`, `RS` Default values: Argentina, default view: `AR`, other available views: `Unified`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `TW`, `RS` India, default view: `IN`, other available views: - Morocco, default view: `MA`, other available views: `Unified`, `AR`, `IL`, `IN`, `PK`, `RU`, `TR`, `CN`, `TW`, `RS` Pakistan, default view: `PK`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `RU`, `TR`, `CN`, `TW`, `RS` Russia, default view: `RU`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `TR`, `CN`, `TW`, `RS` Turkey, default view: `TR`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `CN`, `TW`, `RS` China, default view: `CN`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `TW`, `RS` Taiwan, default view: `TW`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `RS` Serbia, default view: `RS`, other available views: `Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `TW` Others, default view: `Unified`, other available views: `AR`, `CN`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `TW`, `RS` Value: A geopolitical view code.

Request headers

The following tables describes HTTP request headers.

Required headers Description

TomTom-Api-Key

Required headers	Description
TomTom-Api-Key	An API Key valid for the requested service. See: How do I get a TomTom API Key? Value: Your valid `API Key`.
TomTom-Api-Version	Version of the API. The API version MUST be specified in all requests. Value: A service version value. The current value is `2`.
Attributes	A list of response fields to return, specified in dot-notation. Nested fields are expressed using `.` separators and optional grouped subfields using parentheses. `Attributes` header must contain at least one valid top-level field. Using only a top-level `` wildcard is not allowed. When a field name refers to a non-primitive object, all its non-EXPLICIT* subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in `Attributes` (they are never included solely by selecting their parent or by using ``). The `` wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object. Syntax: `<field-list> ::= <field> (',' <field>)` `<field> ::= <name> ('.' <field> \| <field-set>)?` `<field-set> ::= '(' <field-set-list> ')'` `<field-set-list> ::= '' (',' <field>)* \| <field> (',' <field>)` `<name> ::=` one or more alphabetic characters Note:* All listed field names must exist in the response domain model; unknown fields result in an error. APIs may restrict which fields are allowed in `Attributes`. Disallowed-but-existing fields result in an error. New response fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via `Attributes`, preserving backward compatibility and performance. Examples: `Attributes: results.title, results.position` `Attributes: results(title, position)` `Attributes: results(*, address(neighborhood))`

An API Key valid for the requested service.
See: How do I get a TomTom API Key?
Value: Your valid API Key.

TomTom-Api-Version

Version of the API. The API version MUST be specified in all requests.
Value: A service version value. The current value is 2.

Attributes

A list of response fields to return, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Attributes header must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in Attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.
Syntax:

<field-list> ::= <field> (',' <field>)*
<field> ::= <name> ('.' <field> | <field-set>)?
<field-set> ::= '(' <field-set-list> ')'
<field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
<name> ::= one or more alphabetic characters

Note:

All listed field names must exist in the response domain model; unknown fields result in an error.
APIs may restrict which fields are allowed in Attributes. Disallowed-but-existing fields result in an error.
New response fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via Attributes, preserving backward compatibility and performance.

Examples:

Attributes: results.title, results.position
Attributes: results(title, position)
Attributes: results(*, address(neighborhood))

Optional headers	Description
Tracking-Id	A unique identifier for tracking the request across services. The client should provide a globally unique value, preferably a UUID (v4 or v7). While any string format is accepted, the tracking ID must be unique to enable effective request tracing and correlation in logs.
Accept-Language	Sequence of preferred response IETF BCP 47 language tags compliant with RFC 7231 (section 5.3.5). The API makes best effort to return results in one of the preferred languages, falling back to the prevalent local language in the result’s geographical region if none of the preferred languages is available.
Accept	The standard HTTP Accept header indicating the media type(s) the client is able to understand. Available values: `application/json`
Accept-Encoding	Enables response compression. Value: `gzip`
Attributes-Exclude	A list of response fields to omit from the response, specified in dot-notation. Nested fields are expressed using `.` separators and optional grouped subfields using parentheses. Any field listed in `Attributes-Exclude`, including its entire sub-tree, is omitted from the response, regardless of whether it was included implicitly or explicitly via the `Attributes` header. Exclusion always overrules inclusion. The format of the field list is the same “listed dot-notation” used for the `Attributes` header: Syntax: `<field-list> ::= <field> (',' <field>)` `<field> ::= <name> ('.' <field> \| <field-set>)?` `<field-set> ::= '(' <field-set-list> ')'` `<field-set-list> ::= '' (',' <field>)* \| <field> (',' <field>)` `<name> ::=` one or more alphabetic characters Notes:* The exclusion list is applied to the result of the inclusion list. If a parent field is excluded, all of its children are excluded, even if some of those children were explicitly listed in `Attributes`. Listed field names in `Attributes-Exclude` must exist in the response domain model; unknown fields result in an error. APIs may restrict which fields are allowed in `Attributes-Exclude`. Disallowed-but-existing fields result in an error. Fields may occur multiple times in `Attributes-Exclude` (not recommended, but not an error). Some overlap between `Attributes` and `Attributes-Exclude` is allowed. In case of overlap, the exclusion takes precedence. Whether a field is EXPLICIT or not does not change the semantics of exclusion: if it is present in `Attributes-Exclude`, it is omitted whenever it would otherwise have been returned. Examples: `Attributes: results(title, position)` `Attributes-Exclude: results.position` Results in only the `title` field being returned for each result, while `position` is excluded despite being included in `Attributes`. `Attributes: results(*, address(neighborhood, postalCode))` `Attributes-Exclude: results.address.postalCode` Results in all address fields being returned except for the `postalCode` field.

Response data

Response body

For illustrative purposes the following examples are neatly indented. Please note that actual responses will vary based on the result type and the data available. See the following response fields section for more information. When requesting JSON output, the response has the following structure:

Response structure - JSON

1
{
2
  "results": []
3
}

Example response for the result of the Point Address type is in the following format:

Point Address type example response - JSON

1
{
2
  "results": [
3
    {
4
      "id": "bWDVPAAQT6667EoGx_kMcQ",
5
      "type": "address",
6
      "title": "4320 Payne Avenue, Cleveland, OH 44103",
7
      "position": {
8
        "type": "Point",
9
        "coordinates": [
10
          -81.656548,
11
          41.510887
12
        ]
13
      },
14
      "address": {
15
        "country": "United States",
16
        "countryCodeIso2": "US",
17
        "countrySubdivision": "OH",
18
        "countrySubdivisionCodeIso": "US-OH",
19
        "countrySecondarySubdivision": "Cuyahoga",
20
        "municipality": "Cleveland",
21
        "neighborhood": "Goodrich Park",
22
        "postalCode": "44103",
23
        "extendedPostalCode": "44103-2329",
24
        "street": "Payne Avenue",
25
        "houseNumber": "4320"
26
      },
27
      "accessPoints": [
28
        {
29
          "position": {
30
            "type": "Point",
31
            "coordinates": [
32
              -81.6567403,
33
              41.5112742
34
            ]
35
          }
36
        }
37
      ]
38
    }
39
  ]
40
}

Example response for the Geography result with areaTypes=postalCode filtering:

Geography example response - JSON

1
{
2
  "results": [
3
    {
4
      "id": "xs8Xg3uNDJSj4uqwbT2fZA",
5
      "type": "area",
6
      "areaType": "postalCode",
7
      "title": "Santa Cruz, CA 95065",
8
      "position": {
9
        "type": "Point",
10
        "coordinates": [
11
          -121.974876,
12
          36.988171
13
        ]
14
      },
15
      "address": {
16
        "country": "United States",
17
        "countryCodeIso2": "US",
18
        "countrySubdivision": "CA",
19
        "countrySubdivisionCodeIso": "US-CA",
20
        "countrySecondarySubdivision": "Santa Cruz",
21
        "municipality": "Santa Cruz",
22
        "postalCode": "95065",
23
        "postalName": "Santa Cruz"
24
      }
25
    }
26
  ]
27
}

Response fields

The following tables describe all of the fields that can appear in a response. Fields are listed by the response section they belong to and in the order that they appear in the response.

Primary fields
Field	Description
`results` array	The result list. `results` array
results array
Field	Description
`id` string	Unique identifier of the result. It can change between new data releases.
`type` string	Type of result. Value: One of: `address` `street` `area`
`areaType` string	The type of area returned. One of: `country` `countrySubdivision` `countrySecondarySubdivision` `countryTertiarySubdivision` `municipality` `municipalitySubdivision` `municipalitySecondarySubdivision` `postalCode` `neighborhood`
`title` string	Localized display title for the result.
`position` object	The position of the result in GeoJSON format. `position` object
`address` object	The structured address for the result. `address` object
`accessPoints` array	List of access points of the location. Access points are always on the road network. `accessPoints` array
address object
Field	Description
`country` string	Country name.
`countryCodeIso2` string	ISO 3166-1 alpha-2 country code. Example: `US`
`countrySubdivision` string	State or province.
`countrySubdivisionCodeIso` string	ISO 3166-2 country subdivision code. Example: `US-CA`
`countrySecondarySubdivision` string	County.
`countryTertiarySubdivision` string	Named area.
`municipality` string	City or town.
`municipalitySubdivision` string	Subdivision of a city.
`municipalitySecondarySubdivision` string	Smaller subdivision of a city.
`neighborhood` string	Neighborhood.
`postalCode` string	Postal code (ZIP code).
`postalName` string	An address component which represents the name for a postal code that is related to a single administrative area, city, town, or other populated place.
`extendedPostalCode` string	Extended postal code (availability dependent on region).
`street` string	Name of the street.
`houseNumber` string	The building number on the street.
`routeNumbers` array	The codes used to unambiguously identify the street. Items: string Example: `["A1", "E15"]`
position object (GeoJSON Point)
Field	Description
`type` string	GeoJSON type. Value: `Point`
`coordinates` array	A GeoJSON position: [longitude, latitude] optionally followed by elevation in meters. Example: `[-73.935242, 40.73061]` or `[-73.935242, 40.73061, 10.5]`
accessPoints array
Field	Description
`position` object	Position of the access point in GeoJSON format `position` object.

Default view mapping

Default view is recognized based on the country the request came from.

Country	Default view	Other available views
Argentina	`AR`	`Unified`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `TW`, `RS`
India	`IN`	`-`
Morocco	`MA`	`Unified`, `AR`, `IL`, `IN`, `PK`, `RU`, `TR`, `CN`, `TW`, `RS`
Pakistan	`PK`	`Unified`, `AR`, `IL`, `IN`, `MA`, `RU`, `TR`, `CN`, `TW`, `RS`
Russia	`RU`	`Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `TR`, `CN`, `TW`, `RS`
Turkey	`TR`	`Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `CN`, `TW`, `RS`
China	`CN`	`Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `TW`, `RS`
Taiwan	`TW`	`Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `RS`
Serbia	`RS`	`Unified`, `AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `TW`
Others	`Unified`	`AR`, `IL`, `IN`, `MA`, `PK`, `RU`, `TR`, `CN`, `TW`, `RS`

Response codes

The following data table contains HTTP response codes signifying successful and failed requests to an API server.

Successful and failed response codes
Code	Meaning & possible causes
`200`	OK: The search successfully returned zero or more results.
`400`	Bad Request: Client error.
`403`	Forbidden: The supplied API Key is not valid for this request.
`429`	Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
`500`	Internal Server Error: There is a problem with the TomTom Reverse Geocoding API service.
`503`	Service Unavailable: TomTom Reverse Geocoding API service is unable to receive any request.

Response headers

The following table contains response headers sent back from an API server.

Header	Description
Access-Control-Allow-Origin	Ensures that clients implementing the CORS security model are able to access the response from this service. Value: An asterisk `*` that signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its response, indicating which origin sites are allowed.
Content-Type	Indicates the format of the response, as chosen by the client. Format: `<application/json>; charset=utf-8` Values: `<type/subtype>` currently supports `application/json` Example: `application/json; charset=utf-8`
Content-Encoding	If requested by the client, the Search service applies gzip compression to the responses with the Accept-Encoding header. Value: `gzip`
Content-Language	The HTTP Content-Language representation header is used to describe the language(s) intended for the audience, so users can differentiate it according to their own preferred language. For example, Content-Language: de-DE indicates that the document is intended for German language speakers. The document may be written in English, not German, as part of a language course for German speakers. To indicate the language the document is written in, use the lang attribute instead. If no Content-Language is specified, the default is that the content is intended for all language audiences. Multiple language tags are also possible, as well as applying the Content-Language header to various media types and not only to textual documents.
Tracking-ID	An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: An `identifier` for the request.

Error response

Error response content type - JSON

1
{
2
    "detailedError": {
3
        "code": "BAD_REQUEST",
4
        "message": "Invalid request: invalid position: latitude/longitude out of range.",
5
        "target": "position"
6
    }
7
}

Error response fields

Primary fields
Field	Description
`detailedError` object	Detailed error information. `detailedError` object
detailedError object
Field	Description
`code` string	A unique identifier for this particular occurrence of the problem that SHOULD be human-readable.
`message` string	A description of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
`target` string	Optional. The target of the error (e.g., the name of the property in error).