@polar/plugin-address-search v2.0.0-alpha.5

AddressSearch

Scope

The AddressSearch plugin allows users to search for an address. If multiple addresses are returned by services, the user is prompted to select a result.

The plugin saves the chosen information as GeoJSON to the store so that following procedures may grab it or so that other plugins may use it.

Currently supported services:

• BKG
• WFS
• Some gazetteers/WFS-G (please request a check or try yourself, not 100% done)

Configuration

addressSearch

The configuration allows defining and grouping services. Grouped services can be requested in a search at the same time, and one group of searches can be active at a time. When multiple searches are in a group, they may be extended with category information to make the results easier to browse.

It is advised to either use one-search-per-group or all services in a singular group to avoid an overly complex UI. Mixed configurations may be required for more complex search requirements.

In categoryProperties and groupProperties, id strings called groupId and categoryId are used. These are arbitrary strings you can introduce and reuse to group or categorize elements together. Regarding what groups and categories are, see further below.

addressSearch.searchMethodsObject

addressSearch.customSearchMethod

This is a function with the following signature:

(
  // should be used to actually abort request
  signal: AbortSignal,
  // base url as configured
  url: string,
  // input value from address search input
  inputValue: string,
  // whatever was configured
  queryParameters: any
) => Promise<FeatureCollection> | never

With this, arbitrary services can be supported.

addressSearch.customSelectFunction

This is a function with the following signature:

({
  // VueX context object
  context,
  payload: {
    feature, // GeoJSON feature
    categoryId // if configured on searchService, else ''
  }
}) => void

With this, arbitrary click results can be supported. Please mind that undocumented mutations and actions fired in such a function are subject to change without further notice.

addressSearch.groupProperties

addressSearch.categoryProperties

addressSearch.searchMethodsObject.queryParameters (type:common)

These fields are interpreted by all implemented services.

addressSearch.searchMethodsObject.queryParameters (type:wfs)

Since inputs may overlap with multiple patterns, multiple queries are fired and executed on the WFS until the maxFeatures requirement is met, beginning with the pattern that 'looks like the user input the most'. The best-fitting pattern on the returned features will be used to generate a display string. When two patterns fit best, the first one is used.

addressSearch.searchMethodsObject.queryParameters (type:gazetteer)

⚠️ "gazetteer" is deprecated. Please use "mpapi" instead.

addressSearch.searchMethodsObject.queryParameters (type:mpapi)

Please mind that this requires a configured backend. A WFS's Stored Query is requested with predefined parameters using the masterportalApi. This implementation is meant for e.g. https://geodienste.hamburg.de/HH_WFS_GAGES, but works with other WFS configured in the same manner.

While all fields are optional, configuring none of them will yield undefined behaviour. At least one search instruction should be set to true.

addressSearch.searchMethodsObject.queryParameters (type:bkg)

In BKG mode, queryParameter's key-value pairs are used in the service query. E.g. {filter: { bundesland: 'Bremen' }} results in the GET request URL having &filter=bundesland:Bremen as suffix.

For more options, please check the official documentation regarding what query parameters are interpreted.

Additionally, it is possible to configure the parameters accesstoken (Authorization) or apiKey (custom header X-Api-Key) to send the described headers to the search service for authentication purposes.
Note that this changes the request to be non-simple. To be able to use the parameters, the request has to be sent in cors mode and has to support preflight request OPTIONS.

Store

Mutations

setSelectedGroupName

This can be used to change the selected search group by name.

map.$store.commit(
  'plugin/addressSearch/setSelectedGroupName',
  'Flurstückssuche'
)

Please mind that programmatically changing the search group will not trigger a search, unlike a search group change by the user. If you need a search after change, consider the search action.

Actions

search

This is a purely programmatical search method. It is not used by user input.

map.$store.dispatch('plugin/addressSearch/search', {
  input: 'Bahnhofsstraße 12',
  autoselect: 'first',
})

The payload object supports the following fields:

State

map.subscribe('plugin/addressSearch/chosenAddress', (chosenAddress) => {
  /* Your code. */
})

Address object as returned by search service. The result and its fields differ depending on the used backend. The callback is used whenever the user clicks on a search result or started a one-result search, which results in an auto-select of the singular result.