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

CrossStreet lookup


There may be times when you need to translate a coordinate (example: 37.786505, -122.3862) into a human understandable street address. Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the point is located.

This endpoint will return address information for a position.

Request

Format

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

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
[limit] Only applicable to cross-street lookup, controls the max number of cross-streets to return. No Integer 1 100
[spatialKeys]
DEPRECATED1
If the "spatialKeys" flag is set, the response will also contain the deCarta proprietary geo-spatial key information for a specified location. 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 up to 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)
[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. No String
[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.

Response

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": {
        "numResults": 1,
        "queryTime": 176
    },
    "addresses": [],
    "spatialKeys": []
}

Each element of the addresses array is in the format:

{
    "address": {
        "streetName": "Soquel Dr & Winkle Ave",
        "crossStreet": "Soquel Dr",
        "municipalitySubdivision": "Santa Cruz, Live Oak",
        "municipality": "Santa Cruz, Live Oak",
        "countrySecondarySubdivision": "Santa Cruz",
        "countryTertiarySubdivision": "Santa Cruz",
        "countrySubdivision": "CA",
        "postalCode": "95065",
        "countryCode": "US",
        "country": "United States Of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "Soquel Dr & Winkle Ave, Santa Cruz, CA 95065",
        "countrySubdivisionName": "California",
        "street": "Winkle Ave"
    },
    "position": "36.9882,-121.97511"
}

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
numResults Number of Results in the response. Integer
queryTime Time spent on resolving the query. Integer
Result
address Structured address for the Result. Address
position Position of the Result. LatLon
Address
streetName The names of the streets crossing each other. String
crossStreet The street being crossed. String
municipalitySubdivision Sub / Super City. String
municipality City / Town. String
countrySecondarySubdivision County. String
countryTertiarySubdivision Named Area. String
countrySubdivision State or Province. String
postalCode Postal Code / Zip Code. String
countryCode Country. 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
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
street The street crossing the crossStreet. String
SpatialKeys
priority String
val String

Default view mapping

Default view is recognised based on the country the request came 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.