Geocoding and Search API Comparison: /Discover vs. /Browse for Point of Interest (POI) Searches

Comparing /Discover and /Browse: Choosing the Right Endpoint for POI Search

In the previous blogs, we've explored the options of utilizing the /discover and /browse endpoints for searching Points of Interest (POIs) with HERE Geocoding and Search. Both endpoints offer valuable capabilities for accessing HERE's rich location data, but the question remains: which one is the better choice for your specific needs? In this blog post, we will delve into the similarities and distinctions between these two endpoints, allowing you to make an informed decision based on your unique scenario.

HERE Geocoding and Search is composed of seven services, each with its own dedicated endpoint for the production environment. These endpoints grant access to a wealth of location data, encompassing addresses, geographical coordinates, and places, aiding users in pinpointing their current location or their desired destination.

Endpoints Overview

/Discover: This endpoint empowers users to search for a known place or address, whether partial or complete, and also discover unfamiliar places.
/Autosuggest: Offers term and query suggestions as users type their search queries, complete with spell correction.
/Geocode: Returns the geographical coordinates for a specified address, but note that it may return multiple results if the query is ambiguous.
/Autocomplete: Provides auto-completion of user input, without spell correction.
/Browse: Allows users to navigate HERE Map Content through various filters.
/Lookup by ID: Finds a single result based on a unique location ID.
/Reverse Geocode: Returns the nearest address based on known geographical coordinates.

Searching for POIs

When it comes to searching for Points of Interest (POIs), you have the option to use either the /discover or /browse endpoints. Both endpoints will provide you with a list of places, complete with location information. Both are able to return items of several types: place, locality, street, etc.

For instance, here's the response showcasing a hotel near Portland, Oregon:

Copied

        {
	"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.....
    ]
}

/Discover Input Search Parameter (One-box search)

The /discover endpoint anticipates the intent behind a user's search request. Users submit a free-form text query, and the endpoint returns candidate items (places and related addresses) ranked by intent-matching relevance. It supports various scripts (Latin, Cyrillic, Arabic, Greek, etc.).

The /discover endpoint offers versatile use cases for users to locate information using free-form text input:

Finding a specific place or address by its name.
Searching based on a known geo-position.
Locating a place using a telephone number.
Exploring a particular class of place.
Identifying places by category name.
Locating chains by their name.
Combining a category or chain name with a specified location.
Searching for places with a category or chain name near a specific location.

The q parameter serves as the input for the free-form text, enabling these various search scenarios. For example, discovering hotels within 10 miles of Portland, Oregon, is formulated as follows:

Copied

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

/Browse Input Search Parameters (Multi-granular place category filter)

The /browse endpoint offers a more precise interpretation of the request and allows you to retrieve places at a specific position for a HERE Places category or HERE Places cuisine. You can use query parameters like categories and foodTypes for this purpose. Both categories and foodTypes support multiple values, separated by commas. For instance, to find fast food places serving either Indian or Pakistani cuisine in London:

Copied

        GET https://browse.search.hereapi.com/v1/
    browse
    ?at=51.51979,-0.088
    &limit=5
    &categories=100-1000-0009
    &foodTypes=202,208
    &apiKey={YOUR_API_KEY}

In additional to categories and foodTypes query filters, /browse endpoint offers a chains query filter. This feature allows you to specify any combination of HERE chain id to retrieve places associated with those particular chains. For instance, a companion app for a car manufacturer can utilize this filter, as demonstrated in the following example:

Copied

        GET https://browse.search.hereapi.com/v1/
    browse
    ?at=51.51979,-0.088
    &limit=5
    &categories=700-7850-0122&chains=299
    &apiKey={YOUR_API_KEY}

Additionally, another way to filter locations is by using a name filter. This filter is especially useful when used in conjunction with a category filter, but it can also be employed independently. For example, if a mobile application wants to display an icon representing Petrobras gas stations, it can set the category IDs to 700-7600-0000,700-7600-0116 while including a name parameter with the value "petrobras," as shown in the following example:

Copied

        GET https://browse.search.hereapi.com/v1/
    browse
    ?at=-23.000813,-43.351629
    &categories=700-7600-0000,700-7600-0116
    &limit=3&lang=en-US
    &name=petrobras
    &apiKey={YOUR_API_KEY}

There is a special use-case served by /browse is to return surrounding places, streets or localities at a given position without any names or categories filtering. For example, to get the 10 items at the a certain geoposition in Chicago, one would send:

Copied

        GET https://browse.search.hereapi.com/v1/
    browse
    ?at=41.89344,-87.62406
    &limit=10
    &apiKey={YOUR_API_KEY}

The expected result for this query would be the following including a place, a street, etc:

Copied

        {
  "items": [
    {
      "title": "N Saint Clair St, Chicago, IL 60611, United States",
      "id": "here:af:street:lCvTQTfs2eCj2xNrV9W..A",
      "resultType": "street",
      ...
    },
    {
      "title": "Inn of Chicago",
      "id": "here:pds:place:840dp3wq-b8a6b34502fe4852a5103fefd87b62ad",
      "resultType": "place",
      ...
    },
    {
      "title": "Inn Bar",
      "id": "here:pds:place:840dp3wq-5479400a4b47402492e7d47288f0a3d5",
      "resultType": "place",
      ...
    },
    {
      "title": "USPS Collection Box - Blue Box",
      "id": "here:pds:place:840dp3wq-4de5518b40d7cb88d6771dda834104d9",
      "resultType": "place",
      ...
    },
    ...
  ]
}

These filtering options provide flexibility for tailoring your search results based on specific chains or names, enhancing the precision of your location-based queries.

Geographic Filter

The search center is determined by the geo-position specified in the at query parameter, and item distances are calculated in relation to this center. You can apply filters like a circle, country code, or bounding box using in parameter. The choice of at and in combinations depend on the endpoint used.

Browse	Discover
`at` `at` with `in=countryCode` `at` with `in=circle` `at` with `in=circle` and `in=countryCode` `at` with `in=bbox` `at` with `in=bbox` and `in=countryCode`	`at` `at` with `in=countryCode` `in=circle` `in=circle` with `in=countryCode` `in=bbox` `in=bbox` with `in=countryCode`
Note: Max radius of 250km for `/browse` endpoint.

Country Filter

In addition to circle and bounding box filters, you can specify a country-related geographical constraint in both endpoints by providing a list of uppercase ISO 3166-1 alpha-3 country codes. All returned items will be located within the specified countries.

For example, discovering restaurants in USA from a geo-position is formulated with:

Copied

        GET https://discover.search.hereapi.com/v1/
    discover
    ?at=42.36346,-71.05444
    &limit=1
    &q=restaurant
    &in=countryCode:USA
    &apiKey={YOUR_API_KEY}

Searching POIs along the route

/browse, /autosuggest and /discover supports search along the route through the addition of a route parameter to the at parameter. Check Implementing Search along the route for specifics.

Sorting Result

For the /discover endpoint, results are primarily sorted by relevance, wherein /browse endpoint, results are always sorted by distance.

Language

Applications needing to enforce a preferred language in the /browse and /discover result items need to set the lang parameter to the necessary BCP 47 language code. If lang is not set, or if the result item has no translation in the requested language, the default language will be used.

Closing Thought

In conclusion, the choice between the /discover and /browse endpoints depend on your specific use case and requirements. Consider the nature of your search, the level of precision needed, and the sorting preference to make an informed decision. Each endpoint offers distinct advantages, so use the one that best suits your scenario.