Sorry, you need to enable JavaScript to visit this website.

Autocomplete

 

Service version: 2
Last edit: 2019.10.31

On this page

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

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

curl command format

curl '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>]'

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.
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 supported IETF language tags.
Optional parameters
Parameter Description
[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 only bias the autocomplete results to that area.
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 only bias the autocomplete results to that area.
Value: min/max: -180 to +180
Reference: Latitude, Longitude and Coordinate System Grids
[radius]
integer
Value: A radius in meters. It must be used in conjunction with lat, lon parameters.
If [radius] and [position] are set:

  • The results will be constrained to the defined area.
  • The [radius] parameter is specified in meters.
[countrySet]
string
A comma-separated string of country codes (e.g., FR,ES).

  • This will limit the autocomplete results to the specified countries.
  • See Market Coverage Search for a list of all the countries supported by the Autocomplete API engine.

Value: FR,ES,etc.

[resultSet]
string
Restricts the result space based on their segment types.
A result is only included if at least one segment is 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

▲ Return to top

Request Headers

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
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: request identifier, e.g., 3c8ea54d-e217-49b3-8c16-d13accf2e84a

▲ Return to top

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:

{
  "context":{
    "inputQuery":"mazda dealer Warszawa",
    "geoBias":{
      "position":{
        "lat":51.759431,
        "lon":19.448653
      },
      "radius": 10000
    }
  },
  "results":[
    {
      "segments":[]
    },
    ...
  ]
}

Each element of the segments array can be one of:

▸ Brand segment:

{
  "type":"brand",
  "value":"Mazda",
  "matches":{
    "inputQuery":[
      {
        "offset":0,
        "length":5
      }
    ]
  }
}

▸ Category segment:

{
  "type":"category",
  "value":"Automotive Dealer",
  "matches":{
    "inputQuery":[
      {
        "offset":6,
        "length":6
      }
    ]
  },
  "id":"9910",
  "matchedAlternativeName":"Dealer"
}

▸ Plaintext segment:

{
  "type":"plaintext",
  "value":"Warszawa",
  "matches":{
    "inputQuery":[
      {
        "offset":8,
        "length":13
      }
    ]
  }
}

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <context>
    <inputQuery>mazda dealer Warszawa</inputQuery>
    <geoBias>
      <position>
        <lat>51.759431</lat>
        <lon>19.448653</lon>
      </position>
      <radius>10000</radius>
    </geoBias>
  </context>
  <results>
    <result>
      <segments>
        <segment type="...">
        ...
        </segment>
        ...
      </segments>
    </result>
    ...
  </results>
</response>

Segments element will contain one or more of following segment types:

▸ Brand segment:

<segment type="brand">
  <value>Mazda</value>
  <matches>
    <inputQueries>
      <inputQuery length="5" offset="0"/>
    </inputQueries>
  </matches>
</segment>

▸ Category segment:

<segment type="category">
  <id>9910</id>
  <value>Automotive Dealer</value>
  <matchedAlternativeName>Dealer</matchedAlternativeName>
  <matches>
    <inputQueries>
      <inputQuery length="6" offset="6"/>
    </inputQueries>
  </matches>
</segment>

▸ Plaintext segment:

<segment type="plaintext">
  <value>Warszawa</value>
  <matches>
    <inputQueries>
      <inputQuery length="8" offset="13"/>
    </inputQueries>
  </matches>
</segment>

▲ Return to top

Response fields

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

Primary fields
Field Description
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
Field Description
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
Field Description
position{}
object
Position used to bias the results by setting the optional [lat] and [lon] Request parameters.
LatLon{} object
radius
integer
The optional [radius] Request parameter passed by the user.
LatLon{} object
Field Description
lat
float
Latitude. Reference: Latitude, Longitude and Coordinate System Grids
lon
float
Longitude. Reference: Latitude, Longitude and Coordinate System Grids
result{} object
Field Description
segment[]
array
Describes recognized entities of the result.
segment{} object
segment{} object
Field Description
type
string
The type of a detected entity. Currently we can detect: category, brand, 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.
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
Field Description
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
Field Description
offset
integer
Starting offset of the inputQuery substring matching the segment.
length
integer
Length of the matched substring.

▲ 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 autocomplete engine successfully returned zero or more results.
400 Bad Request: One or more parameters were incorrectly specified.
403 Forbidden: Possible causes includes:

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

▲ 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: 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: request identifier, e.g., 3c8ea54d-e217-49b3-8c16-d13accf2e84a

▲ Return to top

Error Response

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

Error Response example (JSON)

{
  "detailedError": {
    "code": "BadRequest",
    "message": "Request validation failed.",
    "details": [
      {
        "code": "BadArgument",
        "message": "Missing required parameter: language",
        "target": "language",
        "innerError": {
          "code": "MissingRequiredParameter"
        }
      }
    ]
  }
}

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
  <detailedError>
    <code>BadRequest</code>
    <message>Request validation failed.</message>
    <details>
      <detail>
        <code>BadArgument</code>
        <message>Missing required parameter: language</message>
        <target>language</target>
        <innerError>
          <code>MissingRequiredParameter</code>
        </innerError>
      </detail>
    </details>
  </detailedError>
</response>

Error Response fields

Primary fields
Field Description
detailedError
object
Detailed information about the error.
detailedError{} object
detailedError{} object
Field Description
code
string
One of the defined error 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
Field Description
code
string
One of the defined error 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

▲ Return to top

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 code Description
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.
InvalidParameterValue The 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).
MissingRequiredParameter One 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.
ValueOutOfRange The value of one of numeric parameters is out of allowed range.

▲ Return to top

You are here