Autocomplete

Service version: 2
Last edit: 2022.12.13

Purpose

The Autocomplete API enables you to make a more meaningful Search API call by recognizing entities inside an input query and offering them as query terms.

Request data

HTTPS Method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
get
URL request format
https://{baseURL}/search/{versionNumber}/autocomplete/{query}.{ext}?key={Your_API_Key}&language={language}&limit={limit}&lat={lat}&lon={lon}&radius={radius}&countrySet={countrySet}&resultSet={resultSet}
get
URL request example
https://api.tomtom.com/search/2/autocomplete/pizza.json?key={Your_API_Key}&language=en-US
get
curl command request example
curl 'https://api.tomtom.com/search/2/autocomplete/pizza.json?key={Your_API_Key}&language=en-US'

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.
  • The order of request parameters is not important.
Required  parametersDescription

baseURL
string

Base URL for calling the API.
Values:

versionNumber
string

The service version.
Value: The current value is 2.

query
string

Query string.
Value: Must be properly URL encoded.

ext
string

A valid response format.
Values: json , xml

key
string

An API Key valid for the requested service.
Value: Your valid TomTom API Key.

language
string

Language in which autocomplete results should be returned.
Value: One of the TomTom IETF Supported Language Tags.

Optional parametersDescription

limit
integer

Maximum number of autocomplete results that will be returned.
Default value: 5
Maximum value: 10

lat
float

Latitude, e.g., lat=37.337. It must be used in conjunction with the lon parameter. Results should be biased to the position defined by the lat, lon parameters. Note: supplying a lat/lon without a radius will bias the autocomplete results only to that point.
Value: min/max: -90 to +90
Reference: Latitude, Longitude, and Coordinate System Grids

lon
float

Longitude, e.g.,lon=-121.89. It must be used in conjunction with the lat parameter. Results should be biased to the position defined by the lat, lon parameters. Note: supplying a lat/lon without a radius will bias the autocomplete results only to that point.
Value: min/max: -180 to +180
Reference: Latitude, Longitude, and Coordinate System Grids

radius
integer

The radius parameter must be used in conjunction with the lat , lon parameters. If radius , lat , and lon are set, the results will be constrained to the defined area.
Value: min/max: 0 to 5000000 Note: The radius parameter is specified in meters. Values greater than 5000000 meters are reduced to 5000000. Values less than 0 will respond with code 400 Bad request.

countrySet
string

A comma-separated string of country codes (e.g., FR,ES). This will limit the autocomplete results to the specified countries. See the Search API Market Coverage page for a list of all the countries supported by the Autocomplete API engine.
Values: FR,ES, etc.

resultSet
string

Restricts the result space based on their segment types. A result is only included if it contains a segment of any of the indicated types.
Value: A comma-separated list that consists of the types of segments.
Usage examples:

  • resultSet=category

  • resultSet=brand

  • resultSet=category,brand

Request headers

Note: There are no required request headers in this endpoint.

Optional headersDescription

Accept-Encoding

Should contain a list of encodings acceptable by the client. Usually used to demand a compressed response.
Value: gzip

Tracking-ID

Specifies an identifier for the request. It is only meant to be used for support and does not involve tracking of you or your users in any form. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of a format that matches this regular expression is UUID. If specified, it is replicated in the Tracking-ID response header.
Value: A request identifier, e.g., 3c8ea54d-e217-49b3-8c16-d13accf2e84a

Response data

Response body

Please note that actual responses will vary based on the data available. See the following response fields section for more information. When requesting JSON output, the response has the following structure:

Response structure - JSON
1 "context":{
2 "inputQuery":"mazda dealer Warszawa",
3 "geoBias":{
4 "position":{
5 "lat":51.759431,
6 "lon":19.448653
7 },
8 "radius": 10000
9 }
10 },
11 "results":[
12 {
13 "segments": []
14 },
15 ...
16 ]
17}

Each element of the segments array can be one of:

segments array - JSON
1{
2 "type": "brand",
3 "value": "Mazda",
4 "matches": {
5 "inputQuery": [
6 {
7 "offset": 0,
8 "length": 5
9 }
10 ]
11 }
12}
Category segment - JSON
1{
2 "type": "category",
3 "value": "Automotive Dealer",
4 "matches": {
5 "inputQuery": [
6 {
7 "offset": 6,
8 "length": 6
9 }
10 ]
11 },
12 "id": "9910",
13 "matchedAlternativeName": "Dealer"
14}
Plaintext segment - JSON
1{
2 "type": "plaintext",
3 "value": "Warszawa",
4 "matches": {
5 "inputQuery": [
6 {
7 "offset": 8,
8 "length": 13
9 }
10 ]
11 }
12}

When requesting XML output, the response has the following structure:

Response structure - XML
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2<response>
3 <context>
4 <inputQuery>mazda dealer Warszawa</inputQuery>
5 <geoBias>
6 <position>
7 <lat>51.759431</lat>
8 <lon>19.448653</lon>
9 </position>
10 <radius>10000</radius>
11 </geoBias>
12 </context>
13 <results>
14 <result>
15 <segments>
16 <segment type="...">
17 ...
18 </segment>
19 ...
20 </segments>
21 </result>
22 ...
23 </results>
24</response>

The <segments> element will contain one or more of following segment types:

Brand segment - XML
1<segment type="brand">
2 <value>Mazda</value>
3 <matches>
4 <inputQueries>
5 <inputQuery length="5" offset="0"/>
6 </inputQueries>
7 </matches>
8</segment>
Category segment - XML
1<segment type="category">
2 <id>9910</id>
3 <value>Automotive Dealer</value>
4 <matchedAlternativeName>Dealer</matchedAlternativeName>
5 <matches>
6 <inputQueries>
7 <inputQuery length="6" offset="6"/>
8 </inputQueries>
9 </matches>
10</segment>
Plaintext segment - XML
1<segment type="plaintext">
2 <value>Warszawa</value>
3 <matches>
4 <inputQueries>
5 <inputQuery length="8" offset="13"/>
6 </inputQueries>
7 </matches>
8</segment>

Response fields

The following table describes all of the fields that can appear in a response.

Primary fields
FieldDescription

context
object

Information about the autocomplete request that was performed.
context object

results
array

List of the results returned by the autocomplete engine.
result object

context object
FieldDescription

inputQuery
string

Query passed to the autocomplete engine.

geoBias
object

The geo bias passed to the autocomplete engine by setting the position ( lat , lon ) and radius parameters.
geoBias object

geoBias object
FieldDescription

position
object

Position used to bias the results by setting the optional lat and lon request parameters.
LatLon

radius
integer

The optional radius request parameter passed by the user.

LatLon
FieldDescription

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

result object
FieldDescription

segments
array

Describes recognized entities of the result.
segment object

segment object
FieldDescription

type
string

The type of a detected entity. Currently we can detect: category, brand, and plaintext, but more types can appear in the future.

value
string

The value of the detected entity. It may be a category name, brand name, or a part of unrecognized text. For the brand segment type, the value of this field can be used to restrict results of other search endpoints to the Points Of Interest (POI) of specific brands. See the brandSet parameter in the Search service documentation , e.g., the Fuzzy Search endpoint.

matches
object

Defines a mapping between the inputQuery and segment.
matches object

id
string

Provided for the category segment type. This can be used to restrict the results of other search endpoints to the Points Of Interest (POI) of specific categories. See the categorySet parameter in the Search service documentation , e.g., the Fuzzy Search endpoint.

matchedAlternativeName
string

Optionally provided for the category segment type. Present only if a part of the user query matched to the alternative name instead of a primary name. For example, for the input query "petrol station" the category segment value will be "gas station" and the matchedAlternativeName will be "petrol station".

matches object
FieldDescription

inputQuery
array

Informs which part of the input query is represented by segment. Input query matching may not be continuous, so the mapping is defined by an array of matched substrings.
match object

match object
FieldDescription

offset
integer

Starting offset of the inputQuery substring matching the segment.

length
integer

Length of the matched substring.

Response codes

The following data table contains response codes signifying successful and failed requests to an API server.

CodeMeaning & possible causes
200

OK : The autocomplete engine 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
  • Over QPS (Queries per second), or over QPD (Queries per day)
  • Unknown referer
405

Method Not Allowed : Used HTTP method is not supported for this request.

404/596

Not Found : Used HTTP request 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. Retry your request, and if it doesn't solve the problem please contact support to resolve the issue.

Response headers

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

HeaderDescription

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:

  • application/json

  • application/xml

Content-Encoding

Service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.
Value: gzip

Tracking-ID

An identifier for the request. It is only meant to be used for support and does not involve tracking of you or your users in any form. If the Tracking-ID request header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. Value: A request identifier, e.g., 3c8ea54d-e217-49b3-8c16-d13accf2e84a

Error response

The content type of error response depends on the requested output format (JSON or XML).

Error response example (JSON)
1{
2 "detailedError": {
3 "code": "BadRequest",
4 "message": "Request validation failed.",
5 "details": [
6 {
7 "code": "BadArgument",
8 "message": "Missing required parameter: language",
9 "target": "language",
10 "innerError": {
11 "code": "MissingRequiredParameter"
12 }
13 }
14 ]
15 }
16}
Error response example (XML)
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2<response>
3 <detailedError>
4 BadRequest
5 <message>Request validation failed.</message>
6 <details>
7 <detail>
8 BadArgument
9 <message>Missing required parameter: language</message>
10 <target>language</target>
11 <innerError>
12 MissingRequiredParameter
13 </innerError>
14 </detail>
15 </details>
16 </detailedError>
17</response>

Error response fields

Primary fields
FieldDescription

detailedError
object

Detailed information about the error.
detailedError object

detailedError object
FieldDescription

code
string

One of the defined error Response codes.

message
string

A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.

target
string

Optional. Target of the particular error.
Value: The name of the request parameter.

details
array

Optional. An array of root causes (more detailed errors) that led to this error.
detailedError array

innerError
object

Optional. A higher level of details about this error.
innerError object

innerError object
FieldDescription

code
string

One of the defined error response codes.

message
string

Optional. A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.

innerError
object

Optional. A higher level of details about this error.
innerError object

Error code hierarchy

A list of predefined, hierarchical, human-readable error codes. Top level codes relate to HTTP error codes. They may be refined by error codes in details or innerError. Further levels of refinement are possible by nesting innerError inside innerError. In the future, the list may be extended with additional codes. The application must be ready for the occurrence of an unknown error code (e.g., by stopping error processing at the last understood level of detail).

Error codeDescription
BadArgument

One of the request parameters was missing or did not pass validation. The target field contains the name of the related parameter.
Possible inner errors:

  • MissingRequiredParameter

  • InvalidParameterValue

  • MissingDependentParameter

  • ValueOutOfRange

BadRequest

Top level code for requests which ended with HTTP 400 Bad Request. Possible root causes: BadArgument

InternalServerError

Top level code for requests which ended with HTTP 500 Internal Server Error. The service cannot handle the request right now, an unexpected condition was encountered.

InvalidParameterValueThe value of one of the parameters is invalid.
MissingDependentParameter

One of the parameters that is required by another parameter was not specified (for example: parameter lon is missing when lat was specified).

MissingRequiredParameterOne of the required parameters was not provided.
NotFound

Top level code for requests which ended with HTTP 404 Not Found caused by providing incorrect request path.

ServiceUnavailable

Top level code for requests which ended with HTTP 503 Service Unavailable. The service cannot handle the request right now, this is certainly a temporary state.

ValueOutOfRangeThe value of one of numeric parameters is out of allowed range.