CrossStreet lookup
Service version: 2
Last edit: 2020.12.16
On this page
Purpose
This endpoint returns address information and coordinates for a position to the nearest intersection.
- There may be times when you need to translate a coordinate (for 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 an asset, and wish to know the position and address information of the nearest intersection/crossroad to its initial position.
Run this endpoint
You can easily run this and other endpoints.
- Go to the TomTom API Explorer page.
-
Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
Request data
HTTPS Method: GET
URL format
GET https://<baseURL>/search/<versionNumber>/reverseGeocode/crossStreet/<position>.<ext>?key=<Your_API_Key>[&limit=<limit>][&spatialKeys=<spatialKeys>][&radius=<radius>][&language=<language>][&allowFreeformNewline=<allowFreeformNewline>][&view=<view>]
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, 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.
Required parameters | |
---|---|
Parameter | Description |
baseURL string |
The base URL for calling the API. Value: api.tomtom.com
|
versionNumber string |
The service version number. Value: The current version number value is 2 .
|
position string |
This is specified as a comma separated string composed by lat,lon (e.g., 37.337,-121.89 ).Value: A comma separated string composed by lat ,lon .Example: 37.553,-122.453
|
ext string |
A valid response format: Values: JSON, JSONP, JS, or XML |
key string |
An API Key valid for the requested service. Value: Your valid API Key .
|
Optional parameters | |
Parameter | Description |
[limit] integer |
The maximum number of responses that will be returned. Default value: 1 (when the [limit] parameter is absent)Maximum value: 100
|
[spatialKeys] boolean Deprecated |
If the spatialKeys flag is set, the Response will also contain the proprietary geo-spatial key information for a specified location.Default value: false March 1, 2018:
|
[radius] integer |
The maximum distance in meters from the specified position for the reverseGeocode to consider.Default value: 10000 meters (10 km).
|
[language] string |
The language in which the search results should be returned.
Deprecation notice: Support for no-NO will be removed in favour of no-NB. |
[allowFreeformNewline] boolean |
The format of newlines in the formatted address.
false .
|
[view] string |
Geopolitical View.
|
Response data
Response body
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 following Response field section 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 following 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 following format:
{
"priority": "0",
"val": "1563238492"
}
Response fields
The following table describes 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 |
summary{} object |
Summary information about the search that was performed.summary{} object
|
addresses[] array |
Result list, sorted in descending order by score.addresses[] array
|
spatialKeys[] array (Deprecated) |
Proprietary geo-spatial key information for a specified location.spatialKeys[] array March 1, 2018:
|
spatialKeys[] Deprecated |
|
Field | Description |
priority string |
Proprietary geo-spatial key information for a specified location. |
val string |
Proprietary geo-spatial key information for a specified location. |
summary{} object |
|
Field | Description |
numResults integer |
The number of Results in the response. |
queryTime integer |
Time spent on resolving the query. |
addresses[] array |
|
Field | Description |
address{} object |
The structured address for the Result.address{} object
|
position double (LatLon) |
Position of the result in a form of "latitude,longitude" coordinates. Example: 37.553,-122.453
|
address{} object |
|
Field | Description |
streetName string |
The street name. |
crossStreet string |
The street being crossed. |
municipalitySubdivision string |
Sub / Super City |
municipality string |
City / Town |
countrySecondarySubdivision string |
County |
countryTertiarySubdivision string |
Named Area. |
countrySubdivision string |
State or Province |
postalCode string |
Postal Code / Zip Code |
countryCode string |
Country (Note: This is a two-letter code, not a country name.) |
country string |
Country name |
countryCodeISO3 string |
ISO alpha-3 country code |
freeformAddress string |
An address line formatted according to the formatting rules of a Result's country of origin, or in case of countries, its full country name. |
countrySubdivisionName string |
A full name of the first level of a country administrative hierarchy.
|
street string |
The street name. |
spatialKeys[] array (Deprecated) |
|
Field | Description |
priority string |
Proprietary geo-spatial key information for a specified location. |
val string |
Proprietary geo-spatial key information for a specified location. |
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, RU, TR |
India | IN |
- |
Morocco | MA |
Unified, AR, IL, IN, PK, RU, TR |
Pakistan | PK |
Unified, AR, IL, IN, MA, RU, TR |
Russia | RU |
Unified, AR, IL, IN, MA, PK, TR |
Turkey | TR |
Unified, AR, IL, IN, MA, PK, RU |
Others | Unified |
AR, IL, IN, MA, PK, RU, TR |
HTTP Response codes
The following table contains Response codes signifying successful and failed requests to an API server.
Code | Meaning & 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:
|
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. |
429 |
Too Many Requests: The API key is over QPS (Queries per second). |
5xx |
Server Error: The service was unable to process your Request. Contact support to resolve the issue. |
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: type/subtype; charset=utf-8 Value: type/subtype is one of:
|