Sorry, you need to enable JavaScript to visit this website.

Reverse Geocode


The TomTom Reverse Geocoding API gives users a tool to translate a coordinate (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 wish to know what the address is.

Request - Regular Reverse Geocoding

Regular request returns information for a given position. The type of response depends on available data:

  • address — the most detailed information
  • street element — less detailed; returned when there is no address data
  • geography — smallest available geographic data; returned when there is no addess nor street element data; the response with geography differs from the regular response, see: Response - geographies

Format

GET https://<baseURL>/search/<versionNumber>/reverseGeocode/<position>.<ext>?key=<apiKey>[&spatialKeys=<spatialKeys>][&returnSpeedLimit=<returnSpeedLimit>][&heading=<heading>][&radius=<radius>][&streetNumber=<streetNumber>][&returnRoadUse=<returnRoadUse>][&roadUse=<roadUse>][&entityType=<entityType>][&callback=<callback>][&language=<language>][&allowFreeformNewline=<allowFreeformNewline>][&returnMatchType=<returnMatchType>][&view=<view>][&dateTime=<dateTime>]
    

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], 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.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 2. Yes 2
position This is specified as a comma-separated string composed by lat., lon. (e.g.: 37.337,-121.89). Yes Position
ext Valid response formats are JSON, JSONP, JS or XML. Yes String
key Your TomTom API key. Yes String
[spatialKeys]
DEPRECATED1
If the "spatialKeys" flag is set, the response will also contain a proprietary geo-spatial key information for a specified location. No Boolean false
[returnSpeedLimit] To enable return of the posted speedlimit (where available). No Boolean false
[heading] The directional heading of the vehicle in degrees, for travel along a segment of roadway. 0 is North, 90 is East and so on, values range from -360 to 360. The precision can include upto one decimal place. No Float
[radius] The maximum distance in meters from the specified position for the reverse geocode to consider. No Integer 10,000 meters (10 km)
[number] If a number is sent in along with the request, the response may include the side of the street (Left/Right) and also an offset position for that number. No String
[returnRoadUse] To enable returning of the road use array for reverse geocodes at street level. No Boolean false
[roadUse] To restrict reverse geocodes to a certain type of road use. No JSON Array2
One or more of:

  • LimitedAccess
  • Arterial
  • Terminal
  • Ramp
  • Rotary
  • LocalStreet
[callback] Specifies the jsonp callback method. No String cb
[language] Language in which search results should be returned. Should be one of supported IETF language tags, case insensitive. When data in specified language is not available for a specific field, default language is used.
DEPRECATION NOTE: support for no-NO will be removed in favour of nb-NO.
No String NGT
[allowFreeformNewline] Format of newlines in the formatted address. If true, the address will contain newlines. Otherwise, newlines will be converted to spaces. No Boolean false
[returnMatchType] Include information on the type of match the geocoder achieved in the response. No Boolean false
[view] Geopolitical View. The context used to resolve handling disputed territories. Views include Unified, along with AR, IL, IN, MA and PK which are tailored for Argentina, Israel, India, Morocco and Pakistan respectively. No String
One of:

  • Unified
  • AR
  • IL
  • IN
  • MA
  • PK
See  default view mapping.
[dateTime] The date and time to return time zone information for. It allows the service to decide whether Daylight Saving Time time zone should be used or not. It must conform to RFC-33393 (e.g.: 2017-12-19T16:39:57, 2017-12-19T16:39:57-08:00, 2018-10-28T00:00:00Z). No Date

Response - Regular Reverse Geocoding

Format

For illustrative purposes the example below is neatly indented and includes all possible response fields. Actual responses are more compact and the fields present will vary based on the result type and the data available. See the response field documentation below for more information.

When requesting JSON output the response has the following structure:

{
    "summary": {
        "queryTime": 17,
        "numResults": 1
    },
    "addresses": [],
    "spatialKeys": []
}

Each element of the addresses array is in the format:

{
    "address": {
        "buildingNumber": "2515",
        "streetNumber": "2515",
        "routeNumbers": [],
        "street": "Soquel Dr",
        "streetName": "Soquel Dr",
        "streetNameAndNumber": "2515 Soquel Dr",
        "speedLimit": "35.00MPH",
        "countryCode": "US",
        "countrySubdivision": "CA",
        "countrySecondarySubdivision": "Santa Cruz",
        "countryTertiarySubdivision": "Santa Cruz",
        "municipality": "Live Oak",
        "postalCode": "95065",
        "municipalitySubdivision": "Santa Cruz, Live Oak",
        "sideOfStreet": "L",
        "offsetPosition": "",
        "country": "United States Of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "2515 Soquel Dr, Live Oak, CA 95065",
        "boundingBox": {
          "northEast": "46.940190,-98.777560",
          "southWest": "46.931190,-98.790740",
          "entity": "position"
        },
        "extendedPostalCode": "950651999",
        "countrySubdivisionName": "California"
    },
    "position": "36.988171,-121.974879",
    "roadUse": [
        "Arterial"
    ],
    "matchType": "AddressPoint"
}

Each element of the spatialKeys array is in the format:

{
    "priority": "0",
    "val": "1563238492"
}

Response fields

The tables below 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.

Field Description Type / Values
Response
summary Summary information about the search that was performed. Summary
addresses Result list, sorted in descending order by score. Result[]
spatialKeys Proprietary geo-spatial key information for a specified location. SpatialKeys
Summary
queryTime Time spent on resolving the query. Integer
numResults Number of Results in the response. Integer
Result
address Structured address for the Result. Address
position Position of the Result. LatLon
roadUse List of road usage types at the address. Zero or more of:

  • LimitedAccess
  • Arterial
  • LocalStreet
  • Terminal
  • Rotary
  • Ramp
matchType Information on the type of match. One of:

  • AddressPoint
  • HouseNumberRange
  • Street
Address
buildingNumber See streetNumber. String
streetNumber The building number on the street. String
routeNumbers The codes used to unambiguously identify the street. String[]
street See streetName. String
streetName The street name. String
streetNameAndNumber The street name and number. String
speedLimit The speed limit for the street in the form DD.DDUUU, e.g. 30.00KPH. D is a digit. UUU is either KPH or MPH (whichever is correct for the address). String
countryCode Country. String
countrySubdivision State or Province. String
countrySecondarySubdivision County. String
countryTertiarySubdivision Named Area. String
municipality City / Town. String
postalCode Postal Code / Zip Code. String
municipalitySubdivision Sub / Super City. String
sideOfStreet String  
offsetPosition String  
country Country name. String
countryCodeISO3 ISO alpha-3 country code. String
freeformAddress An address line formatted according to formatting rules of Result's country of origin or in case of countries it's full country name. String
boundingBox Bounding box of the location. BoundingBox
countrySubdivisionName A full name of a first level of country administrative hierarchy. This field appears only in case countrySubdivision is presented in an abbreviated form. Supported only for USA, Canada and Great Britain. String
extendedPostalCode Extended postal code (availability dependent on region). String
BoundingBox
northEast North-east (top-left) "latitude, longitude" coordinate of the bounding box. String
southWest South-west (bottom-right) "latitude, longitude" coordinate of the bounding box. String
entity Entity type the bounding box was source for. For reverse geocoding this is always equal to position. String
SpatialKeys
priority   String
val   String
LatLon
lat Latitude. Double
lon Longitude. Double

Request - geographies

This request constrains reverse geocoding to geographies only. You can specify the level of geography to get a geometry for. The geometry data can be fetched using Additional Data service.

Format

GET https://<baseURL>/search/<versionNumber>/reverseGeocode/<position>.<ext>?key=<apiKey>&entityType=<entityType>[&spatialKeys=<spatialKeys>][&radius=<radius>][&callback=<callback>][&language=<language>][&allowFreeformNewline=<allowFreeformNewline>][&view=<view>][&dateTime=<dateTime>]
        

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], 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. Struck-through parameters are ignored. The order of request parameters is not important.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 2. Yes 2
position This is specified as a comma-separated string composed by lat., lon. (e.g.: 37.337,-121.89). Yes Position
ext Valid response formats are JSON, JSONP, JS or XML. Yes String
key Your TomTom API key. Yes String
entityType This parameter specifies the level of filtering performed on geographies. Providing the parameter narrows the search for specified geography entity types. The resulting response will contain the geography ID as well as the entity type matched. This ID is a token that can be used to get the geometry of that geography. Yes Comma-Separated String
One or more of:

  • Country
  • CountrySubdivision
  • CountrySecondarySubdivision
  • CountryTertiarySubdivision
  • Municipality
  • MunicipalitySubdivision
  • Neighbourhood
  • PostalCodeArea
[spatialKeys]
DEPRECATED1
If the "spatialKeys" flag is set, the response will also contain a proprietary geo-spatial key information for a specified location. No Boolean false
[radius] The maximum distance in meters from the specified position for the reverse geocode to consider. No Integer 10,000 meters (10 km)
[callback] Specifies the jsonp callback method. No String cb
[language] Language in which search results should be returned. Should be one of supported IETF language tags, case insensitive. When data in specified language is not available for a specific field, default language is used.
DEPRECATION NOTE: support for no-NO will be removed in favour of nb-NO.
No String NGT
[allowFreeformNewline] Format of newlines in the formatted address. If true, the address will contain newlines. Otherwise, newlines will be converted to spaces. No Boolean false
[view] Geopolitical View. The context used to resolve handling disputed territories. Views include Unified, along with AR, IL, IN, MA and PK which are tailored for Argentina, Israel, India, Morocco and Pakistan respectively. No String
One of:

  • Unified
  • AR
  • IL
  • IN
  • MA
  • PK
See  default view mapping.
[dateTime] The date and time to return time zone information for. It allows the service to decide whether Daylight Saving Time time zone should be used or not. It must conform to RFC-33393 (e.g.: 2017-12-19T16:39:57, 2017-12-19T16:39:57-08:00, 2018-10-28T00:00:00Z). No Date
heading Ignored.
number Ignored.
returnRoadUse Ignored.
returnSpeedLimit Ignored.
roadUse Ignored.
returnMatchType Ignored.

Response - geographies

Format

For illustrative purposes the example below is neatly indented and includes all possible response fields. Actual responses are more compact and the fields present will vary based on the result type and the data available. See the response field documentation below for more information.

When requesting JSON output, and no geography of the given type is found, the response is empty:

{
    "summary": {
        "queryTime": 5,
        "numResults": 0
    },
    "addresses": [],
    "spatialKeys": []
}
    

When requesting JSON output, and a geography of the given type is found, the response has the following structure:

{
    "summary": {
        "queryTime": 7,
        "numResults": 1
    },
    "addresses": [],
    "spatialKeys": []
}

Each element of the addresses array is in the format:

{
    "address": {
        "routeNumbers": [],
        "countryCode": "US",
        "countrySubdivision": "CA",
        "countrySecondarySubdivision": "Santa Cruz",
        "countryTertiarySubdivision": "Santa Cruz",
        "municipality": "Live Oak",
        "postalCode": "95065",
        "country": "United States Of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "Live Oak, CA 95065",
        "boundingBox": {
          "northEast": "37.014937,-121.965482",
          "southWest": "36.967406,-122.001081",
          "entity": "position"
        },
        "countrySubdivisionName": "California"
    },
    "position": "36.988167,-121.974884",
    "dataSources": {
        "geometry": {
          "id": "00005543-3300-3c00-0000-000065a03d76"
        }
    },
    "entityType": "PostalCodeArea"
}

Each element of the spatialKeys array is in the format:

{
    "priority": "0",
    "val": "1563238492"
}

Response fields

The tables below 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.

Field Description Type / Values
Response
summary Summary information about the search that was performed. Summary
addresses Result list, sorted in descending order by score. Result[]
spatialKeys Proprietary geo-spatial key information for a specified location. SpatialKeys
Summary
queryTime Time spent on resolving the query. Integer
numResults Number of Results in the response. Integer
Result
dataSources Optional section. Reference ids for service that allows you to request extra data. See: Additional Data service. DataSources
entityType The type of geography. One of:

  • Country
  • CountrySubdivision
  • CountrySecondarySubdivision
  • CountryTertiarySubdivision
  • Municipality
  • MunicipalitySubdivision
  • Neighbourhood
  • PostalCodeArea
Address
routeNumbers The codes used to unambiguously identify the street. String[]
countryCode Country. String
countrySubdivision State or Province. String
countrySecondarySubdivision County. String
countryTertiarySubdivision Named Area. String
municipality City / Town. String
postalCode Postal Code / Zip Code. String
municipalitySubdivision Sub / Super City. String
country Country name. String
countryCodeISO3 ISO alpha-3 country code. String
freeformAddress An address line formatted according to formatting rules of Result's country of origin or in case of countries it's full country name. String
boundingBox Bounding box of the location. BoundingBox
countrySubdivisionName A full name of a first level of country administrative hierarchy. This field appears only in case countrySubdivision is presented in an abbreviated form. Supported only for USA, Canada and Great Britain. String
BoundingBox
northEast North-east (top-left) "latitude, longitude" coordinate of the bounding box. String
southWest South-west (bottom-right) "latitude, longitude" coordinate of the bounding box. String
entity Entity type the bounding box was source for. For reverse geocoding this is always equal to position. String
SpatialKeys
priority   String
val   String
DataSources
geometry Information about the geometric shape of the result. Geometry
Geometry
id Pass this as geometryId to the Additional Data service to fetch geometry information for this result. String
LatLon
lat Latitude. Double
lon Longitude. Double

Default view mapping

Default view recognition is based on the country the request originates from.

Country Default view Other available views
Argentina AR Unified, IL, IN, MA, PK
India IN
Morocco MA Unified, AR, IL, IN, PK
Pakistan PK Unified, AR, IL, IN, MA
Others Unified AR, IL, IN, MA, PK

Response codes

Code Meaning and possible causes
200 OK: the search successfully returned zero or more results.
400 Bad Request: one or more parameters were incorrectly specified.
403 Forbidden: possible causes include:

  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
405 Method Not Allowed: the HTTP method (GET, POST, etc) is not supported for this request.
404/596 Not Found: the HTTP request method (GET, POST, etc) or path is incorrect.
5xx Server Error: the service was unable to process your request. Contact support to resolve the issue.

Response headers

Header Description Value
Access-Control-Allow-Origin Ensures that clients that implement the CORS security model are able to access the response from this service. *
Content-Type Indicates the format of the response, as chosen by the client. Format: type/subtype; charset=utf-8 type/subtype is one of:

  • application/json
  • text/javascript
  • text/xml

1March 1, 2018: The spatialKeys parameter has been deprecated and will be withdrawn following a 12 month deprecation period. The planned withdrawal date is March 1, 2019. Following withdrawal, API requests that include the spatialKeys parameter will receive an HTTP 400 error in response.

2See: RFC 8259
"An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas.
array = begin-array [ value *( value-separator value ) ] end-array"

3See: RFC 3339