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

You can easily run this and other endpoints.

1. Go to the TomTom API Explorer page.
2. Click an endpoint.
   1. Click Try it out.
   2. Enter/select all required parameter values and any optional parameter values.
   3. At the bottom of the form, click Execute.
3. Review the Response.

Request formats

HTTPS Method: GET

URL format

For identification purposes:

• Required constants and parameters are shown in bold.
• Optional parameters are shown in plain text.

https://api.tomtom.com/search/2/routedSearch/gas/37.8328,-122.27669/90.json?key=*****
&typeahead=false&limit=10&multiplier=2&routingTimeout=5000&language=en-us&extendedPostalCodesFor=POI&idxSet=POI

curl command

curl -X GET "https://api.tomtom.com/search/2/routedSearch/gas/37.8328,-122.27669/90.json?key=*****
&typeahead=true
&limit=10
&multiplier=2
&routingTimeout=5000
&language=en-us
&extendedPostalCodesFor=POI
&idxSet=POI"
-H "accept: */*"

▲ Return to top

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.
• A parameter's data type is beneath its name.
• 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.

<

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"
    },
    "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": {
        "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"
        }
    }
}

▲ Return to top

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.
results[] array	Result list, sorted in descending order by score.
summary{} object
Field	Description
query string	Query as interpreted by the search engine.
queryType string	Response type. See the following response types.
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 string	Position used to bias the Results: LatLon
result[] array
Field	Description
type string	Type of Result. One of: POI Street Geography Point Address Address Range Cross Street
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.
info string	Information about the original data source of the Result.
entityType string	Optional section. Only present if type = = Geography. One of: Country CountrySubdivision CountrySecondarySubdivision CountryTertiarySubdivision Municipality MunicipalitySubdivision Neighbourhood PostalCodeArea
poi object	Optional section. Only present if type = = POI.
address object	Structured address for the Result.
position object	Position of the Result: Latitude, Longitude
viewport object	A viewport which can be used to display the Result on a map.
entrypoints array	List of entry points of the POI.
route object	A route from the query position and heading to this Result.
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. Use classifications instead. May 1, 2018: The categories response field has been deprecated. It will be withdrawn following a 12 month deprecation period. The planned withdrawal date is May 1, 2019.
classifications array	The list of POI category classifications.
classifications{} object
Field	Description
code string	Fixed top level category code. For more information, see: Category Code
names array	List of category names with locale code information. Currently only the en-US locale is returned.
names[] array
Field	Description
nameLocale string	Locale code of this category name.
name string	Category name in a 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	A country
countryTertiarySubdivision string	A 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
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	The full name of a first level country administrative hierarchy. This field appears only in case countrySubdivision is presented in an abbreviated form. Supported only for USA, Canada, and Great Britain.
viewport{} object
Field	Description
topLeftPoint string	Top-left corner of the rectangle: LatLon
btmRightPoint string	Bottom-right corner of the rectangle: LatLon
entryPoints[] array
Field	Description
type string	The main entry point. One of: main minor
position string	Position of the entry point: Latitude, Longitude
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	The beginning point of a street segment: Latitude, Longitude
to string	The end point of a street segment: Latitude, Longitude
dataSources{} object
Field	Description
geometry object	Information about the geometric shape of the result. Only present if type = = Geography or POI.
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.
routeSummary object	Summary information about the route as a whole.
routeInstructions{} object
Field	Description
list array	An ordered list of human readable guidance instructions.
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 (MeasuredUnit)	The distance from a preceding maneuver.
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: 0.0° is straight ahead. 90.0° is a right-angle turn to the right. 270.0° is a right-angle turn to the left, and so on.
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.
routeSummary{} object
Field	Description
boundingBox object (BoundingBox)	A box that minimally encloses the route.
totalDistance object (MeasuredUnit)	The sum of the routeInstruction distances.
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.
lat/lon
Field	Description
lat double	Latitude.
lon double	Longitude.
measuredUnit
Field	Description
value double	A distance in the unit uom (unit of measurement).
uom integer (miles)	Indicates that value is expressed in miles.

▲ Return to top

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: 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.

▲ Return to top

Response headers

The following table contains Response headers sent back from an API server.

Header	Description
Access-Control-Allow-Origin	Ensures that clients that implement the CORS security model are able to access the response from this service. Value: *
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: application/json text/javascript text/xml