The search-api bundle provides an API for searching on a set of stores.

The API of this bundle is described in detail in the API documentation.


Bundles should inject the search-api.SearchService to trigger searches:

"components": [
        "name": "MyComponent",
        "references": [{
            "name": "searchService",
            "providing": "search-api.SearchService"

Use the service's search() method to search for items:

const result ="a query");

Use cases

Registering stores for searching

To register a store with the search-api bundle, add the value "search" to the useIn property. By default, all registered stores are searched by the search-api.SearchService implementation.

Additionally, the store must fulfil the following requirements:

Note: these properties may be defined either on the OSGi Level (as service properties) or directly on the store instance. If both ways are used, the service properties take precedence over instance properties.

Supported store properties

Property Type Required Description
id String yes The store's unique ID.
title String no The label for results obtained from this store. Defaults to id if not specified.
searchAttribute String yes The attribute name to query against.
searchLabel String no The label for search results. This can be either an attribute name or a string template, e.g. "title" or "${city_name} (${zip_code})". Defaults to the search attribute.
searchPriority Number no The search priority of the store. A lower value indicates a higher priority. The default priority is 50. The value is evaluated by the search-ui bundle.
searchCandidateCount Number no The amount of result candidates fetched during a search. For these result candidates a score is calculated to produce best matching results. If the value is 0, the algorithm is disabled. If the value is greater than 0, the exact amount of candidates are requested. See the section Client-side score for more details.

Property names of the omnisearch bundle continue to work on some occasions for compatibility reasons:

Property Type Required Description
omniSearchSearchAttr String yes The attribute name to query against. Same as searchAttribute.
omniSearchLabelAttr String no The attribute name that defines the label of a search result. Same as searchLabel
omniSearchLabelString String no The label for search results. Same as searchLabel.

Full example

The following code sample shows how to use the agssearch bundle to define a store:

"bundles": {
    "agssearch": {
        "AGSStore": [
                "id": "stoerungen",
                "title": "Störungen",
                "description": "Störungen",
                "searchAttribute": "kommentar",
                "searchLabel": "kommentar",
                "url": "",
                "useIn": [
                "filterOptions": {
                    "suggestContains": true
                "fetchIdProperty": true,
                "enablePagination": false,

Client-side score

When a search is performed, map.apps requests 10 times as much candidates as are displayed in the user interface (for example, 50 candidates are requested when 5 should be displayed). For these candidates, a score is calculated based on the position of the search term in the corresponding search input text.

If a store already calculates a score itself, you can disable client-side scoring by setting "searchCandidateCount": 0 in the store properties. This is already configured for the locator-store.

To configure the exact number of requested candidates, add the property with a concrete number, for example "searchCandidateCount": 100.

Analyzing search behavior

The search service will use the EventService to emit search-api/SELECTED events whenever a user selects an item from a result set. The event conforms to the SelectedEvent interface.