Places (Search) API Developer's Guide

Link Object Structure

A link object is used to refer to other resources. This object contains the following attributes:

Attribute Type Description
id String; optional An identifier for the linked object.
title String; optional A localized title for the resource to which the link refers. Clients can display this title within their application.
href String (URI) The URI of the resource the link object is referring to.
type String; optional 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.
system String; optional The system name of the resource being referenced from.
accept Array[String]; optional List of accepted content media type for POST request.
method String; optional Common method of HTTP/1.1
icon String (URI); optional A link to the icon for the linked object, if one exists.
labels Object(map of String to LabelNode); optional An object containing a set of fields with translations required for the UI

Label Node

A label nodeis an object containing a set of fields with translations required for the UI. The label node contains the following attributes: This object contains the following attributes:

Attribute Type Description
label String The (localized) display name of the field
values Object(map of String to LabelNode); optional The (localized) values/options user can select from. Will be provided for fields where user should to choose one value from provided options.

Collection Link

A link to a collection. Additional information is included that can be displayed to the user to help them to decide if this is the collection they are interested in.

Attribute Type Description
title String The display name of this collection item.
href String (URI) A hyperlink that refers to the resource represented by that result item.
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.

Favourite Place Link

A link to a favourite place.

Attribute Type Description
position Array[Number] A position given by latitude and longitude, for example [37.785141,-122.4047775]
distance Number (integer); optional Distance to the destination in meters calculated as described in Search Location and Distance Calculation.
title String The (localized) display name of this item.
underlyingTitle String; optional The (localized) original display name of place item.
category Object[Link] A hyperlink to the primary category of the place.
icon String (URI) Icon associated with this item.
vicinity String (formatted text); optional The textual description of the location of the place; usually derived from the address of the place, but may also contain any other description that helps a user understand where the place is located.
type String; optional 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) A hyperlink that refers to the resource represented by that result item.
id String The unique identifier of the place.

Place Link

A link to a place. Additional information is included that can be displayed to the user to help them to decide if this is the place they are interested in. It has the following attributes:

{
  "position": [48.8582557, 2.2947905],
  "distance": 881631,
  "title": "Eiffel Tower",
  "averageRating": 5.0,
  "category": {
    "id": "landmark-attraction",
    "title": "Landmark/Attraction",
    "href": "http://...",
    "type": "urn:nlp-types:category"
  },
  "icon": "http://...",
  "vicinity": "5 avenue Anatole France\n75007 Paris\nFrance",
  "type": "urn:nlp-types:place",
  "href": "http://...",
  "id": "250u09tu-4561b8da952f4fd79c4e1998c3fcf032"
}
Attribute Type Description
position Array[Number] The latitude and longitude of the place, for example [37.785141,-122.4047775]. This latitude and longitude is suitable for displaying the place's position on a map.
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.
distance Number (integer); optional Distance to the destination in meters calculated as described in Search Location and Distance Calculation.
title String The (localized) display name of this search item.
averageRating Number; optional Deprecated. The average rating for a place; it is set to zero for all places. For locations this field is absent
category Object[Link]; optional A hyperlink to the primary category of the place.
categories Array[Link]; optional An array of link objects to categories assigned to the place. A category link object extends the standard link object with an optional icon attribute, that contains a URI string pointing to an icon appropriate for that category.
icon String (URI); optional Icon associated with this item. The icon will always be present if the 'cs' parameter is either not set or equal to 'places'.
vicinity String (formatted text); optional The textual description of the location of the place; usually derived from the address of the place, but may also contain any other description that helps a user understand where the place is located.
address Object[Address]; optional The address of the place.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

contacts Object[Contacts]; optional An object listing means of contacting the place
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

type String; optional 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) A hyperlink that refers to the resource represented by that result item.
distant Boolean; optional If true, indicates that this search result is outside the search context information.
id String The unique identifier of the place.
attribution String (formatted text); optional A ready-to-display string containing the source attribution text for this place.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

supplier Object[Link]; optional A link to metadata about the supplier of the place. The object extends the standard link object with an optional icon attribute that contains a URI string pointing to the supplier's brand icon.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

via Object[Link]; optional A link object to the external website of the supplier of the place. Where possible, this is a deeplink to a page specific to the place. As documented in Source Attribution, this link must be used for attribution when rich text attribution is not being used.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

references Object(map of String to Reference); optional A property that provides a map of 3rd party unique identifiers of the place or place's location.
weight Number; optional Number that can be used to rank places between different tiles (only for tiles request).
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

transitLines Object[TransitLines]; optional A list of available public transport transit lines.
access Array[AccessPoint]; optional List of access (navigation) points for the place.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

openingHours Object[OpeningHours]; optional A list of hours during which the place is open for business
fuelPrices Object[ExtendedAttribute]; optional Fuel price list.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

phonemes Object[PlacePhonemes]; optional Phonetic information for this place.
Note:

This is a premium feature. Contact your HERE representative or contact us through developer.here.com to request the appropriate license if this feature is not already covered by your agreement.

Reference

A third-party identifier for a place or a place's location

{
  
  "references": {
    "pvid": {
      "id": "36704368"
    }
  }

}
Attribute Type Description
id String a place or location reference.
alternatives Array[Reference]; optional alternative identifiers of the same reference.

Transit Lines Extended Attribute

Transit Lines Extended Attribute is associated with public transport stop/station and contains information about the lines and destinations:

Attribute Type Description
text String (formatted text) The information in rich text which can be displayed directly. If the text represents a list of items, the items are separated by a line break entity (if the text format is html) or newline (if the text format is plain).
label String A localized display label for that extended attribute
via Object[Link]; optional A link object to the external website of the supplier of the information. As documented in Source Attribution, this link must be used for attribution when rich text attribution is not being used.
attribution String (formatted text); optional A ready-to-display string containing the source attribution text for this place.
lines Object(map of String to TransitLine); optional Dictionary of public transport lines using this stop/station.
destinations Array[Destination]; optional Dictionary of destinations served from this stop/station.

TransitLine

Public transport line.

Attribute Type Description
name String Name
category Object[TransitLineCategory]; optional Category
style Object[TransitLineStyle]; optional Styling guidelines for the line.
operator String; optional Operator serving the line.

TransitLineCategory

Category information for the public transport line.

Attribute Type Description
id String Unique id of the category.
title String; optional Localized name of the category.
localName String; optional Locally used name for the category.
icon String; optional Icon for the category.

TransitLineStyle

Styling for the public transport line. All colors are in hex format.

Attribute Type Description
color String; optional The color value assigned to a line.
textColor String; optional The text color that should get used when the line color is used as background color.
outlineColor String; optional Color of the border around the line name.
iconShape String; optional An enum identifying the shape style of the icon.

Destination

Destination served from station/stop.

Attribute Type Description
destination String Name of the destination.
line String Name of the line serving the destination.

AccessPoint

Access point for the location. Purpose of the access point is to provide location that can be used e.g. for navigation.

Attribute Type Description
position Array[Number] The latitude and longitude of the access point, for example [37.785141,-122.4047775]
accessType String Type of access. As for now this is always road.

SideOfStreet

Opening Hours

The opening hours object contains opening hours information for a place. The following properties may be available:

Attribute Type Description
text String (formatted text) The information in rich text which can be displayed directly. If the text represents a list of items, the items are separated by a line break entity (if the text format is html) or newline (if the text format is plain).
label String A localized display label for that extended attribute
via Object[Link]; optional A link object to the external website of the supplier of the information. As documented in Source Attribution, this link must be used for attribution when rich text attribution is not being used.
attribution String (formatted text); optional A ready-to-display string containing the source attribution text for this place.
isOpen Boolean; optional Boolean flag indicating whether the place is currently open, based on place's time zone.
structured Array[StructuredOpeningHours]; optional List of structured presentations for opening hours.

Structured Opening Hours

Structure for holding opening hours based on the iCalendar specification.

This structure is defined so that it can describe more complex recurrence pattern like "Every 2nd Saturday of the month from 10am to 10pm".

Unlike the iCalendar specification, the start value in our case does not contain a date part. We omit the date part and immediately start with the T that is time section marker. For example, instead of 19700101T132000 you should expect a simpler T132000 equivalent.

Attribute Type Description
start String String with an iCalendar DATE-TIME value
duration String String with an iCalendar DURATION value
recurrence String String with a RECUR rule

Extended Attribute

Each extended attribute object has at least the following properties:

Attribute Type Description
text String (formatted text) The information in rich text which can be displayed directly. If the text represents a list of items, the items are separated by a line break entity (if the text format is html) or newline (if the text format is plain).
label String A localized display label for that extended attribute
via Object[Link]; optional A link object to the external website of the supplier of the information. As documented in Source Attribution, this link must be used for attribution when rich text attribution is not being used.
attribution String (formatted text); optional A ready-to-display string containing the source attribution text for this place.

Phonetic Place Information

A structure for holding phonetic information about the place in the NT-SAMPA format.

For each field there might be multiple phonetic transcriptions provided. If there are multiple phonetic transcriptions the ones which match the user's stated language preference best are returned first.

Note: Phonetic information is currently not available for discover/explore requests.

  {
    "title": [
      {
        "value": "pru|*\"dEn|tS@l \"sEn|t@r",
        "language": "en"
      },
      {
        "value": "pru|Den|\"tjal \"sen|ter",
        "language": "es-003"
      }
    ],
    "address": {
      "street": [
        {
          "value": "*\"bOIl|st@n \"strit",
          "language": "en"
        },
        {
          "value": "\"boils|ton \"e|se \"te",
          "language": "es-003"
        }
      ],
      "city": [
        {
          "value": "*\"bO|st@n",
          "language": "en"
        },
        {
          "value": "\"bos|ton",
          "language": "es-003"
        }
      ],
      "state": [
        {
          "value": "%m{|s@|*\"tSu|s@ts",
          "language": "en"
        },
        {
          "value": "ma|sa|\"tSu|sets",
          "language": "es-003"
        },
        {
          "value": "ma|sa|Su|\"sEts",
          "language": "fr-CA"
        }
      ]
    }
  }
    
Attribute Type Description
title Array[Phoneme]; optional Phonetic transcription of the place title. There can be multiple transcription for different languages. There can also be more than one pronunciations in a given language.
address Object[AddressPhonemes]; optional Phonetic transcriptions of the address information.

Phonetic Transcription

A phonetic transcription of a name in a particular language.

Attribute Type Description
value String The actual phonetic transcription in the NT-SAMPA format
language String[language tag] the ISO language code

Phonetic Address

A structure to hold phonetic information for an address.

Attribute Type Description
street Array[Phoneme]; optional Street name
district Array[Phoneme]; optional A division of city; typically an administrative unit within a larger city or a customary name of a city's neighborhood.
city Array[Phoneme]; optional The name of the primary locality of the place.
regions Array[Array[Phoneme]]; optional For address conventions where more than to levels of named areas above the city level are in use, the regions attribute provides an array with all additional area names, ordered by decreasing size (starting with the highest subdivision below state)
county Array[Phoneme]; optional A division of a state; typically a secondary-level administrative division of a country or equivalent.
state Array[Phoneme]; optional A division of a country; typically a first-level administrative division of a country and/or a geographical region.
country Array[Phoneme]; optional The country name.

Search Link

A link to a further search query based on the current search query. It may contain, for example, results restricted to a certain category or results for a suggested alternative search term.

This is an example of a result item representing a further search within a specified category:

{
  "title": "Sights & Museums",
  "type": "urn:nlp-types:search",
  "href": "http://...",
  "icon": "http://..."
}

This is an example of a result item representing an alternative suggestion for a search term:

{
  "title": "Hotel Adlon",
  "icon": "http://...",
  "type": "urn:nlp-types:search",
  "href": "http://.../discover/search?at=52.53044,13.41112&q=Hotel+Adlon",
  "vicinity": "Berlin<br/>Germany",
  "modified": true
}
Attribute Type Description
title String The (localized) display name of this element.
icon String (URI) The URI of an iconic representation of the item.
type String; optional 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) A hyperlink that refers to place discovery restricted by certain group (e.g. category).
categoryId String; optional A unique category identifier.
vicinity String (formatted text); optional The textual description of the location of the place; usually derived from the address of the place, but may also contain any other description that helps a user understand where the place is located.