Places (Search) API Developer's Guide

Search Results Media Type

The search-results media type is the structure used for the search results attribute.

Media Type URI

urn:nlp-types:search-results

Media Type Structure

The representation provides a paginateable list of result items that guide users directly or indirectly to the place(s) they are looking for.

{
  "results" : {
    "next": "http://...",
    "offset": 20,
    "items": [
      //...
    ]
  }
}
Attribute Type Description
previous String (URI); optional The URI to the subresource holding the previous page of the collection. If the current page is the first page of the collection, the attribute is not present.
next String (URI); optional The URI to the subresource holding the next page of the collection. If the current page is the last page of the collection, the attribute is not present.
offset Number (integer); optional Pages other than the first page of a collection may include this attribute. If present, it contains the index of the first item in the current page.
items Array[PlaceLink | SearchLink] There are several different types of result items, but regardless of its specific type, each result item is a link object.

The goal of all discovery resources is to guide a user to a place, but this might not always be possible or appropriate in a single step. For example, there may be too many candidates and therefore the user might want to define additional criteria. Therefore some result items directly link to a place, while others link to different resources that can be presented to the user and contain further links via which the user will be linked to a place.

Each resource item has a `type` field identifying the type of page that it links to. The current implementation of the Places (Search) API supports two types:

Place Media Type (urn:nlp-types:place)
A user selecting the item in a Place Link will be directed to a place.
Search Media Type (urn:nlp-types:search)
A user selecting the item in a Search Link will trigger a refined/more precise search query. This type of result item may appear when the amount of reasonable matches is too large and the service can offer additional criteria that may be used to refine the query.

Upcoming releases may introduce additional types (e.g. events). Clients must be prepared to handle that situation and ignore any results that have a `type` that they don't know how to handle.