Location search --------------- .. http:post:: /product_api/v1/search/structured Search for addresses and lots given structured queries. :jsonarr float score: A score describing how good the query matches to the current location. The score is relative to the current search results, and can not be used to denote the quality of the result in absolute terms. :>jsonarr string uuid: The unique identifier for this search result. Used later to find the relevant intentions. :>jsonarr string title: The human readable string describing the location object. :>jsonarr object properties: Various properties describing the location. See :ref:`api-product-search-entities` for the variations for each entity. :status 200: yields a list of locations and their matching score to the query, sorted by score descending. :status 400: passed an invalid entity or query object. **Example request**: .. sourcecode:: http POST /product_api/v1/search/structured Host: planviewer.nl Accept: application/json Content-Type: application/json .. sourcecode:: json { "entity": "adres", "query": { "bool": { "must": [ { "field": { "fields": [ "postcode" ], "query": "6512EX" } }, { "field": { "method": "match", "fields": [ "huisnummer" ], "query": "2" } } ] } } } **Example response**: .. sourcecode:: json [ { "score": 51.31008, "uuid": "9d3e1336-4093-4825-abde-46346805abb2", "title": "Castellastraat 2, 6512EX Nijmegen", "properties": { "type": "adres", "postcode": "6512EX", "huisnummer": "2", "huisnummertoevoeging": null, "huisletter": null, "openbareruimtenaam": "Castellastraat", "woonplaatsnaam": "Nijmegen" } }, { "score": 39.816944, "uuid": "98acb62e-c6e2-4f50-9e24-a6f3458f6669", "title": "Castellastraat 52, 6512EX Nijmegen", "properties": { "type": "adres", "postcode": "6512EX", "huisnummer": "52", "huisnummertoevoeging": null, "huisletter": null, "openbareruimtenaam": "Castellastraat", "woonplaatsnaam": "Nijmegen" } } ] .. _api-product-search-bool-query: Bool query ^^^^^^^^^^ Query which allows the composition of other queries. Adds the score of subqueries for each location result. The semantics of this query is inspired by the similar bool query-concept within `Elasticsearch `_. The following fields are all optional: * **must** *(optional)*: array of query objects for which locations *must* match. * **should** *(optional)*: array of query objects for which locations *should* match, but need not to. * **filter** *(optional)*: array of query objects for which locations *must* match, but their score does not contribute to the compound score. * **must_not** *(optional)*: array of query objects for which locations *must not* match. Their score does not contribute to the compound score. * **minimum_should_match** *(optional)*: the absolute number (integer) of optional clauses that should match. Field query ^^^^^^^^^^^ Query which compares a string to a set of fields. * **query**: a string to which is compared. * **fields**: an array of fields (key names as strings) to which the query string is compared. Optionally a single field can also be passed as a string. The set of applicable fields depends on the entity type, and is described under :ref:`api-product-search-entities`. * **method** *(optional)*: either `match` or `literal`. In the case of `literal` the query must *exactly* match the fields. In the case of `match` a fuzzy matching scheme is used. Defaults to `literal`. Dis-max query ^^^^^^^^^^^^^ Query for which the compound score is determined by the highest scoring subquery, contrary to the sum of all scores as with the :ref:`api-product-search-bool-query`. * **queries**: an array of queries. * **tie_breaker** *(optional)*: a floating point value between 0.0 and 1.0. Defaults to 0.0. Takes the sum of all scores except for the highest score and multiplies this sum by the **tie_breaker**-value. This value is added to the compound score. Conceptually makes the dis-max query behave as a bool query for a value of 1.0. .. _api-product-search-entities: Entities ^^^^^^^^ The Product API support two types of location entities which are used to search products for, and subsequently order them. They can be search using various fields. The applicable fields are also reported back in the search results under the **properties**-field. Adres (address) """"""""""""""" Addresses are entities as defined by the Dutch Kadaster in the `Basisregistraties Adressen en Gebouwen `_. They are either a verblijfsobject, standplaats or a ligplaats. The defined fields are: * **postcode**: postal code, without spaces. Example: '6512EX'. * **huisnummer**: house number, always an integer. * **huisletter**: letter belonging to an addressable object. * **huisnummertoevoeging**: suffix string to a house number and letter. * **openbareruimtenaam**: name of a public space. Typically the name of a street, but could also be a square, park, etc. * **woonplaatsnaam**: name of a town. Perceel (lot) """"""""""""" Lots are entities as defined by the Dutch Kadaster in the `Digitale Kadastrale Kaart `_. * **gemeentecode**: code (string), example for Nijmegen: 'NMG00'. * **sectie**: section code (string), example 'A' * **perceelnummer**: lot number (integer), example '211'