> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Search API

> HTTPS endpoints of WEBSALE Search for full-text search, autocomplete suggestions, filters, pagination, and sorting across products and categories.

The Search API provides HTTPS-based access to the version-independent search module WEBSALE Search.

Typical use cases:

* Full-text search across products, categories, and, if applicable, content
* Filters (checkbox filters, price ranges, etc.)
* Suggestion function (suggest) with search suggestions
* Pagination and sorting

The Search API is independent of [Storefront API](/en/schnittstellen/storefront-api) and [Admin Interface API](/en/schnittstellen/admin-interface-api) and is generally used in parallel with them.

***

## Base URL

All REST API calls of the search run via the same base URL under the path `/api`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://<your-shopid>.search.websale.net/api/
```

#### Examples for using the endpoints

#### Search

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://<your-shopid>.search.websale.net/api/search?query=shoes&subshop=01-aa&from=0&size=24
```

#### Search suggestions / autocomplete

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://<your-shopid>.search.websale.net/api/suggest?query=sho&subshop=01-aa
```

`<your-shopid>` must be replaced with your ShopID / CommonID of the shop platform provided to you.

***

## Supported methods

List of all supported methods.

| **Command/Info**                                           | **Endpoints** | **GET**               | **POST**            | **PUT**             | **DELETE**          |
| ---------------------------------------------------------- | ------------- | --------------------- | ------------------- | ------------------- | ------------------- |
| Full-text search, category navigation, filtering & sorting | search/       | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| Search suggestions (suggest / autocomplete)                | suggest/      | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |

***

## Data fields of the search response

The Search API returns a JSON object with several areas for hits and filters on `GET search`.

The available fields in the results depend on the [backend configuration](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) (`display_fields`, `filter_fields`).

### Areas for products, categories, and content

This section describes the breakdown of the search results into the areas `product`, `category`, and `optional content` each with their own hit list and hit count. In addition, it explains which additional metadata (e.g. `total`, `filters`, `applied_filters`, `zero_result_filters`, and `wssearchdata`) is included in the response and what they are used for.

#### Example of a search response structure (shortened)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "product": {
    "results": [
      {
        "_id": "123456",
        "_source": {
          "name": "Nike Air Max",
          "price": 129.99,
          "brand": "Nike",
          "color": "black",
          "size": ["41", "42", "43"],
          "image": "https://example.com/image.jpg",
          "url": "/product/nike-air-max"
        }
      }
    ],
    "sub_total": 150
  },
  "category": {
    "results": [
      {
        "_id": "cat_001",
        "_source": {
          "name": "Running shoes",
          "url": "/category/running-shoes"
        }
      }
    ],
    "sub_total": 5
  },
  "total": 155,
  "filters": { ... },
  "applied_filters": { ... },
  "zero_result_filters": ["inventoryamount"],
  "wssearchdata": "..."
}
```

#### Parameter descriptions

| **Name**              | **Type** | **Usage**                                                                                                                                                                                                                                                    |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `product`             | object   | Results of the product context. Contains a hit list and the number of products found.                                                                                                                                                                        |
| `category`            | object   | Results in the category context. Contains a hit list and the number of categories found.                                                                                                                                                                     |
| `content`             | object   | Results in the content context, e.g. static pages such as About us, guides, etc. (optional)                                                                                                                                                                  |
| `total`               | int      | Total number of all hits across all indexes / areas. (Sum of `product.sub_total`, `category.sub_total`, and, if applicable, `content.sub_total`.)                                                                                                            |
| `filters`             | object   | List of available filters for the current search (e.g. brand, color, price range) including labels, possible values, and, if applicable, min/max values.                                                                                                     |
| `applied_filters`     | object   | Currently set filters of the request.                                                                                                                                                                                                                        |
| `zero_result_filters` | array    | List of static filters that would lead to 0 hits in the current context. (E.g. certain sizes or colors for which no products are currently found.)      Note: Only relevant for `WebComponents`.                                                             |
| `wssearchdata`        | string   | Additional data for the WEBSALE clothing module (e.g. query and color values)  The [WEBSALE clothing module](https://doku.websale.net/index.html?guide_bekleidungsmodul.html) is a function that is only available in the WEBSALE shop software version V8s. |

The areas `product`, `category`, and optionally `content` each have the same structure

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"product": {
  "results": [ ... ],
  "sub_total": 150
}
```

| **Name**    | **Type** | **Usage**                                                                                                                          |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `results`   | array    | List of individual hits in this area. Each element in the array represents, for example, a product, a category, or a content page. |
| `sub_total` | int      |                                                                                                                                    |

Individual result in `results` (example shortened)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "_id": "123456",
  "_source": {
    "name": "Nike Air Max",
    "price": 129.99,
    "brand": "Nike",
    "color": "black",
    "size": ["41", "42", "43"],
    "image": "https://example.com/image.jpg",
    "url": "/product/nike-air-max"
  }
}
```

| **Name**  | **Type** | **Usage**                                                                                                                                                                                             |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id`     | string   | Internal ID of the document in the search index. Used for unique identification of the hit in the index.                                                                                              |
| `_source` | object   | Content of the document according to the search index. Which fields are included here is controlled via the configuration of the `display_fields` and differs per index (product, category, content). |

### Filter information

### `filters`

`filters` describes which filters are available for the current search.

The structure depends on the filter type, e.g. checkbox, listbox, etc.

#### Checkbox filter

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"brand": {
  "label": "Brand",
  "values": ["Nike", "Adidas", "Puma"]
}
```

#### Range filter (e.g. price)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"price": {
  "label": "Price",
  "min": 29.99,
  "max": 299.99
}
```

The actually available filter fields are configured in the [backend](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) via `filter_fields`.

### `applied_filters`

`applied_filters` reflects which filters are currently active via the URL parameters.

#### Structure

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
"applied_filters": {
  "{field_name}": [
    {
      "op_type": "eq|neq|gte|lte|gt|lt",
      "value": "single_value or [ \"array\", \"of\", \"values\" ]",
      "field": "{technical-field-name}"
    }
  ]
}
```

* `op_type`: operator used (e.g. `eq`, `gte`)
* `value`: a value or a list of values
* `field`: name of the field to which the filter refers

### `zero_result_filters`

`zero_result_filters` contains the names of static custom filters (e.g. `"inventoryamount"`) that would lead to 0 hits in the current context.

It is not about dynamic filters from the `filters` parameter. By definition, these dynamic filters never lead to 0 results.\
0 hits only occur with custom/static filters that are created, for example, via `WebComponents` and are always available — regardless of the current search.

### `wssearchdata`

`wssearchdata` is a technical field for the [WEBSALE clothing module](https://doku.websale.net/index.html?guide_bekleidungsmodul.html) of shop version V8s.

It contains, among other things, information about query and color filters and is used to correctly load colored variant images on product lists.

For the integration of your own frontend search, the field can usually be passed unchanged to the corresponding scripts.

## Using the methods

### GET `api/search`

This call loads search results from the search index. The endpoint can be used for both classic full-text search and pure filter/category navigation (without a search term).

#### **Example request**

Simple search for "running shoes" in subshop `01-aa`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shopid>.search.websale.net/api/search?query=running shoes&subshop=01-aa&from=0&size=24
```

`<your-shopid>` is the shop/CommonID of the shop platform — see chapter 1 on the base URL.

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "product": {
    "results": [...],
    "sub_total": 150
  },
  "category": {
    "results": [...],
    "sub_total": 5
  },
  "content": {
    "results": [...],
    "sub_total": 0
  },
  "total": 155,
  "filters": { ... },
  "applied_filters": { ... },
  "zero_result_filters": [ ... ],
  "wssearchdata": "..."
}
```

Details on the individual fields are described in the section on the [search response structure](#3-data-fields-of-the-search-response).

#### **Overview of query parameters for GET** `api/search`

| **Parameter**                     | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device`                          | string   | Device type, optional for logging, e.g. `desktop`, `mobile`, `tablet`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `filter_{OPERATOR}[{FIELD_NAME}]` |          | Filters are passed via separate query parameters with operator syntax.  - eq → Equals (exact match) - neq → Not Equals (exclusion) - gte → Greater Than or Equal - lte → Less Than or Equal - rm → Remove  For multiple values of the same filter, the parameter can be passed multiple times (OR concatenation).  Further details on filter parameters can be found under [URL filter parameters (query parameters)](https://websale.atlassian.net/wiki/spaces/Doku/pages/3130949644/URL-Filterparameter+Query-Parameter) in the general documentation of the search module. |
| `from`                            | integer  | Offset for pagination or paging function (start position of the hit list)  Default: `0`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `language`                        | string   | Browser language, optional for logging / evaluation, e.g. `de-DE`, `en-US`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sessionId`                       | string   | Session tracking ID, optional for logging, e.g. `sess_abc123`  Default: `unknown`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `size`                            | integer  | Number of results per page.  Default: `16`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sortOrder`                       | string   | Sort order. Specific sort fields are [configuration-dependent](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) (e.g. relevance, price).  Default: `_score_desc`                                                                                                                                                                                                                                                                                                                                                                |
| `subshop`                         | string   | **Required field**. Subshop identifier (lowercase). Determines the search context / index. Example: `01-aa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `query`                           | string   | Search term for full-text search. If no `query` is passed, a `filter_eq[catids]` must be set instead (search at category level).   At least one of the parameters `query` or `filter_eq[catids]` must be included in the request, in addition to `subshop`.                                                                                                                                                                                                                                                                                                                   |

#### Further example calls for GET `api/search`

#### Category navigation (without search term)

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET /api/search?subshop=01-aa&filter_eq[catids]=electronics&from=0&size=24
```

* `subshop=01-aa`: uses the search index of the subshop `01-aa`.
* `filter_eq[catids]=electronics`: restricts the hits to the category `electronics`.\
  Note: With `backend search module versions < 1.7.x`, the category name must be passed here as a string (e.g. '`electronics`'); from `version 1.7.x`, the actual category ID is expected at this point.
* `from=0&size=24`: returns the first page with up to 24 hits.
* Result: category navigation in `electronics` without a full-text search term.

#### Filter combinations (brand, price, color)

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET /api/search?query=smartphone&subshop=01-aa&from=0&size=24&sortOrder=price_asc&filter_eq[brand]=Samsung&filter_eq[brand]=Apple&filter_gte[price]=200&filter_lte[price]=800&filter_eq[color]=black
```

* `query=smartphone`: full-text search for "smartphone".
* `subshop=01-aa`: search in the subshop `01-aa`.
* `sortOrder=price_asc`: sorting by price ascending.
* `filter_eq[brand]=Samsung&filter_eq[brand]=Apple`: only products of the brands Samsung **or** Apple.
* `filter_gte[price]=200&filter_lte[price]=800`: price range 200–800 (inclusive).
* `filter_eq[color]=black`: only black products.
* Result: filtered smartphone search, sorted by price ascending.

#### Pagination (page 2 with 24 results per page)

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET /api/search?query=shoes&subshop=01-aa&from=24&size=24
```

* `query=shoes`: full-text search for "shoes".
* `subshop=01-aa`: search in the subshop `01-aa`.
* `size=24`: 24 hits per page.
* `from=24`: skips the first 24 hits → corresponds to page 2.
* Result: second page of the search results for "shoes".

#### Negative filter (exclude colors)

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET /api/search?query=shirts&subshop=01-aa&filter_neq[color]=white&filter_neq[color]=beige
```

* `query=shirts`: full-text search for "shirts".
* `subshop=01-aa`: search in the subshop `01-aa`.
* `filter_neq[color]=white&filter_neq[color]=beige`: excludes white and beige shirts.
* Result: all shirt hits, **except** in the colors white and beige.

#### Price range with sorting by price

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET /api/search?query=laptop&subshop=01-aa&filter_gte[price]=600&filter_lte[price]=1500&sortOrder=price_asc
```

* `query=laptop`: full-text search for "laptop".
* `subshop=01-aa`: search in the subshop `01-aa`.
* `filter_gte[price]=600&filter_lte[price]=1500`: price range 600–1500 (inclusive).
* `sortOrder=price_asc`: sorting by price ascending.
* Result: laptops in the price range 600–1500, cheapest first.

### GET `api/suggest`

The endpoint `GET /api/suggest` returns search suggestions for a partial search term entered.

The suggestions are primarily based on log data (frequently searched terms) and can be supplemented with automatically generated completions if required. Additionally, a text can be returned for ghost text completion.

#### Example call

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shopid>.search.websale.net/api/suggest?query=run&subshop=01-aa
```

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "suggestions": [
    {
      "text": "running shoes nike",
      "hitCount": 150
    },
    {
      "text": "running pants",
      "hitCount": 89
    },
    {
      "text": "running jacket",
      "hitCount": 45
    }
  ],
  "completion": "running shoes"
}
```

* `suggestions` is sorted in descending order by the `hitCount` parameter and consists of search suggestions generated from log data. These are filled up with `completion` if needed.
* `completion` provides a text that can be used to automatically complete the search field behind the currently entered text (ghost text/autocompletion).

#### **Overview of query parameters for GET** `api/suggest`

| **Parameter** | **Type** | **Description**                                                                                                                                              |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query`       | string   | **Required field.**  Partial search term for which suggestions are to be determined, e.g. "run" for suggestions such as "running shoes" and "running pants". |
| `subshop`     | string   | **Required field.**  Subshop identifier of the search.  The SubshopID, e.g. 01-aa, of the desired subshop must be specified.                                 |