Places (Search) API Developer's Guide

Place Media Type

A place response, identified by media type URI urn:nlp-types:place, contains all the information available for a single place.

The place representation is extensible, with attributes divided into four sections:
Base attributes
A set of predefined attributes providing core information about a place like name, location, and categories.
Extended attributes
An extensible collection of additional facts about the place
Media collections
A set of rich media types aggregated from multiple sources
Related places
References to other places related to the given place
Base attributes are members of the place object itself, while extended attributes, media collections and related places are each grouped under their own subobject:
{
  "name": "Rockefeller Center",
  //... other base attributes

  "extended": {
    //... extended attributes
  },

  "media": {
    //... media collections
  },

  "related": {
    //... related places
  }
}

Base Attributes

Base place attributes are members of the place object that provide core information about a place.

Attribute Type Description
name String The name of the place. If a user's preferred language is English and the place has an alternative name in English, the English name would be returned as the place name and the original name would be present in the alternativeNames attribute.
placeId String The unique identifier of the place.
view String (URI) A URI linking to a representation of the place that can be viewed by end users. Applications must provide at least a link for every place that is fetched.
Note: The link in the place.view attribute can be used to enable users to share a place with their friends. For more information on this feature, please see Place Sharing
alternativeNames Array[AlternativeName]; optional Original names of a place, including possibly those in other languages.
location Object[Location] A description of the physical location of a place.
attribution String (formatted text); optional A ready-to-display string containing the source attribution text for this place.
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.
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.
references Object(map of String to Reference); optional A map from third-party names to the unique identifier that the third party uses for this place.
contacts Object[Contacts] An object listing means of contacting 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) A URI linking to a representation of the place that can be viewed by end users. Applications must provide for every place they fetch at least a link.
ratings Object[Ratings]; optional

An object summarizing the user ratings for a place. Deprecated. Replaced by Rating Media Type in media collections

report Object[Link]; optional A link for getting options for reporting a place because, for example, it contains inappropriate content or place does not exists. The response will have the report-options media type.

Additional Place Information

Attribute Type Description
extended Object[ExtendedAttributes]; optional An object that provides further information about a place
related Object[Related] An object that contains related places in which users may also be interested.
media Object[Media] An object containing collections of media (images, reviews, etc.) relating to the place.
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.

Alternative Name

Each alternative name is an object providing the alternative name as well as information on the language of that name.

Attribute Type Description
name String the alternative name
language String[language tag] the ISO language code

Location

A location object contains attributes to describe the physical location of a place.

Attribute Type Description
position Array[Number] A position given by latitude and longitude, for example [37.785141,-122.4047775]
locationId String; optional A unique identifier of the location when assigned.
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.
access Array[AccessPoint]; optional Coordinates to access the location.

Ratings

A summary of how users rated a place.

Attribute Type Description
average Number The average rating of the place across all users.
count Number (integer) The number of individual votes on the place.

Extended Attributes

If a place has no information for a given attribute, the attribute is not present. If there is no extended content at all for a place, the extended attribute of the place is not present.

In the future, more properties may be added to the extended section. Clients can safely loop over all properties in this section and use the label and text properties to display all available information in this section to the user. When an attribute represents a list of options, the text field separates the elements with newlines.

The currently available extended properties may include third-party content as described in media collections.

Some extended attributes may provide a structured presentation in addition to the label/text representation (e.g. transitLines). They will be documented separately.

Attribute Type Description
payment Object[ExtendedAttribute]; optional A list of available payment methods (such as cash, credit card, direct debit, etc.)
openingHours Object[OpeningHours]; optional A list of hours during which the place is open for business.
annualClosings Object[ExtendedAttribute]; optional A description of annual closing dates such as holidays or other special occasions.
price Object[ExtendedAttribute]; optional A price list.
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.

nearestLandmark Object[ExtendedAttribute]; optional A description of the nearest landmark.
languagesSpoken Object[ExtendedAttribute]; optional A list of the languages that are spoken at the place.
availableParking Object[ExtendedAttribute]; optional A list of parking options available nearby.
smoking Object[ExtendedAttribute]; optional Whether smoking is allowed.
disabledAccess Object[ExtendedAttribute]; optional Whether disabled access is available.
transitLines Object[TransitLines]; optional A list of available public transport transit lines.
departures Object[Departures]; optional A list of next departures for available public transport transit lines.
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.

blindGuide Object[ExtendedAttribute]; optional Whether a public transport stop has blind guides ('tactile paving').
disabledParkingSpaces Object[ExtendedAttribute]; optional Whether disabled parking is available.
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.

womenParkingSpaces Object[ExtendedAttribute]; optional Whether women parking is available.
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.

restRoomAvailable Object[ExtendedAttribute]; optional Whether rest room is available in parking 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.

secureParking Object[ExtendedAttribute]; optional Whether parking is secured, indicates a gated and CCTV parking.
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.

securityManned Object[ExtendedAttribute]; optional Whether security guard is available in parking 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.

electricalChargingPoints Object[ExtendedAttribute]; optional Whether electric charging point is available in parking 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.

elevator Object[ExtendedAttribute]; optional Whether a place has an elevator.
escalator Object[ExtendedAttribute]; optional Whether a place has an escalator.

Departures Extended Attribute

Departures Extended Attribute is associated with public transport stop/station and contains information about scheduled departures from the place:

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.
schedule Object[Schedule]; optional List of next public transport departures.

Schedule

Information about the departures of public transport stop/station. Departure items are paginated based on page size parameter.

Attribute Type Description
next String (URI); optional Link to the next set of departures, if available.
items Array[Departure] List of departures.
lines Object(map of String to TransitLine); optional Dictionary of lines serving departures shown in current departure item list using line name as a key.
operators Object(map of String to PTOperator); optional Dictionary of public transport operators operating on this stop/station using operator ID as a key.

Departure

Information about single departure. All times use RFC 3339 date-time format with timezone offset

Attribute Type Description
line String Reference to the line in lines dictionary.
scheduled Object[DepartureTime] Originally scheduled departure time.
direction String; optional Direction of the departure on its line.
exception String; optional An indicator for some exceptional event happened to this departure. Possible values are redirected, replaced, cancelled and additional.
operator String; optional A reference to the operator in the operators dictionary.
real Object[DepartureTime]; optional A real time information about departure time.
extended Array[ExtendedAttribute]; optional A dictionary describing additional features of the departure. Supported keys are bikeAllowed and barrierFree.

DepartureTime

Information about departure time.

Attribute Type Description
platform String; optional Platform for the departure.

PTOperator

Public transport operator.

Attribute Type Description
id String Id.
title String; optional Name of the operator
supplier Object[OperatorSupplier]; optional Supplier of the operator's schedule information
links Object(map of String to OperatorLink); optional Dictionary of additional links to be display next to departure information of the operator. Possible keys are operator, agency and tariff.

OperatorSupplier

Supplier of the public transport operator's schedule.

Attribute Type Description
title String Name

OperatorLink

Additional link associated with operator.

Attribute Type Description
text String (formatted text) Text for the link.
url Object[Link] URI of the link.

Related Places

The related object contains related places in which users may also be interested. The following properties may be available:

Attribute Type Description
recommended Object[Link]; optional A link list of recommended places for the given place which shares the same structure as the search results.
public-transport Object[Link]; optional A link list of nearby public transports for the given place which shares the same structure as the search results.
venue Object[PlaceLink]; optional Venue where place resides
stops Object[Link]; optional A link list of public transport connections in the given place which shares the same structure as the search results.

Media Object Structure

A Media Object Structure contains third-party content collections. This object contains the following attributes:

Attribute Type Description
images Object[MediaCollection] collection of images of a place
editorials Object[MediaCollection]; optional collection of editorial description about a place
reviews Object[MediaCollection] collection of reviews about a place
links Object[MediaCollection]; optional collection of links for interactions with a place
ratings Object[MediaCollection] collection of rating summaries from suppliers

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.