Routed Search (Deprecated)
Service version: 2
Last edited: 2020.07.02
Deprecation notice
May 1, 2018:
- The Routed Search endpoint has been deprecated.
- This endpoint will be withdrawn following a 12 month deprecation period.
- The planned withdrawal date is May 1, 2019.
- Following withdrawal, requests to this endpoint will receive an HTTP 404 error in response.
On this page
Purpose
The Routed Search endpoint allows you to perform a free-form search from any location with a given heading. Results will contain information regarding the:
- drive distance
- drive time
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
For ease of viewing and identification:
- Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
- See the following Request parameters section with the Required and Optional parameters tables for these values.
https://<baseURL>/search/<versionNumber>/routedSearch/<query>/<position>/<heading>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&multiplier=<multiplier>][&routingTimeout=<routingTimeout>][&language=<language>][&idxSet=<idxSet>][&extendedPostalCodesFor=<extendedPostalCodesFor>]
curl command format
curl 'https://<baseURL>/search/<versionNumber>/routedSearch/<query>/<position>/<heading>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&multiplier=<multiplier>][&routingTimeout=<routingTimeout>][&language=<language>][&idxSet=<idxSet>][&extendedPostalCodesFor=<extendedPostalCodesFor>]'
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. Value: The current value is 2 .
|
query string |
The query string.
|
position string (Position) |
Lat/Lon Value: Example: 37.819722,-122.478611
|
heading decimal |
A direction that a person or vehicle is facing, usually similar to its course. Degrees are measured clockwise from the north. Value: A direction degree. |
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 headers | |
Header | Description |
[Accept-Encoding] string |
Enables response compression. Value: gzip |
Optional parameters | |
Parameter | Description |
[typeahead] boolean |
If the typeahead flag is set:
false
|
[limit] integer |
Maximum number of responses that will be returned. Default value: 10 Maximum value: 100
|
[multiplier] integer |
Multiplies the limit by N to gather more candidate POIs.
2
|
[routingTimeout] integer (milliseconds) |
Only returns results from the routing engine within this limit. Default value: 4000
|
[language] string |
Language in which search results should be returned.
|
[extendedPostalCodesFor] string |
Indexes for which extended postal codes should be included in the results.
extendedPostalCode property of an address. Availability is region-dependent.Values: See the preceding list of available indexes. |
idxSet string |
The idxSet parameter allows fine tuning Search by specifying which indexes to utilize for the search. The pre-defined indexes are:
|
Response data
Response body
For illustrative purposes the following example 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 documentation for more information.
When requesting JSON output the Response has the following structure:
{
"summary": {
"query": "pizza",
"queryType": "NON_NEAR",
"queryTime": 1498,
"numResults": 10,
"offset": 0,
"totalResults": 265482,
"fuzzyLevel": 1,
"geoBias": {
"lat": 36.98844,
"lon": -121.97483
}
},
"results": []
}
Each element of the results
array is in the following format:
{
"type": "POI",
"id": "US/POI/p0/9033556",
"score": 5,
"dist": 0,
"info": "search:ta:840061001865142-US",
"entityType": "Municipality",
"poi": {
"name": "Upper Crust Pizza & Pasta",
"phone": "+(1)-(831)-4762333",
"url": "www.uppercrustsc.com/",
"categories": [
"pizza",
"restaurant"
],
"classifications": [
{
"code": "RESTAURANT",
"names": [
{
"nameLocale": "en-US",
"name": "pizza"
},
{
"nameLocale": "en-US",
"name": "restaurant"
}
]
}
]
},
"address": {
"streetNumber": "2501",
"streetName": "Soquel Dr",
"municipalitySubdivision": "Santa Cruz, Live Oak",
"municipality": "Santa Cruz, Live Oak",
"countrySecondarySubdivision": "Santa Cruz",
"countryTertiarySubdivision": "Santa Cruz",
"countrySubdivision": "CA",
"postalCode": "95065",
"extendedPostalCode": "950652023",
"countryCode": "US",
"country": "United States Of America",
"countryCodeISO3": "USA",
"freeformAddress": "2501 Soquel Dr, Santa Cruz, CA 95065",
"countrySubdivisionName": "California",
"localName": "Santa Cruz"
},
"position": {
"lat": 36.98844,
"lon": -121.97483
},
"viewport": {
"topLeftPoint": {
"lat": 36.98934,
"lon": -121.97596
},
"btmRightPoint": {
"lat": 36.98754,
"lon": -121.9737
}
},
"entryPoints": [
{
"type": "main",
"position": {
"lat": 36.98817,
"lon": -121.97487
}
}
],
"addressRanges": {
"rangeLeft": "1 - 3",
"rangeRight": "2 - 12",
"from": {
"lat": 51.16561,
"lon": 19.48489
},
"to": {
"lat": 51.16545,
"lon": 19.4863
}
},
"dataSources": {
"chargingAvailability": {
"id": "442009000132285"
},
"geometry": {
"id": "00004e4c-3100-3c00-0000-0000685e23c7"
}
},
"route": {
"routeGeometry": [
"36.98847, -121.97506"
],
"routeInstructions": {
"list": [
{
"Instruction": "Proceed North on Winkle Ave",
"Point": "36.98847,-121.97506",
"description": "route maneuver 1",
"distance": {
"value": 0,
"uom": "MI"
},
"duration": "P0DT0H0M0S",
"waitTime": "P0DT0H0M0S",
"turnAngle": 0,
"turn": "Proceed",
"tour": 0
},
{
"Instruction": "Arrive at destination",
"Point": "36.98847,-121.97506",
"description": "route maneuver 2",
"distance": {
"value": 0,
"uom": "MI"
},
"duration": "P0DT0H0M0S",
"waitTime": "P0DT0H0M0S",
"turnAngle": 0,
"tour": 0,
"sideOfStreet": "Unknown"
}
],
"language": "english"
},
"routeSummary": {
"boundingBox": {
"topLeftPoint": "36.98846999999999, -121.97505999999998",
"btmRightPoint": "36.98846999999999, -121.97505999999998"
},
"totalDistance": {
"value": 0,
"uom": "MI"
},
"totalTime": "P0DT0H0M0S",
"totalTravelTime": "P0DT0H0M0S",
"totalWaitTime": "P0DT0H0M0S"
}
}
}
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.
- 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
|
results[] array |
Result list, sorted in descending order by score.results[] array
|
summary{} object |
|
Field | Description |
query string |
Query as interpreted by the search engine. |
queryType string |
Response type. Can be NEARBY or NON_NEAR. |
queryTime integer |
Time spent on resolving the query. |
numResults integer |
Number of Results in the response. |
offset integer |
Starting offset of the returned Results within the full Result set. |
totalResults integer |
Total number of Results found. |
fuzzyLevel integer |
Maximum fuzzy level required to provide Results. |
geoBias comma separated string composed by lat,lon |
Position used to bias the Results:LatLon double Example: 37.553,-122.453
|
results[] array |
|
Field | Description |
type string |
Type of Result. One of:
|
id string |
Non-stable id for this Result. |
score double |
Score of the Result. A larger score means there is a probability that a Result meeting the query criteria is higher. |
dist double |
Unit: meters. This is the distance to an object if geobias was provided. |
info string |
Information about the original data source of the Result. |
entityType string |
Optional section. Only present if type == Geography. One of:
|
poi object |
Optional section. Only present if type == POI.poi{} object
|
address object |
Structured address for the Result.address{} object
|
position object |
Position of the Result:LatLon double Example: 37.553,-122.453
|
viewport object |
A viewport which can be used to display the Result on a map. viewport{} object
|
entrypoints array |
List of entry points of the POI.entryPoints[] array
|
addressRanges object |
Address ranges on a street segment. Available only for Results where the Result type is equal to "Address Range". addressRanges{} object
|
poi{} object |
|
Field | Description |
name string |
Name of the POI. |
phone string |
Telephone number. |
url string |
Website URL. |
categories array Deprecated |
The list of POI categories. Category Codes
|
classifications array |
The list of POI category classifications.classifications[] array
|
classifications[] array |
|
Field | Description |
code string |
Fixed top level category code. Category Codes |
names array |
List of category names with locale code information. Currently only "en-US" locale is returned. names[] array
|
names[] array |
|
Field | Description |
nameLocale string |
Locale code of this category name. |
name string |
Category name in given locale. |
address{} object |
|
Field | Description |
streetNumber string |
The building number on the street. |
streetName string |
The street name. |
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 |
extendedPostalCode string |
Extended postal code (availability dependent on region) |
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 formatting rules of a Result's country of origin,or in case of countries its full country name. |
countrySubdivisionName string |
A full name of a first level of country administrative hierarchy.
|
localName 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. |
viewport{} object |
|
Field | Description |
topLeftPoint comma separated string composed by lat,lon |
Top left corner of the rectangle:LatLon double
|
btmRightPoint comma separated string composed by lat,lon |
Bottom right corner of the rectangle:LatLon double
|
entryPoints[] array |
|
Field | Description |
type string |
Main entry point: One of:
|
position string |
Position of the entry point:LatLon double Example: 37.553,-122.453
|
addressRanges{} object |
|
Field | Description |
rangeLeft string |
An address range on the left side of a street segment (assuming looking from the "from" end toward the "to" end). |
rangeRight string |
An address range on the right side of a street segment (assuming looking from the "from" end toward the "to" end). |
from string |
A beginning point of a street segment:LatLon double
|
to string |
An end point of a street segment:LatLon double
|
dataSources{} object |
|
Field | Description |
chargingAvailability object |
Information about the charging stations availability. Only present if type == POI. |
id string |
Pass this as chargingAvailability to the EV Charging Stations Availability service to fetch charging availability information for this result. |
geometry object |
Information about the geometric shape of the result. Only present if type == Geography or POI. |
id string |
Pass this as geometryId to the Additional Data service to fetch geometry information for this result.
|
route{} object |
|
Field | Description |
routeGeometry array |
An ordered list of strings each in the form of "latitude, longitude" denoting points along the route. |
routeInstructions object |
Human readable guidance on how to follow the route.routeInstructions{} object
|
routeSummary object |
Summary information about the route as a whole.routeSummary{} object
|
routeInstructions{} object |
|
Field | Description |
list array |
An ordered list of human readable guidance instructions.routeInstructions{} object
|
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.
- 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
|
results[] array |
Result list, sorted in descending order by score.results[] array
|
summary{} object |
|
Field | Description |
query string |
Query as interpreted by the search engine. |
queryType string |
Response type. Can be NEARBY or NON_NEAR. |
queryTime integer |
Time spent on resolving the query. |
numResults integer |
Number of Results in the response. |
offset integer |
Starting offset of the returned Results within the full Result set. |
totalResults integer |
Total number of Results found. |
fuzzyLevel integer |
Maximum fuzzy level required to provide Results. |
geoBias comma separated string composed by lat,lon |
Position used to bias the Results:LatLon double Example: 37.553,-122.453
|
results[] array |
|
Field | Description |
type string |
Type of Result. One of:
|
id string |
Non-stable id for this Result. |
score double |
Score of the Result. A larger score means there is a probability that a Result meeting the query criteria is higher. |
dist double |
Unit: meters. This is the distance to an object if geobias was provided. |
info string |
Information about the original data source of the Result. |
entityType string |
Optional section. Only present if type = = Geography. One of:
|
poi object |
Optional section. Only present if type == POI.poi{} object
|
address object |
Structured address for the Result.address{} object
|
position object |
Position of the Result:LatLon double Example: 37.553,-122.453
|
viewport object |
A viewport which can be used to display the Result on a map. viewport{} object
|
entrypoints array |
List of entry points of the POI.entryPoints[] array
|
addressRanges object |
Address ranges on a street segment. Available only for Results where the Result type is equal to "Address Range". addressRanges{} object
|
poi{} object |
|
Field | Description |
name string |
Name of the POI. |
phone string |
Telephone number. |
url string |
Website URL. |
categories array Deprecated |
The list of POI categories. Category Codes
|
classifications array |
The list of POI category classifications.classifications[] array
|
classifications[] array |
|
Field | Description |
code string |
Fixed top level category code. Category Codes |
names array |
List of category names with locale code information. Currently only "en-US" locale is returned. names[] array
|
names[] array |
|
Field | Description |
nameLocale string |
Locale code of this category name. |
name string |
Category name in given locale. |
address{} object |
|
Field | Description |
streetNumber string |
The building number on the street. |
streetName string |
The street name. |
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 |
extendedPostalCode string |
Extended postal code (availability dependent on region) |
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 formatting rules of a Result's country of origin,or in case of countries its full country name. |
countrySubdivisionName string |
A full name of a first level of country administrative hierarchy.
|
localName string |
Address area name. This field appears only for POI and PAD abbreviated value types. |
viewport{} object |
|
Field | Description |
topLeftPoint comma separated string composed by lat,lon |
Top left corner of the rectangle:LatLon double
|
btmRightPoint comma separated string composed by lat,lon |
Bottom right corner of the rectangle:LatLon double
|
entryPoints[] array |
|
Field | Description |
type string |
Main entry point: One of:
|
position string |
Position of the entry point:LatLon double Example: 37.553,-122.453
|
addressRanges{} object |
|
Field | Description |
rangeLeft string |
An address range on the left side of a street segment (assuming looking from the "from" end toward the "to" end). |
rangeRight string |
An address range on the right side of a street segment (assuming looking from the "from" end toward the "to" end). |
from string |
A beginning point of a street segment:LatLon double
|
to string |
An end point of a street segment:LatLon double
|
dataSources{} object |
|
Field | Description |
chargingAvailability object |
Information about the charging stations availability. Only present if type == POI. |
id string |
Pass this as chargingAvailabilityId to the Additional Data service to fetch charging availability information for this result. |
geometry object |
Information about the geometric shape of the result. Only present if type == Geography or POI. |
id string |
Pass this as geometryId to the Additional Data service to fetch geometry information for this result.
|
route{} object |
|
Field | Description |
routeGeometry array |
An ordered list of strings each in the form of "latitude, longitude" denoting points along the route. |
routeInstructions object |
Human readable guidance on how to follow the route.routeInstructions{} object
|
routeSummary object |
Summary information about the route as a whole.routeSummary{} object
|
routeInstructions{} object |
|
Field | Description |
list array |
An ordered list of human readable guidance instructions.routeInstructions{} object
|
Instruction string |
A human readable instruction. For example, "Turn left onto". |
Point string |
The "latitude,longitude" location at which the instructions should be executed. |
description string |
A string describing the instruction, currently in the form "route maneuver N" with "N" being the 1-based index into the list of instructions. |
distance object |
The distance from a preceding maneuver.totalDistance{} object (formerly named measuredUnit)
|
duration string |
The expected time to complete this maneuver. |
waitTime string |
Time spent waiting at intersections. |
turnAngle double |
The angle of the turn in the maneuver. For example:
|
turn string |
The procedure to complete this maneuver. Typically this is an instruction such as "Turn right". |
tour integer |
The number of waypoints passed thus far. |
language string |
The language that the human readable instructions are given in.english
|
routeSummary{} object |
|
Field | Description |
boundingBox object ( )
|
A box that minimally encloses the route.boundingBox{} object
|
totalDistance object |
The sum of the routeInstruction distances.totalDistance{} object (formerly named measuredUnit)
|
totalTime string |
The sum of the routeInstruction durations. |
totalTravelTime string |
The sum of the routeInstruction durations. |
totalWaitTime string |
The sum of the routeInstruction durations, ex (in) cluding the waitTimes. |
boundingBox{} object |
|
Field | Description |
topLeftPoint string |
Top-left "latitude, longitude" coordinate of the bounding box. |
btmRightPoint string |
Bottom right "latitude, longitude" coordinate of the bounding box. |
LatLon |
|
Field | Description |
lat float |
Latitude. min/max: -90 to +90 Reference: Latitude, Longitude and Coordinate System Grids |
lon float |
Longitude. min/max: -180 to +180 Reference: Latitude, Longitude and Coordinate System Grids |
totalDistance{} object (formerly named measuredUnit) |
|
Field | Description |
value double |
A distance in the unit uom (unit of measurement). |
uom integer (miles) |
Indicates that value is expressed in miles. |
HTTP Response codes
The following data 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. |
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: The type/subtype is one of:
|
Content-Encoding |
If requested by the client, the Search service applies gzip compression to the Responses with the Accept-Encoding header. Value: gzip
|