Best practices

In order to geo-bias your results to the relevant area for your user, you should always use a lat./lon. pair 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 around the lat./lon.:

https://api.tomtom.com/search/2/search/pizza.json?key=<apiKey>&lat=37.8085&lon=-122.4239

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 or the given lat./lon.:

https://api.tomtom.com/search/2/search/pizza.json?key=<apiKey>&lat=37.8085&lon=-122.4239&radius=1000

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/search/2/search/pizza.json?key=<apiKey>&lat=37.8085&lon=-122.4239&idxSet=POI,PAD,Str,Xstr,Geo,Addr

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

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/search/2/search/pizza.json?key=<apiKey>&countrySet=HR  (search for pizza in Croatia only)

Supported countries

Click here for a list of all the countries supported by the Online Search engine.

We also support both json or xml formatted responses:

https://api.tomtom.com/search/2/search/pizza.xml?key=<apiKey>&lat=37.8085&lon=-122.4239  (xml response)

If you would like to page your results or build an infinite scroll view for your search results, you can page results with limit and offset:

https://api.tomtom.com/search/2/search/pizza.xml?key=<apiKey>&lat=37.8085&lon=-122.4239&limit=10&ofs=20  (results 21-30)

Finally, if you are interested in pure category search we have a special endpoint:

https://api.tomtom.com/search/2/categorySearch/important tourist monument.json?key=<apiKey>&lat=37.8085&lon=-122.4239  (category search for important tourist attractions)

Understanding the responses

In the response, the query type can either be NON_NEAR or POI_NEAR_{X} where X is the name of one of the indexes, GEO, POI, PAD etc. E.g. POI_NEAR_GEO might be "coffee near san jose ca" or POI_NEAR_POI will happen for queries like "parking near sfo". Also when using the typeAhead feature, you might see non-concrete results coming back in the special form POI_NEAR_ENTITY, in which case you present the results to the user and they select one which fires a second query to get the concrete results. This is a very UI dependent feature.

Understanding the response summary

{
    "summary": {
        "query": "TomTom",        // echo of the query
        "queryType": "NON_NEAR",  // query type (explained above)
        "queryTime": 38,          // query time on server in milliseconds
        "numResults": 10,         // total number of result in this response
        "offset": 0,              // if limit and offset are being used for paging
        "totalResults": 51,       // total number of hits within the entire database
        "fuzzyLevel": 1           // range of 2-4 indicating depth of strategies used
                                  // to find matches, e.g. 1 means more accurate and 4 means less
    },
    "results": [
        {
            "type": "POI",        // responses type (see table of types above)
            "id": 50422,        // non-stable id for this document (might change in subsequent release)
            "score": 4,       // score of this document relative to other scores in same response
            "poi": {    ...