Places (Search) API Developer's Guide

Search Media Type

The search media type describes a step in a user activity to find/discover places.

Media Type URI

urn:nlp-types:search

Media Type Structure

The representation provides some information about the search request, but the primary information in the search media type is a list of result items that guides users directly or indirectly to the place(s) they are looking for. This media type has the following format:

{
  "search": {
    //...
  },
  "results" : {
    "items": [
      //...
    ]
  }
}
Attribute Type Description
results Object[DiscoverResultSet] a paginateable collection of search result items.
search Object[SearchDescription] search location context that the service has chosen for the query.

Search Description

Attribute Type Description
context Object[SearchContext] search context information
supportsPanning Boolean; optional If true, this request can be run in different locations.
ranking String; optional Indicates the specific ranking algorithm selected for the query. See Search Results Ranking for details. Values are:
  • default - the default ranking
  • category-recommendations - "recommendation-style" category ranking
  • category-distance - category ranking by distance
  • chain - chain ranking

Search Context Information

The primary information about the search context is the location context that the service has chosen for the query. Usually the location context is derived from the explicit location parameters of a discover activity. But sometimes the location context is also derived from other elements, particularly from a user's search term. For example, when a user located in "Berlin, Germany" uses the search term is "Restaurant in Paris", the search algorithm uses "Paris" as the search location.

When the location context of a place discovery is derived from one of the explicit location parameters, the selected one is returned in the result. Depending on the endpoint used, it may also contain an address or area of the location:

{
  "search": {
    "context": {
      "title": "Paris",
      "location": {
        "position": [52.5044, 13.3909]
        "address": {
          "city": "Paris",
          "country": "France",
          "text": "Paris<br/>France"
          //...
        }
      },
      "type": "urn:nlp-types:place"
    }
    //...
  }
}

Result items of type search contain the context used for the search, which includes the following attributes:

Attribute Type Description
title String (formatted text); optional A (short) textual representation of the item
location Object[SearchLocation] The location used for the search.
type String The type of the resource being linked to. The value is either a valid MIME media type or a URI. Places (Search) API internal links always use a URN in the namespace "nlp-types" for the type attribute. If missing, the link goes to a web resource that is best opened in a universal HTTP client, like a web browser.
href String (URI); optional A hyperlink that refers to the resource represented by that result item.
moved Boolean; optional If true, the location used for the search is different from the one provided in the request.

Search Location

Attribute Type Description
position Array[Number] A position given by latitude and longitude, for example [37.785141,-122.4047775]
address Object[Address]; optional The neighborhood of the location used for the search.
bbox Array[Number]; optional An enclosing rectangle that describes a range of coordinates corresponding to the location of the place. Bounding boxes are typically associated with places such as cities and countries. A bounding box is specified as an array ([West longitude, South latitude, East longitude, North latitude]) according to the GeoJSON geospatial data interchange format.