Discover

The /discover endpoint 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 ranking quality levels are provided at a global and local levels.

Use cases

The /discover endpoint provides users the ability to find with a free-form text:

  1. a known place or location, using a partial or complete name
  2. an unknown place
    1. using a category name
    2. using a chain name
    3. using a category or chain name, together with a location
    4. using a category or chain name, nearby a specific place

The free-form text is provided as the value of the q parameter.

Result items

To allow the end-user to make a decision whether or not to visit an unknown places, /discover is expected to return several choices, resulting in multiple items. The end-user will select the most appropriate.

/discover main input field is q, aimed at containing the free-form text coming from end-users. The input string can be in various and mixed scripts (Latin, Cyrillic, Arabic, Greek, ...). It is then advised to set the q parameter encoding to UTF-8, and then percent-encode it.

Special cases:

  • q values are expected to be non-empty.
  • q values only containing whitespaces, or tabs, or line feeds are valid queries and return empty results lists.

Location context and filter

To maximize the relevance of the returned items, the /discover endpoint expects a query location context, provided through any of the following:

  • a single geo-position (also named "search center"), or
  • a circle or
  • a bounding rectangle (aka bounding box, or bbox) or

Those three location contexts are mutually exclusive. Only one of them is allowed.

The circle and the bounding rectangle define both a location context (The center position) as well as a filter: All returned items will be located inside that geographical constraint.

The search center is specified in the at parameter, while the circle and country code filters are specified in the in parameter.

Similarly to in=circle and in=bbox, customers can specify a country related geographical constraint to a search center. This takes the form of a country codes list. All returned items will be located in the related countries.

The list of allowed at and in combinations is:

  • at
  • at with in=countryCode
  • in=circle
  • in=circle with in=countryCode
  • in=bbox
  • in=bbox with in=countryCode

Last but not least, /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.

More details are to be found in the API Reference.

Internationalization

Where possible, the HERE Geocoding and Search /discover endpoint attempts to present the response items in a language convenient to the end-user. For this, customers have to set the lang parameter to the desired 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.

Proximity

/discover endpoint also captures the geographical proximity in free-form texts. End-users can submit a phrase querying a category or a chain "near" or "close to" a locality or even a specific place name.

Example

For example, discovering restaurants in USA from the geo-position (42.36399,-71.05493) is formulated with:

GET https://discover.search.hereapi.com/v1/
    discover
    ?at=42.36399,-71.05493
    &limit=1
    &q=restaurant
    &in=countryCode:USA


Authorization: Bearer [your token]

More details about /discover parameters can be found in the API Reference. The response to the above request looks like below:

{
  "items": [
    {
      "title": "Casarecce Ristorante",
      "id": "here:pds:place:840drt3p-bfe137a807b449ccb3dac212fadcd5b0",
      "resultType": "place",
      "address": {
        "label": "Casarecce Ristorante, 285 Hanover St, Boston, MA 02113-1810, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "North End",
        "street": "Hanover St",
        "postalCode": "02113-1810",
        "houseNumber": "285"
      },
      "position": { "lat": 42.36363, "lng": -71.05442 },
      "access": [{ "lat": 42.36373, "lng": -71.05458 }],
      "distance": 58,
      "categories": [
        { "id": "100-1000-0001", "primary": true },
        { "id": "100-1000-0000" }
      ],
      "foodTypes": [{ "id": "304-000", "primary": true }],
      "contacts": [{ "phone": [{ "value": "+16172483839" }], "www": [{ "value": "http://casarecceboston.com" }] }]
    }
  ]
}

The response includes multiple items from the top choice to least-likely match. It delivers the following high-level elements for each result:

  • resultType - HERE Geocoding and Search /discover is able to return items of several types: place, locality, street, etc.
  • title – a representative string for the result, for instance the name of a place or a street
  • address - the detailed address of the result
  • position - a representative geo-position (WGS 84) of the result. this is to be used to display the result on a map
  • access - the geo-position of the access to the result (for instance the entrance)
  • id - the identifier of the result object. Its value can be used to retrieve the very same object through the /lookup endpoint.
  • categories - a list of category ids for place results

    New: The primary category has its flag primary set to true.

  • foodTypes - a list of food-type ids for place results preparing/serving food

    New: The primary food type has its flag primary set to true.

  • contacts - a list of contact details (phone, web, ...) for place results

  • openingHours - a list of opening hours for place results

Only title, id, resultType, position can be expected for all results.

Further examples can be found in the appendix.

results matching ""

    No results matching ""