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": { ...