Location search¶

POST /product_api/v1/search/structured¶

Search for addresses and lots given structured queries.

Request JSON Object:
	entity (string) – What kind of location is desired; either a `adres` (address) or a `perceel` (lot). query (object) – Structured query describing the desired entities. A query may be of types `bool`, `field` or `dis-max`.
Response JSON Array of Objects:
	score (float) – 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. uuid (string) – The unique identifier for this search result. Used later to find the relevant intentions. title (string) – The human readable string describing the location object. properties (object) – Various properties describing the location. See Entities for the variations for each entity.
Status Codes:	200 OK – yields a list of locations and their matching score to the query, sorted by score descending. 400 Bad Request – passed an invalid entity or query object.

Example request:

POST /product_api/v1/search/structured
Host: planviewer.nl
Accept: application/json
Content-Type: application/json

{
  "entity": "adres",
  "query": {
    "bool": {
      "must": [
        {
          "field": {
            "fields": [
              "postcode"
            ],
            "query": "6512EX"
          }
        },
        {
          "field": {
            "method": "match",
            "fields": [
              "huisnummer"
            ],
            "query": "2"
          }
        }
      ]
    }
  }
}

Example response:

[
  {
    "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"
    }
  }
]

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

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’