Places (Search) API Developer's Guide

Changing Responses with Representation Modifiers

Places (Search) API media types allow you to specify some aspects of how the information contained in a response is presented. You can change the following aspects of information contained in a response:

  • number of items per page in paginated responses
  • text format
  • image dimensions
  • additional content

Use the appropriate query parameters as indicated below to set the representation modifiers in your 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 you need to add representation modifiers to all links received in a response, except for those that point to the same resource type. For example, the URI in the next attribute for paginated objects.

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

Page Size (size)

The size parameter defines the maximum number of items that should be in a page in responses that contain paginateble collections. If you do not specify a value for size, each collection may define its own default. Individual collections may define a maximum page size and then use that instead of the value provided in the seach results.

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

Text Format (tf)

Some response attributes are defined as rich text strings. You can use the text format parameter (tf) to specify the format of rich text attributes.

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

Image Dimensions (image_dimensions)

When a resource provides a URI for image resources (for example, photos of a place), you can specify maximum sizes for those images in your request to match your UI and bandwidth requirements.

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

Valid elements are:
  • w{dimension}
  • h{dimension}
  • w{dimension}-h{dimension}
Examples:
  • image_dimensions=w32-h32,w64-h64
  • image_dimensions=w32-h32,w300
  • image_dimensions=h200

The provided values are used as upper limits for the dimensions of the images in the responses. Small images are never scaled and the aspect ratio of the original image remains intact.

If you use the parameter image_dimensions, 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)

The parameter show_content allows you to request additional content related to the search result.

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

Table 1. Supported additional content
Identifier Description
wikipedia You can use this value to request Wikipedia content be included in a Place Media Type response when available.
Note: HERE has no control over the availability and quality of Wikipedia content. For more details, see Third Party Content (Disclaimer). 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 offers a fuel service with information about fuel prices and fuel types from petrol stations. If you set show_content to fuel, Places (Search) API enriches the search result with fuel content. This is only done if the search result has a 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)

The parameter show_refs allows you to request that place/location IDs from external systems be included in the response.

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

The option can only be used when requesting the following media types:
The Places (Search) API currently supports the external systems listed in the table below.
Table 2. Supported external systems
Name of the system Identifier Description
HERE Core Maps pvid HERE Core Maps offers map and POI data for most regions of the world. These maps include long-term stable identifiers called Published Version IDs (PVIDs). For the subset of map features that are available through the Places (Search) API, PVIDs may allow you to match information available in different HERE products.
HERE Venue Maps venues.* HERE Venue Maps offers indoor maps for thousands of venues.
It provides three types of identifiers:
  • venues – all types of venue IDs
  • venues.venue – venue IDs
  • venues.content – venue content IDs
  • venues.destination – venue destination IDs
You can use all identifier types to associate the corresponding objects in Venue Maps with the Places (Search) API.
Facebook facebook You can use Facebook unique page IDs to retrieve content directly from the Facebook Graph API.
Yelp yelp You can use a Yelp unique ID to retrieve content directly from the Yelp Business API.
TripAdvisor tripadvisor You can use a TripAdvisor unique ID to retrieve content directly from the TripAdvisor Content API.
Opentable opentable Website developers can use OpenTable restaurant unique IDs to include the OpenTable reservation widget.

For more detailed information, see External References.

Teasers (teasers)

You can use the parameter teasers to specify the maximum number of places in a response to a search request that should have teaser information (for example, an image URL) included.

The format is a numeric value, with the default 0.

Category Systems (cs)

The parameter cs allows you to request that multiple POI categories from different category systems be included in the response.

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

This option can only be used when requesting the following media types:
The possible values of the parameter are:
  • places – Place categories
  • cuisines – Cuisine categories