Low Bandwidth Search (Deprecated)
Service version: 2
Last edit: 2020.07.27
Deprecation notice
May 1, 2018:
- The Low Bandwidth Search endpoint has been deprecated.
- This endpoint will be withdrawn following a 12 month deprecation period.
- The planned withdrawal date is May 1, 2019.
- Following withdrawal, requests to this endpoint may receive an HTTP 404 error in response.
On this page
Purpose
When building apps for mobile conserving bandwidth is extremely important. We have a shortened endpoint with:
- A more compressed and concise response structure to help save bandwidth.
- Add some convenience to the client side parsing.
Run this endpoint
You can easily run this and other endpoints.
- Go to the TomTom API Explorer page.
-
Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
Request data
HTTPS Method: GET
For ease of viewing and identification:
- Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
- See the following Request parameters section with the Required and Optional parameters tables for these values.
URL format (using "s" search)
https://<baseURL>/search/<versionNumber>/s/<query>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&idxSet=<idxSet>][&view=<view>]
curl command format (using "s" search)
curl 'https://<baseURL>/search/<versionNumber>/s/<query>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&idxSet=<idxSet>][&view=<view>]'
HTTPS Method: GET
URL format (using "cS" category search)
https://<baseURL>/search/<versionNumber>/cS/<category>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&idxSet=<idxSet>][&view=<view>]
curl command format (using "cS" category search)
curl 'https://<baseURL>/search/<versionNumber>/cS/<category>.<ext>?key=<Your_API_Key>[&typeahead=<typeahead>][&limit=<limit>][&ofs=<ofs>][&lat=<lat>][&lon=<lon>][&countrySet=<countrySet>][&radius=<radius>][&topLeft=<topLeft>][&btmRight=<btmRight>][&language=<language>][&idxSet=<idxSet>][&view=<view>]'
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 .
|
query/category string |
Query (s)/Category (cS) string. Must be properly URL encoded. Value: A properly URL encoded query string. |
ext string |
A valid response format. Value: JSON, JSONP, JS, or XML |
key string |
An API Key valid for the requested service. Value: Your valid API Key .
|
Optional headers | |
Header | Description |
[Accept-Encoding] string |
Enables response compression. Value: gzip |
Optional parameters | |
Parameter | Description |
[typeahead] boolean |
If the "typeahead" flag is set, the query will be interpreted as a partial input and the search will enter predictive mode. Default value: false Other value: true
|
[limit] integer |
Maximum number of responses that will be returned. Default value: 10 Maximum value: 100
|
[ofs] integer |
Starting offset of the returned results within the full result set. Default value: 0 Maximum value: 1900
|
[lat] float |
Latitude, e.g., lat=37.337 lat,lon where results should be biased.Note: supplying a lat/lon without a radius will only bias the search 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 lat,lon where results should be biased.Note: supplying a lat/lon without a radius will only bias the search results to that area. Value: min/max: -180 to +180 Reference: Latitude, Longitude and Coordinate System Grids |
[countrySet] string |
Comma separated string of country codes (e.g.: FR,ES )
FR ,ES ,etc.
|
[radius] integer |
If radius and position are set, the results will be constrained to the defined area. The radius parameter is specified in meters. Value: A radius. |
[topLeft] string |
Top left position of the bounding box.
lat ,lon .Example: 37.553,-122.453
|
[btmRight] String |
Bottom right position of the bounding box.
lat , lon .
|
[language] string |
Language in which search results should be returned.
|
[idxSet] string |
The dxSet parameter allows for fine tuning L2 by specifying which indexes to utilize for the search. The predefined indexes are:
|
[view] string |
Geopolitical View.
|
Response data
Response body
For illustrative purposes the example below 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 section for more information.
When requesting JSON output, the Response has the following structure:
{
"s": 200,
"sum": {
"q": "pizza",
"t": "NON_NEAR"
},
"r": []
}
Each element of the results
array is in the following format:
{
"id": "US/POI/p0/9033556",
"tp": "POI",
"etp": "",
"a1": "2501 Soquel Dr",
"a2": "Santa Cruz, CA 95065",
"cc": "US",
"nm": "Upper Crust Pizza & Pasta",
"ph": "+(1)-(831)-4762333",
"ul": "www.uppercrustsc.com/",
"ps": "36.98844 -121.97483",
"gh": "9q962ms9k2yx",
"ct": [
"pizza",
"restaurant"
],
"cst": [
{
"cd": "RESTAURANT",
"ns": [
{
"nl": "en-US",
"na": "pizza"
},
{
"nl": "en-US",
"na": "restaurant"
}
]
}
]
}
Response fields
The following table describes all of the fields that can appear in a Response. Fields are listed by the Response section they belong to and in the order that they appear in the Response.
Primary fields | |
---|---|
Field | Description |
s string |
Response status code. |
sum{} object |
Summary information about the search that was performed. sum{} object |
r[] array |
Result list, sorted in descending order by score. r[] array |
s |
|
Field | Description |
s integer |
Response status code. 200 denotes success. |
sum{} object |
|
Field | Description |
q string |
Query as interpreted by the search engine. |
t string |
Response type. Can be NEARBY or NON_NEAR. |
r[] array |
|
Field | Description |
id string |
Non-stable id for this result. |
tp string |
Type of Result. One of:
|
etp string |
Optional section. Only present if type = = Geography. One of:
|
a1 string |
Address line 1. |
a2 string |
Address line 2. |
cc string |
Country. |
nm string |
Name of the POI. |
ph string |
Telephone number. |
ul string |
Website URL. |
ps string |
Position. |
gh string |
Geohash. |
ct array Deprecated |
The list of POI categories. Deprecated: Use cst instead.May 1, 2018:
|
cst array |
The list of POI category classifications.cst[] array
|
cst[] array |
|
Field | Description |
cd string |
Fixed top level category code. Category Codes |
ns array |
List of category names with locale code information. Currently only the en-US locale is returned. |
ns[] array |
|
Field | Description |
nl string |
Locale code of this category name. |
na string |
Category name in given locale. |
HTTP Response codes
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:
|
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. |
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:
|
Content-Encoding |
If requested by the client, the Search service applies gzip compression to the Responses with the Accept-Encoding header. Value: gzip
|