Places (Search) API Developer's Guide

Search Media Type

The search media type describes a step in a user activity to find/discover places.

Media Type URI

urn:nlp-types:search

Media Type Structure

The representation provides some information about the search request, but the primary information in the search media type is a list of result items that guide users directly or indirectly to the place(s) they are looking for. This media type has the following format:

{
  "search": {
    //...
  },
  "results" : {
    "items": [
      //...
    ]
  }
}
Attribute Type Description
results Object[DiscoverResultSet] a paginateable collection of search result items.
search Object[SearchDescription] search location context that the service has chosen for the query.

Search Description

Attribute Type Description
context Object[SearchContext] search context information

Search Context Information

The primary information about the search context is the location context that the service has chosen for the query. Usually the location context is derived from the explicit location parameters of a discover activity. But sometimes the location context is also derived from other elements, particularly from a user's search term. For example, when a user located in "Berlin, Germany" uses the search term is "Restaurant in Paris", the search algorithm uses "Paris" as the search location.

When the location context of a place discovery is derived from one of the explicit location parameters, the selected one is returned in the result. Depending on the endpoint used, it may also contain an address or area of the location:

{
  "search": {
    "context": {
      "title": "Paris",
      "location": {
        "position": [52.5044, 13.3909]
        "address": {
          "city": "Paris",
          "country": "France",
          "text": "Paris<br/>France"
          //...
        }
      },
      "type": "urn:nlp-types:place"
    }
    //...
  }
}

Result items of type search contain the context used for the search, which includes the following attributes:

Attribute Type Description
title String (formatted text); optional A (short) textual representation of the item
location Object[SearchLocation] The location used for the search.
type String The type of the resource being linked to. The value is either a valid MIME media type or a URI. Places (Search) API internal links always use a URN in the namespace "nlp-types" for the type attribute. If missing, the link goes to a web resource that is best opened in a universal http client, like a web browser.
href String (URI); optional A hyperlink that refers to the resource represented by that result item.
moved Boolean; optional If true, the location used for the search is different from the one provided in the request.

Search Location

Attribute Type Description
position Array[Number] A position given by latitude and longitude, for example [37.785141,-122.4047775]
address Object[Address]; optional The neighborhood of the location used for the search.
bbox Array[Number]; optional An enclosing rectangle that describes a range of coordinates corresponding to the location of the place. Bounding boxes are typically associated with places such as cities and countries. A bounding box is specified as an array ([West longitude, South latitude, East longitude, North latitude]) according to the GeoJSON geospatial data interchange format.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.