Skip to content

Searching

Searching for products is the most important part of Ecommerce Search. Most of the other features are designed to enhance the product search experience.

To learn how to use search, read through the tutorial.

Phrase

The most basic element of the search request is the phrase. The phrase refers to the text provided by the user, that the user wants to search for. The phrase can be modified by the text analysis pipeline to model linguistic structures, such as hypernyms or misspellings.

Pagination

The search response can be paginated by setting an offset and numberOfResults.

It should not be used to do a paged export of data, use the POST /sku-export endpoint for that instead. See the full API reference here.

Sorting

Ecommerce Search's allows configurable sorting of search results based on predefined fields or custom attributes, in either ascending or descending order.

Segment

When searching for products, a segmentId is needed to select the correct search dataset. The segment determines which products to search for, but also which synonyms to apply, along with hypernyms and other text-analysis configurations. It is therefore important that the correct segment is chosen.

Context

The context affects both the commercial sorting of the returned products, but also which facets are returned in a search response. The search request does not specify a contextId, instead, it automatically selects the best-fitting context based on the search request. When searching for products, Ecommerce Search resolves the best-fitting context according to context conditions. A splitTestId can be set to track split tests for contexts. The splitTestId, along with context conditions, is used to resolve the best context.

Filters

Filters for products, SKUs, content and exports work in the same way. Read more here.

Scope

A scope is required to complete a search request. The scope is used to resolve the context and apply domain filters.

Scopes determine the default number of results and SKUs per result. Scopes also determine which fields are returned in the search response. These values can be overwritten in the search request.

Given a scope with the following fieldsToReturn:

  • ProductName
  • Price
  • Media

A search with this scope then returns.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "skus": [
    {
      "id": "BZ01",
      "skuNo": "",
      "ean": null,
      "name": "",
      "metadata": null,
      "price": {
        "price": 1000,
        "listPrice": 1000
      },
      "stringAttribute": {},
      "numberAttributes": {},
      "intervalAttributes": {}
    }
  ],
  "id": "BZ01",
  "alternativeIds": [],
  "productNumber": "",
  "name": "Bizzkit T-Shirt",
  "shortDescription": "",
  "longDescription": "",
  "media": [
    {
      "url": "https://docs.academy02.test/BlueBizzkit3.c59253dd-f56c-4a3a-b484-f6eac0a7654d.jpg",
      "type": "Image"
    }
  ],
  "metadata": null
}

The name and media link of the product and the price of the SKU are returned. All the other fields are still there, just without any data. Even though the fields are there, the search is optimized to only retrieve the specified fields from the dataset, so limiting which fields a scope returns will affect the performance of the search.

Personalization

The userId is used to enable personalized sorting.

Pinning

It is possible to pin products to the top of a search result. Both products and skus can be pinned by their id.

Pinned products have the following characteristics:

  • The order of pinned products is fixed. The first product in the list will be first in the result and so on.
  • A pinned product appears if and only if they are part of the search result. Irrelevant product will never be returned.
  • A pinned product only appears once, and does not reappear in the list of sorted products.

A product search query, like below, will return the product product_id_3 and product containing the sku with id sku_id_15 if they contain the word shoes in the searchable fields.

Request
1
2
3
4
5
6
7
8
{
  "segmentId": "b2c-dk-da",
  "phrase": "Shoes",
  "scopeId": "browse"
  "pinnedIds": [
    "product_id_3",
    "sku_id_15"]
}

Unified Search provides access to various data sources and features such as products, content, suggestions, related tags, and Did You Mean from a single endpoint, with automatic correction functionality for misspelled search phrases.

It is possible to specify filters that cannot be changed by end users. These can be set in the AuthenticationToken. See Authenticated Search. This is used for getting prices for other price groups than the default one.

Suggestions

Searching for suggestions is useful to help guide users toward their intended search phrase. It can also help users who are not sure how to spell something. To search for suggestions, suggestion candidates must first be created.

Given a suggestion candidate tshirt, searching for suggestions is as simple as:

Request
1
2
3
4
5
{
  "segmentId": "b2c-dk-da",
  "phrase": "t",
  "numberOfResults": 12
}

Provides this suggestion.

Response
1
2
3
4
5
6
{
  "suggestions": [
    "tshirt"
  ],
  "total": 1
}

Did you mean

Did You Mean provides alternative search phrases for user searches that contain typos or misspellings, improving search results by correcting simple misspellings, typos, missing spaces, extra spaces, and missing hyphens.

Semantic search can help solve 0-result searches.