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:
|
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. |