Places (Search) API Developer's Guide

Representation Modifiers

Places (Search) API media types allows client applications to adjust the presentation of the returned response to suit their needs.

Applications can activate the various tailoring options by passing a series of options as additional query string parameters to the request.

Note: Representation modifiers are resource-specific and therefore are not propagated to links in the response which point to a different resource type. This means that applications need to add representation modifiers to all links received in a response except for those that link to the same resource type. For example, the URI in the next attribute.

Please refer to the sections on the individual media types for details on which representation modifiers are supported for each type.

Page Size (size)

The option defines the page size (maximum number of items) of all paginateble collections in the response; if not provided, each collection may define its own reasonable default. Individual collections may define a maximum page size and then use that instead of the provided value.

For example:
  • In search results, the size option determines the maximum amount of result items to show on each result list page (default: 20).
  • In media collections such as media.images, the maximum number of images to return (default: 5).

Text Format (tf)

Various attributes returned in responses are defined as rich text strings. With this option, clients can define the format in which rich text attributes are exposed.

Supported values are:
  • html : (default) The rich text is rendered as an XHTML fragment using a subset of the standard HTML elements applicable for text rendering, including a, b, br, ul, ol, li, i, p, h? or img (only used for inline-images).
  • plain : The rich text attribute is reduced to a plain text representation.

Image dimensions (image_dimensions)

When a resource provides a URI of image resources (for example, photos of a place) applications are able to request specific maximum sizes of those images to match their UI and bandwidth requirements.

The format is that of a comma-separated list where each element specifies dimensions for a scaled image by providing either the desired width, desired height, or both.

Valid elements are:
  • w\d+
  • h\d+
  • w\d+-h\d+
Examples:
  • image_dimensions=w32-h32,w64-h64
  • image_dimensions=w32-h32,w300
  • image_dimensions=h200

The provided values are used as upper boundaries for the dimensions of the returned images. The solution will never scale up small images and will maintain the aspect ratio of the original image.

If this option is used, the image objects in media.images.items contain a dimensions attribute, which is a map containing links to the sized variants of the original image.

For example:
{
  "src": "http://...",
  "dimensions": {
    "w32-h32": "http://...",
    "w64-h64": "http://..."
  }
}

Show content (show_content)

show_content allows applications to request additional content related to the search result.

The format is a comma-separated list of content names.

Identifier Description
wikipedia This option can be used to show Wikipedia editorial content in Place Media Type response.
Note: HERE has no control over the availability and quality of Wikipedia content. For more detail, please read HERE Disclaimer on third party content. When displaying Wikipedia content, client applications must display the source attribution next to the content. This requirement forms part of the terms and conditions of the Places (Search) API.
fuel The HERE platform also has a fuel service. The fuel service has information about fuel prices and fuel types from petrol stations. In case show_content contains fuel, Places (Search) API will enrich search result with fuel content. This is only done if search result has petrol-station category. This option can only be used when requesting the Search Media Type.
Example of fuel content:
"fuelPrices": {
  "text":"Super Unleaded: EUR 1.359/l<br/>Diesel: EUR 1.089/l",
  "label":"Fuel Prices"
}

Show references (show_refs)

show_refs allows applications to request place/location related ids of external systems to be included in returned response.

The format is a comma-separated list of external system names.

The option can only be used when requesting the following media types:
Places (Search) API currently support the following external systems:
Name of the system Identifier Description
HERE Core Maps pvid HERE’s core content product provides map and POI data for most regions of the world. This data product provides long term stable identifiers, called PVID. For the subset of map features that are available through Places (Search) API, that external reference allows to correlate information available in the two products
HERE Venue Maps venues.* HERE’s venue maps product provides indoor maps for thousands of venues. It provides three type of identifiers:
  • venues: All types of venue IDs
  • venues.venue: Venue IDs
  • venues.content: Venue content IDs
  • venues.destination: Venue destination IDs
All types of identifier can be used to associate the corresponding objects in the venue maps product with Places (Search) API
Facebook facebook Application can use Facebook unique page ID to retrieve content directly from Facebook Graph API
Yelp yelp Application can use Yelp unique ID to retrieve content directly from Yelp Business API
TripAdvisor tripadvisor Application can use TripAdvisor unique ID to retrieve content directly from TripAdvisor Content API
Opentable opentable Website developer can use OpenTable restaurant unique ID to include OpenTable reservation widget.

For more detailed information on External References, please refer to User Guide External References

Teasers (teasers)

The maximum number of places in search results that should have teaser information (e.g image URL) included.

The format is numeric value (default: 0).

Category systems (cs)

cs allows applications to request multiple place categories from different category systems to be included in returned response.

The format is a comma-separated list of category system names.

The option can only be used when requesting the following media types:
Supported values are:
  • places: Place categories
  • cuisines: Cuisine categories

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.