Points of Interest with Reviews, Ratings and Photos

We have even more POIs!

As we mentioned in a previous article, we work with many global and local companies to grow the coverage of our points of interest (POI), 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. You can find the documentation here.

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

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.

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.

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's say 100x100 pixels:

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

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

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.

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à!

Conclusion

In this article I worked only with a flower store, but these APIs are available in all our categories. Check out the documentation here.

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 Developer Forum! 

To read more about the power of POI data and how to add search capabilities to your web or mobile app, check out these suggested articles:

• Understanding Places and POI APIs
• Making Geomarketing More Effective with Accurate POI Data
• Autocomplete and Suggestions with the Search API
• Building a Responsive Location Search Component with a React Search Box
• What is Fuzzy Search?
• Understanding Fuzzy Search

Lastly, here's a video tutorial to check out:

Good luck and happy mapping!