Understanding Places and POI APIs 📍

Places give value to maps. This article goes over places and points of interest, or POIs, and how developers can integrate them into their web and mobile apps. Happy reading!

Understanding Places and Points of Interest (POIs)

Places give value to maps. We want to know what interesting places are near us, where those places are located, and how we can best travel to them. These are the primary reasons maps have become so useful to us, pretty much since maps have been available. And today, from searching for a restaurant for dinner, to routing a road trip to a new city, to finding a hotel to stay in, interacting with location information has become ubiquitous.

In the mapping world, we call these locations or places “points of interest” (POI), and they can take the form of addresses, landmarks, or even simply arbitrary markers. But exactly how can you access POI data and turn it into a smooth user experience for your app?

In this article, we’ll help you navigate POIs from a developer’s perspective and examine the various ways you can integrate them for your users, as well as point you to the different tools and technologies TomTom offers to power your apps with an extensive, global, and consistent POI database for easily finding and displaying places.

What is a POI?

A point of interest is a specific location that someone may find useful or noteworthy. Broad definition, huh? Yup. It’s basically a way to mark and classify geographic locations that have some significance. They might be homes, businesses, buildings, cities, or even just one big tree inside a park. Some common examples of POIs on maps include railway stations, airports, restaurants, and hotels.

What makes POIs important in an app is that they’re the fundamental elements end users interact with when it comes to locations. POIs are often what the end-user knows rather than an exact address or coordinates.

For example, you might know the name and even the general location of your favorite ice cream place or restaurant, but probably can't provide an address from memory. Same for hotels: when looking for directions to a hotel, you rarely enter the address into the search box of whatever app you're using. Typically, we start with the hotel name.

When searching for POIs, users can search for them in a list, see them on a map as icons, and route paths between them. Being able to give your users the most relevant, important, and up-to-date places can be absolutely critical to an app that works with location datasets, and that’s where TomTom APIs can help you succeed. We work with many global and local companies to continually grow our POI coverage, breadth, depth and data quality. TomTom has recently integrated millions of new POIs from Foursquare – a global POI data partner of TomTom – to provide our users with an even better location technology service.

How are Developers Using POI Data?

With access to POI data, developers have enabled people to sift through and manage location information around the world faster and better than ever before. Finding landmarks, discovering nearby pizza restaurants, navigating traffic routes, or even taking a walking tour of a city can now happen immediately in real-time using a mobile app.

Integrating points of interest seamlessly into location-based applications changes how people interact with real-world places and are a crucial part of many mapping and location apps. Having quick access to accurate POI data and being able to work with it easily is tremendously powerful for your users.

With regard to POI data, keep in mind that it’s not just about having place names and locations; the depth of information an app offers matters, too. Where are the entrances to the museum? What are the days and hours of operation? Information that can answer key context questions like these allows apps to provide real value to users and can make or break the experience.

The good news is that by connecting to TomTom APIs, you can easily offer this deep level of information to your users. Not only is it easy to use TomTom APIs, but with a TomTom POI database that includes nearly 100 million points of interest in over 180 countries and territories, labeled with hundreds of POI categories, you also have comprehensive data to offer users. TomTom Enterprise customers can also get POIs in a dataset format, enabling an even broader set of use cases.

With a connection to a reliable and vast POI database, you can enable very specific search results for your users to display only the relevant places by using POI categories with as much or as little granularity as you need. For instance, you could add a family dinner suggestions map that would show restaurants in an area, but not fast food. When you’re using TomTom APIs coupled with an extensive database of millions of POIs, the possibilities are endless.

How to Plot POI Locations on a Map

Let’s take a look at how you can work with POI data in just a single HTTP call.

The simplest way to start leveraging TomTom data is with the Fuzzy Search API to find places and basic information, such as place names, addresses, and POI locations. It’s as easy as making an HTTP web request with parameters passed in via a query string, along with your TomTom API key. You can even just put the link into your web browser to test it.

The URI takes the form of

/search/{versionNumber}/search/{query}.{ext}

and the current version is 2. So, for example, if you wanted to get a list of cafés within a 1km radius in Paris, France returned in JSON format, it would look like:

https://api.tomtom.com/search/2/search/coffee.json?countrySet=FR&lat=48.85&lon=2.34&radius=1000&idxSet=POI&categorySet=7315&key=YOUR_API_KEY

Let’s take a moment to break down the query string parameters in the link:

• countrySet is a comma-separated list of country codes to specify which countries to search within. In this example, FR indicates France.
• lat and lon represent the latitude and longitude coordinates to focus the search. The coordinates for Paris are 48.85, 2.34.
• radius is the radius area of the search specified in meters, in our case 1km.
• idxSet is a comma-separated list of indexes for the search. For this search, we only listed the POI index.
• categorySet specifies comma-separated list of categories for POI searches. 7315 is the “restaurant” category. There are hundreds of categories you can specify. To get the complete list, you can call the POI Categories API endpoint /search/{versionNumber}/poiCategories.{ext} or use the API Explorer.
• key is your TomTom Developer API key. If you don’t have an API key, you can get one for free by signing into the TomTom Developer Dashboard.

The JSON formatted date returned in the response will give you a lot of information for each returned POI, including name, phone, address, distance, categories, and more if available in the database, and will look a bit like this:

{ 
    "summary":{ 
        "query":"coffee", 
        "queryType":"NON_NEAR", 
        "queryTime":65, 
        "numResults":10, 
        "offset":0, 
        "totalResults":15, 
        "fuzzyLevel":1, 
        "geoBias":{ 
            "lat":48.85, 
            "lon":2.34 
        } 
    }, 
    "results":[ 
        { 
            "type":"POI", 
            "id":"FR/POI/p0/2112353", 
            "score":2.404910087585449, 
            "dist":497.0501740330584, 
            "info":"search:ta:250009036855126-FR", 
            "poi":{ 
                "name":"Coffee Parisien", 
                "phone":"+(33)-(1)-43541818", 
                "categorySet":[ 
                    { 
                        "id":7315069 
                    } 
                ], 
                "url":"www.coffee-parisien.fr", 
                "categories":[ 
                    "hamburgers", 
                    "restaurant" 
                ], 
                "classifications":[ 
                    { 
                        "code":"RESTAURANT", 
                        "names":[ 
                            { 
                                "nameLocale":"en-US", 
                                "name":"restaurant" 
                            }, 
                            { 
                                "nameLocale":"en-US", 
                                "name":"hamburgers" 
                            } 
                        ] 
                    } 
                ] 
            }, 
            "address":{ 
                "streetNumber":"4", 
                "streetName":"Rue Princesse", 
                "municipalitySubdivision":"6ème Arrondissement", 
                "municipality":"Paris", 
                "countrySecondarySubdivision":"Paris", 
                "countrySubdivision":"Île-de-France", 
                "postalCode":"75006", 
                "countryCode":"FR", 
                "country":"France", 
                "countryCodeISO3":"FRA", 
                "freeformAddress":"4 Rue Princesse, Paris, 75006", 
                "localName":"Paris" 
            }, 
            "position":{ 
                "lat":48.85254, 
                "lon":2.33441 
            }, 
            "viewport":{ 
                "topLeftPoint":{ 
                    "lat":48.85344, 
                    "lon":2.33304 
                }, 
                "btmRightPoint":{ 
                    "lat":48.85164, 
                    "lon":2.33578 
                } 
            }, 
            "entryPoints":[ 
                { 
                    "type":"main", 
                    "position":{ 
                        "lat":48.85255, 
                        "lon":2.33445 
                    } 
                } 
            ] 
        }, 
        ... 
    ] 
}

Integrating this kind of detailed POI information into your app, combined with other TomTom services, lets you provide your users with nearby searches, routes, travel times, traffic, and much more. And while the above Fuzzy Search shows just a simple example, there are many other parameters available to further customize and narrow a search. For a full list of options, check the Search API Explorer for Fuzzy Search.

Next Steps

We just saw how, with a single web request to the Fuzzy Search endpoint of the TomTom Search API, you can put a powerful location search through millions of POIs into the hands of your users. Imagine what might be possible with just a bit more data. Why don’t you try adding POI data to your app now?

Some great places to start developing with POIs in your app are the functional samples for Search and Geocoding and Customizing Markers.

To learn more about using POIs with TomTom APIs, we recommend you check out these resources:

• The Search API and Extended Search API, to get started with location search, filtering options, and looking at response data, as well as Best Practices to help improve your API query results.
• The Map Display API, to get a POI map of any location for your web and mobile apps.
• The TomTom Maps SDKs for Web, iOS, and Android, which provide easy access to these and other TomTom services.

To help you get even more out of our TomTom APIs, we also provide extensive tutorials, functional examples and detailed documentation.

For background details on POIs and TomTom location services, see the blog posts How to Use POI Data to Power Your Location-Based Application and Where to Open a Chinese Restaurant in Amsterdam using TomTom Maps APIs.

And lastly, for any questions or feedback, we encourage you to reach out to us in the TomTom developer forum.

Good luck and happy coding!

This article was first published at https://developer.tomtom.com/blog. The original author is Olivia Vahsen.