Best practices

Service version: 1
Last edit: 2024.05.31
TomTom Orbis Maps

Public Preview Notice

Important notes:

  • This TomTom Orbis Maps Search API document collection is in Public Preview. Go to the Public Preview - what is it? page to see what this means.
  • This API is powered by TomTom Orbis Maps.
  • See the TomTom Orbis Maps documentation for more information.


The following topics provide some helpful tips to improve your Search API query results.

Note: Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Using geobias

In order to geo-bias your results to the relevant area for your user, you should always use a geobias parameter to help bias the results to the user's location. Note, this is a non-restrictive bias, but for very common searches it will find the instances nearby.

This query will find places with pizza biased to the point lat,lon:


This query will find places with pizza biased to the rectangle topLeftLat,topLeftLon,btmRightLat,btmRightLon:


Using radius

If geo-biasing is not strong enough for keeping your results local to the user, you can also pass in a radius (in meters) to restrict the result to a given area. For instance, this query will only find pizza within 1000 meters of the given point lat/lon:


Using idxSet

You can also specify the exact set of indexes to query in the idxSet parameter. For instance if you are only interested:


The idxSet parameter value set of indexes that can be used are:

  • POI = Points of interest
  • PAD = Point Addresses
  • Str = Streets
  • Geo = Geographies
  • Xstr = Cross Streets (intersections)
  • Addr = Address range interpolation (when there is no PAD)

Note: If you are using more than one index, do not include any spaces between them in the comma-separated string.

Using a subset of countries

You can also specify a subset of the countries on the server by adding a comma-separated list of countries in the form:

Subset of countries{Your_API_Key}&apiVersion=1&countrySet=HR,CY,CZ,DK

(search for pizza in Croatia, Cyprus, Czech Republic, and Denmark) See the TomTom Search API Market Coverage page for a list of all the countries supported by the Search API engine.

Using different response formats

We also support JSON or XML formatted responses.

Request example with a JSON response format{Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239
Request example with an XML response format{Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239

Finally, if you are interested in pure category search we have a special endpoint: Category Search. The following query will produce a category search for important tourist attractions:

Category Search tourist monument.json?key={Your_API_Key}&geobias=point:37.8085,-122.4239

Understanding a response summary

The following example uses JSON. Note: For your benefit, the code comments are preceded by // and are not part of the actual JSON.

JSON Response
2 "summary": {
3 "query": "TomTom", // echo of the query
4 "queryTime": 38, // query time on server in milliseconds
5 "numResults": 10, // total number of result in this response
6 "totalResults": 51, // total number of hits within the entire database
7 // to find matches, e.g. 1 means more accurate and 4 means less
8 },
9 "results": [
10 {
11 "type": "POI", // responses type (see table of types above)
12 "id": 50422, // non-stable id for this document (might change in subsequent release)
13 "score": 4, // score of this document relative to other scores in same response
14 "poi": {
15 ...