.. index:: Search .. _search: Search ====== Bespoke endpoint for doing searches. Returns a list of embedded :ref:`SearchResult ` representations. This endpoint supports both simple search via query string parameters and more complicated search via a json request placed in the request body. Search queries support boolean clauses (via and,or keywords), and negation (via - suffix). To illustrate this consider the following advertisements +----+-------------------------------------------------------+ | id | Title | +====+=======================================================+ | 1 | new car | +----+-------------------------------------------------------+ | 2 | old car | +----+-------------------------------------------------------+ | 3 | old boat | +----+-------------------------------------------------------+ | 4 | new motorbike | +----+-------------------------------------------------------+ This table lists a number of example queries along with the advertisements that would be returned from the set above +-----------------------------+--------------------------------------+ | Query | Advertisements returned | +=============================+======================================+ | car | 1,2 | +-----------------------------+--------------------------------------+ | car or boat | 1,2,3 | +-----------------------------+--------------------------------------+ | new and car | 1 | +-----------------------------+--------------------------------------+ | car -new | 2 | +-----------------------------+--------------------------------------+ | (old and car) or -old | 1,2,4 | +-----------------------------+--------------------------------------+ .. note:: For performance reasons we do not support deep pagination, you will not be able to retrieve more than 5000 results for a given search query. Because this number may change in the future. The preferred way to page through a collection is to to follow the next link relation in the response Query Parameters ---------------- .. parameters:: .. parameter:: :name: categoryId :constraints: -- the categoryId to filter on .. parameter:: :name: query :constraints: must be a non empty value when neither categoryId or sellerId is defined the search query. .. parameter:: :name: withImages :default: false :constraints: -- true to indicate that indicate that only results that have images should be returned .. parameter:: :name: searchDescription :default: false :constraints: -- true to indicate that the description field should be taken into account when doing searches .. parameter:: :name: sellerId :constraints: -- only return advertisements belonging to the specified seller .. parameter:: :name: postCode :constraints: 6 character postcode Postcode center of area search .. parameter:: :name: distance :constraints: positive Radius distance area of search from postcode in meters .. parameter:: :name: sortBy :constraints: one of ``default``, ``location``, ``price`` Which field is used for sorting .. parameter:: :name: sortOrder :constraints: one of ``ascending``, ``descending`` Order in which search results are returned .. parameter:: :name: offset :constraints: offset * limit cannot be greater than 5000 :default: 0 0 based index of the first element to return in the response, currently has to be a multiple of the limit value eg. when the limit is 10, then 10, 20, 30 are allowed 11 is not. We do not support deep pagination. offset * limit has to be < 5000 .. parameter:: :name: limit :constraints: max 200 :default: 30 maximum number of contained elements to return in the response .. parameter:: :name: locale :constraints: valid language tags like 'nl-NL', 'fr-BE' Comma separated list of locales to use for filtering the results Fields ------ .. apifields:: .. apifield:: :name: query :type: string :constraints: -- :required: false :updateable: false :writable: true search query .. apifield:: :name: categoryId :type: int :constraints: -- :required: false :updateable: false :writable: true the categoryId to filter on .. apifield:: :name: sellerId :type: int :constraints: -- :required: false :updateable: false :writable: true only return advertisements belonging to the specified seller .. apifield:: :name: withImages :type: boolean :constraints: -- :required: false :updateable: false :default: false :writable: false true to indicate that indicate that only results that have images should be returned .. apifield:: :name: searchDescription :type: boolean :constraints: -- :required: false :updateable: false :default: false :writable: true true to indicate that the description field should be taken into account when doing searches .. apifield:: :name: offset :type: int :constraints: -- :required: true :updateable: false :writable: true 0 based index of the first element to return in the response .. apifield:: :name: limit :type: int :constraints: -- :required: true :writable: true :updateable: false The category in which the advertisement is placed. maximum number of contained elements to return in the response .. apifield:: :name: totalCount :type: int :constraints: -- :required: false :updateable: false :writable: false total number of elements matching your search query .. apifield:: :name: categoriesHistogram :type: :ref:`Categories Histogram ` :constraints: -- :required: false :updateable: false :writable: false the distribution of ads per categories .. apifield:: :name: attributesHistogram :type: :ref:`Attributes Histogram ` :constraints: -- :required: false :updateable: false :writable: false the distribution of ads per attribute values Search request fields --------------------- .. apifields:: .. apifield:: :name: offset :type: int :constraints: -- :required: true :updateable: false :writable: true 0 based index of the first element to return in the response .. apifield:: :name: limit :type: int :constraints: -- :required: true :writable: true :updateable: false The category in which the advertisement is placed. maximum number of contained elements to return in the response .. apifield:: :name: query :type: string :constraints: -- :required: false :updateable: false :writable: true search query .. apifield:: :name: categoryId :type: int :constraints: -- :required: false :updateable: false :writable: true the categoryId to filter on .. apifield:: :name: withImages :type: boolean :constraints: -- :required: false :updateable: false :default: false :writable: false true to indicate that indicate that only results that have images should be returned .. apifield:: :name: searchDescription :type: boolean :constraints: -- :required: false :updateable: false :default: false :writable: true true to indicate that the description field should be taken into account when doing searches .. apifield:: :name: sellerId :type: int :constraints: -- :required: false :updateable: false :writable: true only return advertisements belonging to the specified seller .. apifield:: :name: filters :type: object :constraints: -- :required: false :writable: true Search request filters object. Used to declare detailed filtering .. apifield:: :name: filters.price.from :type: int :constraints: positive :required: false :writable: true .. apifield:: :name: filters.price.to :type: int :constraints: positive :required: false :writable: true .. apifield:: :name: filters.postCode :type: String :constraints: 6 character postcode :required: false :writable: true Postcode center of area search .. apifield:: :name: filters.distance :type: int :constraints: positive :required: false :writable: true Radius distance area of search from postcode in meters .. apifield:: :name: filters.{customAttributeKey} :type: array of strings :constraints: -- :required: false :writable: true Any custom attribute can be used for filtering by setting an array of custom attribute values in case of simple or multiple attributes Ex: // select elements with attribute "customAttributeA" equals value1 or value2 "customAttributeA" : ["value1", "value2"] .. apifield:: :name: filters.{customNumericAttributeKey} :type: object :constraints: -- :required: false :writable: false Any custom numeric attribute can be used for filtering by setting, optionally "from" and/or "to" fields Ex: // select elements with values between 10 and 20 inclusive "customNumericAttributeA" : {"from": 10, "to": 20 } // select elements with values of 35 and more "customNumericAttributeA" : {"from": 35 } .. apifield:: :name: sort.by :type: string :constraints: one of ``default``, ``location``, ``price`` :required: false :updateable: false :writable: false Which field is used for sorting .. apifield:: :name: sort.order :type: string :constraints: one of ``ascending``, ``descending`` :required: false :updateable: false :writable: false Order in which search results are returned Relations --------- .. relations:: .. relation:: :name: mp:search-result :embedded: yes :cardinality: 0..N Reference --------- .. endpoint:: GET /v1/search Errors ------ .. errors:: .. error:: :http: 400 :code: pagination-invalid :description: The pagination offset and limit need to match, offset should be a multitude of limit. .. error:: :http: 400 :code: pagination-too-deep :description: limit * offset cannot be > 5000 .. error:: :http: 400 :code: limit-invalid :description: The specified limit is invalid .. error:: :http: 400 :code: query-missing :description: When not specifying a category id the query cannot be empty or missing .. error:: :http: 500 :code: internal-server-error :description: Oops! Sorry, something went wrong on our side. Examples -------- .. include:: examples/get-search-simple.rst .. include:: examples/get-search-complex.rst