Best practices

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.

Purpose

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:

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239

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

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={Your_API_Key}&apiVersion=1&geobias=rectangle:37.8085,-122.4239,34.8085,-121.4239

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:

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239&radius=1000

Using idxSet

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

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239&idxSet=POI,PAD,Str,Xstr,Geo,Addr

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:

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={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.

https://api.tomtom.com/maps/orbis/places/search/pizza.json?key={Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239

https://api.tomtom.com/maps/orbis/places/search/pizza.xml?key={Your_API_Key}&apiVersion=1&geobias=point:37.8085,-122.4239

Using pure Category Search

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:

https://api.tomtom.com/maps/orbis/places/search/categorySearch/important 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.

1{
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        ...