Sorry, you need to enable JavaScript to visit this website.

Points of Interest with Reviews, Ratings and Photos

How to use the Search API to get ratings, reviews and images from Points of Interest

We have even more POIs!

Foursquare-PR-v2

As we mentioned in a previous article, we work with many global and local companies to grow the coverage of our Points of Interest, as well as their quality and reliability. Recently we partnered with Foursquare to provide an even better offer. Today I would like to go over the APIs to use and create powerful search offering in your applications. 

Today we are going to discuss the POI Details and how to get photos and extended information from POIs.

Let’s start getting information from a flower store I know in Mexico City. 

Here are the steps we’ll follow:

  • Find the POI location and Id using the Search API
  • Get the Details and Photos using the Id from the previous step

The POI Details API

We’ll start with the POI details API, for which we can find the documentation here: https://developer.tomtom.com/search-api/search-api-documentation/points-of-interest-details

It provides the following information about Points of Interest:

  1. Current Rating 
  2. Price Range
  3. 5 to 10 most relevant user reviews
  4. The Photo IDs to be used in the POI Photos API (explained later in the article)

From the documentation:

Format

https://<baseURL>/search/<versionNumber>/poiDetails.<ext>?key=<apiKey>&id=<id>

Parameters

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail. 

Parameter Description Required? Type Values
baseURL Base URL for calling the API. Yes String api.tomtom.com
versionNumber Service version number. Yes Integer 2
ext A valid response format. Yes String JSON, XML
key An API Key valid for the requested service. Yes String
Id POI details id which is previously retrieved from a Search request Yes String

As usual with the TomTom Maps APIs, the “ext” (Extension) parameter will define the format the response will be. In our case we use ‘JSON’.

Let’s take a look at the following sample.

We are going to use the Search API. In this case, we will use FuzzySearch (https://developer.tomtom.com/search-api/search-api-documentation-search/fuzzy-search) to find a single Point of Interest item as mentioned in the beginning of the article: a flower store around the center of Mexico DF. In this case I know one: “El Mercado de Flores San Angel”

This is the cUrl command we could use:

curl -X GET "https://api.tomtom.com/search/2/search/mercado%20flores%20San%20Angel.json?lat=19.42968891342941&lon=-99.093737687179&radius=20000&idxSet=POI&key=<APIKEY>" -H "accept: */*"

This command will return exact results of the flower store I named above . Let’s check the data:

{"type": "POI","id": "MX/POI/p0/3883835","score": 9.826740264892578,"dist": 13656.338024508208,"info": "search:ta:484009011809419-MX","poi": {"name": "Mercado De Flores San Ángel","categorySet": [{"id": 9361017}],"categories": ["florists","shop"],"classifications": [{"code": "SHOP","names": [{"nameLocale": "en-US","name": "florists"},{"nameLocale": "en-US","name": "shop"}]}]},

This is all great information, but we are interested in the last section of the result:

"dataSources": { 
   "poiDetails": [ 
      { 
        "id":"Rm91cnNxdWFyZTo0ZDA2N2Y4NTliN2Y2MGZjYTMzOTBiYWI=", 
        "sourceName": "Foursquare"
      } 
   ] 
}

Here we see this POI is coming from Foursquare, and so now we have the id:

Rm91cnNxdWFyZTo0ZDA2N2Y4NTliN2Y2MGZjYTMzOTBiYWI=

With this ID we can fetch the details with the ‘poiDetails’ API using the following URL:

https://api.tomtom.com/search/2/poiDetails.json?key=<API KEY>&id= Rm91cnNxdWFyZTo0ZDA2N2Y4NTliN2Y2MGZjYTMzOTBiYW=

Then we get this result:

poidetails1

Here we see current ratings of this place, some reviews about it and a list of Photo IDs we can use in order to fetch images.

We can incorporate up to ten reviews that represent the newest and the most relevant at the moment based on the Foursquare algorithms.

Next, of course we want to fetch these photos!

Fetching Images from the POI

Now with the last API call, we get a list of Photo IDs. These IDs are used in the “poiPhoto” API.

For more details and background on using “poiPhoto”, check out the documentation here: https://developer.tomtom.com/search-api/search-api-documentation/points-of-interest-photos

The table below describes the parameters that can be used in a request. Required parameters must be used or the call will fail.

Parameter Description Required? Type Values
baseURL Base URL for calling the API. Yes String api.tomtom.com
versionNumber Service verison number. Yes Integer 2
key An API key valid for the requested service. Yes String
id Photo id which is previously retrieved from a POI details service. Yes String
height

The maximum height/width of the image.

If only one of them is provided, the image will be scaled according to that dimension.

If none of them is provided, the service will return to the original size image.

If both of them are provided, service will fit, center and crop the image to fill the desired dimensions.

If values provided are bigger than the original size dimensions, the service will return the original image.

No Integer
width No Integer

Let’s get the first image by executing the following HTTP Request with this URL:

https://api.tomtom.com/search/2/poiPhoto?key=<Your_API_Key>&id=eab2d0ae-68bc-3e7f-976d-18c93b33c09a

Note that I didn’t request width or height explicitly: I want the full-size image.

poidetails2

This is a big image!

However, since this is such a large image result, now I might want to request a thumbnail version of it: Let say a 100x100 pixels:

https://api.tomtom.com/search/2/poiPhoto?key=<API_KEY>&id=eab2d0ae-68bc-3e7f-976d-18c93b33c09a&width=100&height=100

poidetails3

Now I can even use this smaller image inside a custom Marker on our map. 

poidetails5

Note: for this step, you would have to know how to customize your map markers with TomTom first. This is an easy and fun process to personalize your mapping experience – to learn more about customizing them using the TomTom SDK for Web, take look at this sample here: https://developer.tomtom.com/maps-sdk-web-js/functional-examples#examples,code,custom-markers.html

Now that we have our first one finished, let’s go ahead and get another photo. This time let’s crop it at 200 pixels in width:

https://api.tomtom.com/search/2/poiPhoto?key=<API_KEY>&id=3cb9a077-5f5e-305b-9c19-7d003d95ceaf&width=200

And, Voilà!

poidetails4

Conclusion

In this article I worked only with a flower store, but these APIs are available on all our categories: https://developer.tomtom.com/search-api/search-api-documentation-poi-categories/poi-categories

If you want to increase the appeal of the search features in your application, these two APIs will help you. If you are interested in improving your users experience in more ways, take a look at our tutorials and samples to help get you inspired and keep building.

And if you are stuck, help is only one line away in our Forum! 
https://devforum.tomtom.com/

Good luck and happy mapping!

First published: 
Wednesday, May 27, 2020 - 12:18
Last edited: 
Monday, June 1, 2020 - 18:43