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.
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 search results.
- 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
, thesize
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.
tf
are: -
html
– (default) rich text is rendered as an XHTML fragment using a subset of the standard HTML elements applicable for text rendering, includinga
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
) (DEPRECATED)
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.
-
w{dimension}
-
h{dimension}
-
w{dimension}-h{dimension}
-
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.
{
"src": "http://...",
"dimensions": {
"w32-h32": "http://...",
"w64-h64": "http://..."
}
}
Show Content (show_content
) (DEPRECATED)
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.
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 and the customer is licensed to use the Fuel API. This option can only be used when requesting the Search Media Type. |
"fuelPrices": {
"text":"Super Unleaded: EUR 1.359/l<br/>Diesel: EUR 1.089/l",
"label":"Fuel Prices"
}
Show References (show_refs
) (DEPRECATED)
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.
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: You can use all identifier types to associate the corresponding objects in Venue Maps with the Places (Search) API.
|
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. |
For more detailed information, see External References.
Teasers (teasers
) (DEPRECATED)
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.
-
places
– Place categories -
cuisines
– Cuisine categories