Exploring Detailed POI Data with the TomTom Search API

With a little JavaScript, we’ll use the TomTom POI Details API to create a simple map web page that highlights different pizza shops around Seattle and allows users to explore each business in finer detail.

TomTom Developers
Jun 15 · 12 min read

TomTom Search API v6 helps developers access Detailed Points of Interest (POI) information. Examples include a store’s ratings and reviews, opening hours, and photos. This adds value to map-based applications, enhancing user experience with detailed information about each POI.

This article uses TomTom POI Details API to create a simple map web page that highlights different pizza shops around Seattle and allows users to explore each business in finer detail. To follow this tutorial, you just need to know some JavaScript.


The regular search API already returns basic information and points of interest. This information includes business name, contact information (like address and phone number), and POI category type. It also contains a POI Details ID we can use to request additional details. You can find it in the dataSources object nested inside each search API result, like so:

The detailed data adds more specific information, if it is available available. Examples include photos, price range, social media links, popular hours for each day of the week, and even text reviews.

For example, here is sample detail data in JSON format of one of my favorite pizza places in Seattle:

Pretty nice, right? Most of the data inside the JSON object should be self-explanatory, but you might notice the photos section contains a collection of IDs instead of URLs.

You can use these IDs with TomTom Points of Interest Photos API to retrieve the image at a specified width and height. When using this API, be sure to follow the Terms and Conditions. This includes attributing results from Details API and Photos API as “powered by Foursquare.” Also, do not cache results longer than 30 days.


Now, see how to use Points of Interest Details API to get the detailed data using JavaScript.

First, collect a TomTom API key to use the APIs. It is quick and free to register for the TomTom Developer Portal. TomTom automatically generates the first key.

The next step is to set up the webpage with TomTom Maps SDK for Web so points of interest can be searched in detail. Create a new webpage and include the TomTom SDK files in the header. The Maps JS Library, its CSS stylesheet, and the Services JS Library are used below.

Next, get some points of interest locations. Choose from various options to search and retrieve POI locations from TomTom, such as Fuzzy Search, Category Search, and Nearby Search. Use TomTom Maps POI Search API and center it around a latitude and longitude coordinate to get results within a default distance radius.

POI Search API supports numerous options to help narrow results, including types of businesses or locations. This example uses the query field with the center option to seek any points of interest that match the search phrase near a location. We will try searching for pizza near Seattle.

Using the SDK, pass the API key along with query text “pizza” and the longitude and latitude location coordinate for Seattle (-122.33, 47.60) to the tt.services.poiSearch service:

The returned data should look similar to the following:

Some results include a dataSource field indicating they have additional POI detail. Retrieve these details from TomTom by referencing the ID value using Points of Interest Details API. As a test, the first POI result’s detailed information is recieved by passing the API key and the POI Data Source ID value using TomTom SDK for Web:

That is all it takes to access a whole new level of detail in an app’s location data. But, this is not done yet.

Now that we are set up to retrieve detailed information for points of interest, let’s combine that with TomTom Map Display API to create an interactive map of pizza shops around the area.


To complete the app, add some user interface (UI) elements to the code: a map display and details section.

Adding a Map Display

Start by adding the following CSS code inside a <style> tag in your web page header. This sizes the two UI elements appropriately and ensures the details section sticks to the left side:

Next, add these two <div> elements inside the UI page body:

Keep the API key, location coordinate, and search query as global variables at the top. (Note that in a production release application, keep the API key more secure than placing it directly inside the web page).

Then initialize the map display and add a few controls:

At this point, when you open the webpage in a browser, you should see an interactive map centered on Seattle on the right half of the page, and space for detailed information on the left half of the page.

Adding POI Search Results

Next, add markers for our POI search results into the map, and enable users to click them to dynamically load and view the POI’s detailed information.

Create a helper function named createMarker to place a custom-colored marker on the map display at the specific location with a pop-up for the location name. It should assign and call the onclick event handler if it is passed in as a parameter:

Then, create a second helper function named displayDetails. This uses the basic POI data and detailed data to populate our details section, which is an information panel on the left half of the page. Also, ensure the text “Results powered by Foursquare” display at the bottom per API terms and conditions.

Finally, iterate through the search results. Place a marker on the map for each result, and have it load and display the detailed information inside the click event handler:

With everything in place, click on pizza shops on the map to see photos, ratings and reviews, price range, and more.

Here is the full project code, for reference:


With just a little bit of code, TomTom Maps SDK for Web, and the Points of Interest Details API, we created a fully explorable pizza map within a web page. Visitors can view useful information on each pizza restaurant. Now we can look for a place to eat dinner tonight!

Fun ideas to try with this code include:

  • Change the location to a different city or enable city selection in the app
  • Create a different POI search map by changing the query to “ice cream” or “coffee”
  • Add custom icons to the markers to indicate the type of shop
  • Add an HTML element overlay to directly embed the detailed information inside the pop-up

TomTom’s iOS SDK and Android SDK help build this functionality into mobile apps as well. To learn more about TomTom Map APIs, check out the documentation and tutorials. Also, the online documentation and examples are great resources that show what else TomTom SDK for Web can do.

This article was originally published at https://developer.tomtom.com/blog.

Geek Culture

Proud to geek out. Follow to join our 1M monthly readers.