Places (Search) API Developer's Guide

Utilization of Hypermedia Links

Client applications interact with the Places (Search) API JSON representations by using hypermedia links in the resources. A hypermedia link is a JSON object which has an href attribute.

Link Object in A Place Resource

A place resource contains hypermedia links to the category resources associated with the place, for example:

{
  "name": "Max's Pizza Place",
  "placeId": "360u09tv-be16478e55314b338c551aab2651c9d3",

  "categories": [
    {
      "id": "restaurant",
      "title": "Restaurant",
      "href": "http://...",
      "type": "urn:nlp-types:category",
      "icon": "http://..."
    }
  ]

}

Hypermedia Link in Category Resource

The link object in the categories array from the place resource example above points to the category resource in the following example:

{
  "categoryId": "restaurant",
  "name": "Restaurant",
  "icon": "http://..."
}

Note: The attribute names used in the category resource in this example are different from the ones used in the example in the categories array from the place resource example above.

Method Attribute in Link Object

A link object can contain a method attribute, if the action/method to perform on the resource is not the default retrieval GET method, for example:

{
  "delete": {
    "title": "Delete an item",
    "href": "http://...",
    "method": "DELETE"
  }
}

Type of Resource

All links to Places (Search) API resources indicate the type of the resource being linked to with the type attribute. It is possible to filter links based on the type attribute.

A link can also point to an external resource type, in which case the type attribute is either a MIME media type or missing, but not a type URI, for example a via link object in an image or review object:

{
  "via": {
    "href": "https://share.here.com/p/s-Yz1yZXN0YXVyYW5...",
    "type": "text/html"
  }
}

Note: In case a link object does not contain a type attribute, use the most universal http client available (usually a web browser) to open that link as it may connect to any kind of web resource.

Places (Search) API link objects follow the convention that when a link object is an attribute value, the attribute name signifies the relation type. For example, the via attribute on a review object signifies that the link is to the original document containing the review.