Autocomplete
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.
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}
https://api.tomtom.com/search/2/autocomplete/pizza.json?key={Your_API_Key}&language=en-US
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 parameters | Description |
---|---|
| Base URL for calling the API.
|
| The service version. |
| Query string. |
| A valid response format. |
| An API Key valid for the requested service. |
| Language in which autocomplete results should be returned. |
Optional parameters | Description |
---|---|
| Maximum number of autocomplete results that will be returned. |
| 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. |
| 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. |
| The radius parameter must be used in conjunction with the
|
| 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. |
| 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.
|
Request headers
Note: There are no required request headers in this endpoint.
Optional headers | Description |
---|---|
Should contain a list of encodings acceptable by the client. Usually
used to demand a compressed response. | |
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 |
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:
1 "context":{2 "inputQuery":"mazda dealer Warszawa",3 "geoBias":{4 "position":{5 "lat":51.759431,6 "lon":19.4486537 },8 "radius": 100009 }10 },11 "results":[12 {13 "segments": []14 },15 ...16 ]17}
Each element of the segments
array can be one of:
1{2 "type": "brand",3 "value": "Mazda",4 "matches": {5 "inputQuery": [6 {7 "offset": 0,8 "length": 59 }10 ]11 }12}
1{2 "type": "category",3 "value": "Automotive Dealer",4 "matches": {5 "inputQuery": [6 {7 "offset": 6,8 "length": 69 }10 ]11 },12 "id": "9910",13 "matchedAlternativeName": "Dealer"14}
1{2 "type": "plaintext",3 "value": "Warszawa",4 "matches": {5 "inputQuery": [6 {7 "offset": 8,8 "length": 139 }10 ]11 }12}
When requesting XML output, the response has the following structure:
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:
1<segment type="brand">2 <value>Mazda</value>3 <matches>4 <inputQueries>5 <inputQuery length="5" offset="0"/>6 </inputQueries>7 </matches>8</segment>
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>
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 | |
---|---|
Field | Description |
| Information about the autocomplete request that was performed. |
| List of the results returned by the autocomplete engine. |
context object | |
Field | Description |
| Query passed to the autocomplete engine. |
| The geo bias passed to the autocomplete engine by setting the position (
|
geoBias object | |
Field | Description |
| Position used to bias the results by setting the optional
|
| The optional |
LatLon | |
Field | Description |
| Latitude. min/max: -90 to +90 |
| Longitude. min/max: -180 to +180 |
result object | |
Field | Description |
| Describes recognized entities of the result. |
segment object | |
Field | Description |
| The type of a detected entity. Currently we can detect: category, brand, and plaintext, but more types can appear in the future. |
| 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
|
| Defines a mapping between the |
| 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 |
| 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
|
matches object | |
Field | Description |
| 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 | |
Field | Description |
| Starting offset of the |
| Length of the matched substring. |
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 include:
|
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.
Header | Description |
---|---|
Ensures that clients implementing the CORS security model are able to
access the response from this service. | |
Indicates the format of the response, as chosen by the client.
| |
Service applies gzip compression to the responses if it is requested by
the client with the Accept-Encoding header. | |
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., |
Error response
The content type of error response depends on the requested output format (JSON or XML).
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}
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>2<response>3 <detailedError>4 BadRequest5 <message>Request validation failed.</message>6 <details>7 <detail>8 BadArgument9 <message>Missing required parameter: language</message>10 <target>language</target>11 <innerError>12 MissingRequiredParameter13 </innerError>14 </detail>15 </details>16 </detailedError>17</response>
Error response fields
Primary fields | |
---|---|
Field | Description |
| Detailed information about the error. |
detailedError object | |
Field | Description |
| One of the defined error Response codes. |
| 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. |
| Optional. Target of the particular error. |
| Optional. An array of root causes (more detailed errors) that led to
this error. |
| Optional. A higher level of details about this error. |
innerError object | |
Field | Description |
| One of the defined error response codes. |
| 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. |
| Optional. A higher level of details about this error. |
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
|
BadRequest | Top level code for requests which ended with HTTP
|
InternalServerError | Top level code for requests which ended with HTTP
|
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 |
MissingRequiredParameter | One of the required parameters was not provided. |
NotFound | Top level code for requests which ended with HTTP
|
ServiceUnavailable | Top level code for requests which ended with HTTP
|
ValueOutOfRange | The value of one of numeric parameters is out of allowed range. |