/discover POIs with HERE Geocoding & Search API

In our previous blog, using ChatGPT, we experimented with the /discover endpoint of the Geocoding and Search API to show hotels within 10 miles of Portland, Oregon. In this blog post, we will discuss how to search for Point-of-Interest (POI) using the /discover endpoint of the Geocoding and Search API. We will use the example to show hotels near Portland and other major cities as an example in a web mapping application using HERE Maps API for JavaScript. 

One of the cool things you can do with the Geocoding and Search API is the ability to search for POIs in a specific area such as hotels, restaurants, or parks. You can retrieve locations, addresses, and global POIs with more than 400 categories and address objects at different levels (house number, street, city, state, and postal code). You can do this using the /discover endpoint of the Geocoding and Search API. See this documentation page to learn more about other endpoints. 

Discover endpoint

/discover is one of the endpoints that simplifies searching for places. The user submits a free-form text request that returns candidate items (places and addresses related) in the order of intent matching relevance. The free-form text is provided as the value of the q parameter. /discover main input field is q, aimed at containing the free-form text coming from end-users. Detailed information regarding the /discover endpoint can be found in this guide. 

For example, discovering hotels within 10 miles of Portland, Oregon (45.52, -122.68) is formulated with:

        GET https://discover.search.hereapi.com/v1/
    discover
    ?at=45.52,-122.68 
    &radius=16000
    &q=hotel
    &apiKey={YOUR_API_KEY}


  

More details on other supported parameters can be found in the API Reference. 

POI search

Geocoding and Search API provide customers with a flexible way to retrieve relevant results for textual queries. There are currently 9 values in this resultType , which is an enum of: place, locality, street, houseNumber, administrativeArea, addressBlock, intersection, postalCodePoint, chainQuery, categoryQuery. Detailed information regarding resultType can be found in this guide. 

A POI can be identified through the place value of the resultType response element. A place result represents a POI: A point feature with a name, a position, an address, and a list of categories defining the functionality characterizing the point. A place can be a hotel, an EV charging station, an airport, a stadium, etc. The subtype field categories contains a list of IDs referencing the different functionality of the location.

For example, the response to the above request discovering hotels within 10 miles of Portland, Oregon (45.52,-122.68) looks like below:

        {
	"items": [{
		"title": "Provenance Hotels",
		"id": "here:pds:place:840c20fb-d21e890f05a2a4fe044611ff80d92d35",
		"language": "en",
		"ontologyId": "here:cm:ontology:hotel",
		"resultType": "place",
		"address": {
			"label": "Provenance Hotels, 808 SW Alder St, Portland, OR 97205-3133, United States",
			"countryCode": "USA",
			"countryName": "United States",
			"stateCode": "OR",
			"state": "Oregon",
			"county": "Multnomah",
			"city": "Portland",
			"district": "Downtown",
			"street": "SW Alder St",
			"postalCode": "97205-3133",
			"houseNumber": "808"
		},
		"position": {
			"lat": 45.52011,
			"lng": -122.68051
		},
		"access": [{
			"lat": 45.52031,
			"lng": -122.68043
		}],
		"distance": 42,
		"categories": [{
			"id": "500-5000-0053",
			"name": "Hotel",
			"primary": true
		}, {
			"id": "500-5000-0000",
			"name": "Hotel/Motel"
		}],
		"references": [],
		"contacts": [{
			"phone": [{
				"value": "+15032221515"
			}, {
				"value": "+15035482559",
				"categories": [{
					"id": "500-5000-0053"
				}]
			}],
			"fax": [{
				"value": "+15038024257"
			}],
			"www": [{
				"value": "http://www.provenancehotels.com",
				"categories": [{
					"id": "500-5000-0053"
				}]
			}, {
				"value": "https://www.provenancehotels.com"
			}, {
				"value": "https://www.provenancehotels.com/offers"
			}],
			"email": [{
				"value": "info@provenancehotels.com"
			}]
		}],
		"openingHours": [{
			"text": ["Mon-Sun: 00:00 - 24:00"],
			"isOpen": true,
			"structured": [{
				"start": "T000000",
				"duration": "PT24H00M",
				"recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA,SU"
			}]
		}]
	},
    // more hotels.....
    ]
}
  

Visualization

For the purpose of visualizing the above request and response, we modified one of the samples from HERE Maps API for JavaScript to display 100 hotels within 10 miles of several major cities in an interactive map together with the JSON response for the endpoint. 

Below is the main modification to the code using H.service.GeocodingService service to call the /discover endpoint of Geocoding and Search API:

        function discoveryGeocode(platform) {
  var geocoder = platform.getSearchService(),
      discoveryParameters = {
        q: 'hotel',
        at: '45.52,-122.68',
        limit: 100,
        radius: 16000
      };

  geocoder.discover(
    discoveryParameters,
    onSuccess,
    onError
  );
}
  

The source code for this sample application can be found in our HERE GitHub repo. 

Conclusion

HERE Geocoding and Search API is a very powerful tool and searching for POIs is pretty easy and straightforward. The free-form text input to the q parameter in the /discover endpoint simplifies searching for places. And POIs can be easily identified through the place enum value of the resultType response element.

Resources

• HERE Geocoding and Search API - Developer Guide
• HERE Geocoding and Search API - Endpoints Overview
• HERE Geocoding and Search API - Discover Endpoint
• HERE Geocoding and Search API - API Reference 
• HERE Geocoding and Search API - Result types
• HERE Maps API for JavaScript - Search for a Landmark sample
• HERE Maps API for JavaScript - API Reference - H.service.GeocodingService
• HERE Github - DevRel Sample - Discover POI sample source code