Reverse Geocode
Important notes:
- This TomTom Orbis API is in public preview.
- This API is powered by TomTom Orbis Maps.
- See the TomTom Orbis Maps documentation for more information.
Purpose
The TomTom Orbis Maps Reverse Geocoding API Reverse Geocode endpoint gives users a tool to translate a coordinate (for example: 37.786505, -122.3862
) 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 entityType parameter in the request parameters section) to get a geometry.
- The geometry data can be fetched using the Additional Data service.
Run this endpoint
You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.
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: Either the apiVersion
parameter or the TomTom-Api-Version
header needs to be present.
URL request format
https://{baseURL}/maps/orbis/places/reverseGeocode/{position}.{ext}?key={Your_API_Key}&apiVersion={versionNumber}&returnSpeedLimit={returnSpeedLimit}&heading={heading}&radius={radius}&returnRoadClass={returnRoadClass}&entityType={entityType}&callback={callback}&language={language}&allowFreeformNewline={allowFreeformNewline}&returnMatchType={returnMatchType}&view={view}&mapcodes={mapcodes}&filter={filter}
URL request example
https://api.tomtom.com/maps/orbis/places/reverseGeocode/52.157831,5.223776.json?key={Your_API_Key}&radius=100&apiVersion=1
curl command request example
curl 'https://api.tomtom.com/maps/orbis/places/reverseGeocode/52.157831,5.223776.xml?key={Your_API_Key}&radius=100&apiVersion=1'
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 |
---|---|
string | Base URL for calling the API. Values:
|
string | The service version. |
comma-separated string | This is specified as a comma-separated string composed by lat,lon. Value: Example: |
string | A valid response format: Values: |
string | An API Key valid for the requested service. Value: Your valid TomTom |
Optional parameters | Description |
---|---|
| Enables the return of the posted speed limit (where available). |
| The directional heading of the vehicle in degrees, for travel along a segment of roadway. |
| The maximum distance in meters from the specified position for the |
| Enables the return of the
|
| This parameter specifies the level of filtering performed on geographies. Providing this parameter narrows the search for specified geography entity types. The resulting response will contain the matched entity type. The following parameters are ignored when
Values: One or more of:
|
| Specifies the callback method. |
| The language in which the reverse geocode result should be returned. It should be one of the TomTom IETF Supported Languages tags, case insensitive. When data in a specified language is not available for a specific field, the default language is used. |
| The format of newlines in the formatted address. If |
| This includes information on the type of match the geocoder achieved in the response. |
view string | Geopolitical View. The context used to resolve the handling of disputed
territories. Views include
|
| Enables the return of mapcodes. Can also filter the response to only show selected mapcode types. See mapcode in the response. A mapcode represents a specific location, to within a few meters. Every location on Earth can be represented by a mapcode. Mapcodes are designed to be short, easy to recognize, remember and communicate. Visit the Mapcode project website for more information. |
| Excludes a certain group of inspected address-carrying elements in order to find the closest match to a requested point. Right now service supports only single value, but in future it may change. |
Request headers
The following table describes HTTP request headers.
Optional headers | Description |
---|---|
TomTom-Api-Version | Service version. |
Enables response compression. Value: | |
Tracking-ID | Specifies an identifier for the request.
Value: An |
Response data
Response body
For illustrative purposes the examples below 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:
1{2 "summary": {3 "queryTime": 102,4 "numResults": 15 },6 "addresses": []7}
Example response for the result of the Point Address
type is in the following format:
1{2 "summary": {3 "queryTime": 8,4 "numResults": 15 },6 "addresses": [7 {8 "address": {9 "buildingNumber": "4320",10 "streetNumber": "4320",11 "routeNumbers": [],12 "street": "Payne Avenue",13 "streetName": "Payne Avenue",14 "streetNameAndNumber": "4320 Payne Avenue",15 "countryCode": "US",16 "countrySubdivision": "OH",17 "countrySecondarySubdivision": "Cuyahoga",18 "municipality": "Cleveland",19 "postalCode": "44103",20 "neighbourhood": "Goodrich Park",21 "country": "United States",22 "countryCodeISO3": "USA",23 "freeformAddress": "4320 Payne Avenue, Cleveland, OH 44103",24 "boundingBox": {25 "northEast": "41.511569,-81.655694",26 "southWest": "41.511238,-81.656870",27 "entity": "position"28 },29 "extendedPostalCode": "44103-2329",30 "countrySubdivisionName": "Ohio",31 "countrySubdivisionCode": "OH",32 "localName": "Cleveland"33 },34 "position": "41.511272,-81.656738",35 "matchType": "AddressPoint",36 "mapcodes": [37 {38 "type": "Local",39 "fullMapcode": "US-OH RL.BPD",40 "territory": "US-OH",41 "code": "RL.BPD"42 },43 {44 "type": "International",45 "fullMapcode": "T8GNX.DMVD"46 },47 {48 "type": "Alternative",49 "fullMapcode": "US-OH 63Y.LMT",50 "territory": "US-OH",51 "code": "63Y.LMT"52 },53 {54 "type": "Alternative",55 "fullMapcode": "US-OH FDPJ.HPV",56 "territory": "US-OH",57 "code": "FDPJ.HPV"58 },59 {60 "type": "Alternative",61 "fullMapcode": "US-OH VPLJ.0MC9",62 "territory": "US-OH",63 "code": "VPLJ.0MC9"64 },65 {66 "type": "Alternative",67 "fullMapcode": "USA VPLJ.0MC9",68 "territory": "USA",69 "code": "VPLJ.0MC9"70 }71 ],72 "id": "ZuV4ux-XfHAqL3Ep73d9cg"73 }74 ]75}
Example response for the Geography result with entityType=PostalCodeArea
filtering:
1{2 "summary": {3 "queryTime": 10,4 "numResults": 15 },6 "addresses": [7 {8 "address": {9 "routeNumbers": [],10 "countryCode": "US",11 "countrySubdivision": "CA",12 "countrySecondarySubdivision": "Santa Cruz",13 "municipality": "Santa Cruz",14 "postalName": "Santa Cruz",15 "postalCode": "95065",16 "country": "United States",17 "countryCodeISO3": "USA",18 "freeformAddress": "Santa Cruz, CA 95065",19 "boundingBox": {20 "northEast": "37.085762,-121.949375",21 "southWest": "36.983408,-122.013236",22 "entity": "position"23 },24 "countrySubdivisionName": "California"25 },26 "position": "36.988171,-121.974876",27 "dataSources": {28 "geometry": {29 "id": "00005543-3300-3c00-0000-00004dc8b8e5"30 }31 },32 "entityType": "PostalCodeArea",33 "mapcodes": [34 {35 "type": "Local",36 "fullMapcode": "US-CA FS.WRG0",37 "territory": "US-CA",38 "code": "FS.WRG0"39 },40 {41 "type": "International",42 "fullMapcode": "S4ZW4.89XV"43 },44 {45 "type": "Alternative",46 "fullMapcode": "US-CA 4349.S7L",47 "territory": "US-CA",48 "code": "4349.S7L"49 },50 {51 "type": "Alternative",52 "fullMapcode": "US-CA JJCH.H9CF",53 "territory": "US-CA",54 "code": "JJCH.H9CF"55 },56 {57 "type": "Alternative",58 "fullMapcode": "USA JJCH.H9CF",59 "territory": "USA",60 "code": "JJCH.H9CF"61 }62 ],63 "id": "00005543-3300-3c00-0000-00004dc8b8e5"64 }65 ]66}
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 |
object | Summary information about the search that was performed. summary object |
array | The result list containing a single record. addresses array |
summary object | |
Field | Description |
integer | The time spent on resolving the query (in milliseconds). |
integer | The number of results in the response. The current version of the API returns a maximum of 1 result. |
addresses array | |
Field | Description |
object | The structured address for the result. address object |
double (LatLon) | Position of the result in the form of "latitude,longitude" coordinates. Position of the entry point. Position on the street where you can enter the location. Example: |
array | Road classes at the address. roadclass object |
string | Information on the type of match. One of:
|
object | Optional section. Reference ids for use with the Additional Data service. dataSources object geometry object |
array | Optional section. It can be returned only if the 'mapcodes' input parameter is used. List of mapcode object |
string | A stable, unique id for a given entity. |
address object | |
Field | Description |
string | The building number on the street.
|
string | The building number on the street. |
array | The codes used to unambiguously identify the street. |
string | The street name.
|
string | The street name. |
string | The street name and number. |
string | The speed limit for the street in the form (D)(D)D.DDUUU, For example:
|
string | Country
|
string | State or Province |
string | County |
string | Named Area |
string | City / Town |
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. Only present when the parameter |
string | Postal Code / Zip Code |
string | Sub City |
string | Sub Sub City |
string | Neighbourhood |
string | Country name |
string | |
string | An address line formatted according to the formatting rules of a Result's country of origin, or in the case of a country, its full country name. |
object | The bounding box of the location. boundingBox object |
string | The full name of a first level of country administrative hierarchy. |
string |
|
string | An address component which represents the name of a geographic area or locality that groups a number of addressable objects for addressing purposes, without being an administrative unit. |
string | Extended postal code (availability is dependent on the region). |
boundingBox object | |
Field | Description |
comma-separated floats | North-east (top-left) |
comma-separated floats | South-west (bottom-right) |
string | Entity type source of the bounding box.
|
roadClass object | |
Field | Description |
string | Possible values:
|
array | Possible values:
|
dataSources object | |
Field | Description |
object | Information about the geometric shape of the result. Only present if
|
geometry object | |
Field | Description |
string | Pass this as |
mapcode object | |
Field | Description |
string | Type of mapcode. Possible values:
|
string | The full form of a mapcode ( |
string | The
an address has little meaning unless the user also knows what state it's
in (just as, elsewhere, an address has little meaning if the user
doesn’t know what country it’s in). More information about
|
string | The mapcode without the |
Response codes
The following data table contains response codes signifying successful and failed requests to an API server.
Code | Meaning & possible causes |
---|---|
| OK : The search successfully returned zero or more results. |
| Bad request : One or more parameters were incorrectly specified. |
| Forbidden : Possible causes include:
|
| Method Not Allowed : The HTTP method ( |
| Not Found : The HTTP request method ( |
| Too Many requests : The API Key is over QPS (Queries per second). |
| Server Error : The service was unable to process your request. Contact support to resolve the issue. |
Response headers
The following data table contains response headers sent back from an API server.
Header | Description |
---|---|
Ensures that clients implementing the CORS security model are able to access the response from this service. Value: An asterisk | |
Indicates the format of the response, as chosen by the client. Format: Values: | |
The Reverse Geocode service applies gzip compression to the responses if requested by the client with the Accept-Encoding header. Value: | |
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 |
Error response
The content type of an error response depends on the requested output format (.json
or .xml
).
1{2 "error": "Invalid request: invalid position: latitude/longitude out of range.",3 "httpStatusCode": 400,4 "detailedError": {5 "code": "BadRequest",6 "message": "Invalid request: invalid position: latitude/longitude out of range.",7 "target": "position"8 }9}
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>2<response>3 <error>Invalid request: invalid position: latitude/longitude out of range.</error>4 <httpStatusCode>400</httpStatusCode>5 <detailedError>6 <code>BadRequest</code>7 <message>Invalid request: invalid position: latitude/longitude out of range.</message>8 <target>position</target>9 </detailedError>10</response>
Error response fields
Primary fields | Description |
---|---|
string | A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users. |
integer | HTTP error code. |
object | Detailed information about the error. detailedError object |
detailedError object | |
Field | Description |
string | One of the defined error codes. |
string | A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users. |
string | Optional. Target of the particular error. Value: The name of the request parameter. |
Error code hierarchy
A list of predefined, hierarchical, human-readable error codes. The httpStatusCode
relates to HTTP error codes. An error code in detailedError
can redefine httpStatusCode
to one of the codes described in this section. In the future, the list may be extended with additional codes.
Error code | Description |
---|---|
| The code for requests which ended with HTTP
|
| The code for requests which ended with HTTP |
| The code for requests which ended with HTTP
|
| The code for requests which ended with HTTP
|