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.

HTTPS Method: GET

URL format

GET 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>]

▲ 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, 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.

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

▲ 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. 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: 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. 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: County CountrySubdivision CountrySecondarySubdivision CountryTertiarySubdivision Municipality MunicipalitySubdivision Neighbourhood PostalCodeArea
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 Deprecated: Use classifications instead. As of May 1, 2018: The Response categories 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[] 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. 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 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: main minor
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: 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. 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.

▲ 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 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: application/json text/javascript text/xml