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 precise place or address
   1. using its name
   2. using its geo-position
   3. using a telephone number
2. a class of 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.

One-box search

/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

geometrical context

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.

country filter

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 list of upper-case ISO 3166-1 alpha-3 country codes. All returned items will be located in the related countries. Note that

Additionally to the ISO codes HERE Geocoding and Search supports the country group XEA, equivalent to the list of country codes AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE

Allowed combinations

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.36346,-71.05444) is formulated with:

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

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

{
  "items": [
    {
      "title": "Salumeria Italiana",
      "id": "here:pds:place:840drt3p-898f6ee434794fe59895e71ccf9381e1",
      "ontologyId": "here:cm:ontology:restaurant",
      "resultType": "place",
      "address": {
        "label": "Salumeria Italiana, 151 Richmond St, Boston, MA 02109, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "MA",
        "state": "Massachusetts",
        "county": "Suffolk",
        "city": "Boston",
        "district": "North End",
        "street": "Richmond St",
        "postalCode": "02109",
        "houseNumber": "151"
      },
      "position": { "lat": 42.36355, "lng": -71.05439 },
      "access": [{ "lat": 42.3635, "lng": -71.05448 }],
      "distance": 11,
      "categories": [
        { "id": "600-6300-0066", "name": "Grocery", "primary": true },
        { "id": "100-1000-0000", "name": "Restaurant" },
        { "id": "100-1000-0006", "name": "Deli" },
        { "id": "600-6300-0067", "name": "Specialty Food Store" }
      ],
      "references": [
        { "supplier": { "id": "core" }, "id": "31213861" },
        { "supplier": { "id": "tripadvisor" }, "id": "3172680" },
        { "supplier": { "id": "yelp" }, "id": "JNx0DlfndRurT-8KhSym7g" },
        { "supplier": { "id": "yelp" }, "id": "P44VNcZUUNZfiFy-c4SUJw" }
      ],
      "foodTypes": [
        { "id": "304-000", "name": "Italian", "primary": true },
        { "id": "800-057", "name": "Pizza" },
        { "id": "800-060", "name": "Sandwich" }
      ],
      "contacts": [
        {
          "phone": [{ "value": "+16175234946" }, { "value": "+16175238743" }, { "value": "+16177204243" }],
          "fax": [{ "value": "+16175234946" }],
          "www": [
            { "value": "http://www.salumeriaitaliana.com" }
          ],
          "email": [{ "value": "contact@salumeriaitaliana.com" }]
        }
      ],
      "openingHours": [
        {
          "text": ["Mon-Sat: 08:00 - 17:00", "Sun: 10:00 - 16:00"],
          "isOpen": false,
          "structured": [
            { "start": "T080000", "duration": "PT11H00M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA" },
            { "start": "T100000", "duration": "PT06H00M", "recurrence": "FREQ:DAILY;BYDAY:SU" }
          ]
        }
      ]
    }
  ]
}

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
• foodTypes - a list of food-type ids for place results preparing/serving food
• contacts - a list of contact details (phone, web, ...) for place results
• openingHours - a list of opening hours for place results

Additionally, Discover returns when available the following metadata response elements for place results:

• chains - place chains metadata to allow customers to choose a chain icon

• references - Data source ids, when the place result has a contribution from specific suppliers:

  • yelp, tripadvisor for Yelp and Tripadvisor
  • core for HERE Map Data products with Core POI content (RDF, GDF, NAVSTREETS, File Geodatabase, POI XML)

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

Further examples can be found in the appendix.