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, 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:
- Current Rating
- Price Range
- 5 to 10 most relevant user reviews
- 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:
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.
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
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 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à!
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!