Best practices

Public Preview Notice

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:

1
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:

1
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:

1
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:

1
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,EPP

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)
• EPP = Extended Postal Codes (for the most accurate postal code search experience, especially relevant for countries like the UK and Ireland. If EPP is not used (by default), detailed postal code queries will be matched to Street results.)

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:

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

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

1
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:

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