> ## 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-Schnittstelle der WEBSALE Search API für Volltextsuche, Filter, Sortierung, Pagination und Suchvorschläge (Suggest/Autocomplete).

Die Search API stellt den HTTPS-basierten Zugriff auf das versionsunabhängige Suchmodul WEBSALE Search bereit.

Typische Anwendungsfälle:

* Volltextsuche über Produkte, Kategorien und ggf. Content
* Filter (Checkbox-Filter, Preisbereiche usw.)
* Vorschlagsfunktion (Suggest) mit Suchvorschlägen
* Pagination und Sortierung

Die Search API ist unabhängig von [Storefront API](/schnittstellen/storefront-api) und [Admin Interface API](/schnittstellen/admin-interface-api) und wird in der Regel parallel dazu eingesetzt.

***

## Basis-URL

Alle REST-API-Aufrufe der Suche laufen über dieselbe Basis-URL unter dem Pfad `/api`:

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

#### Beispiele für die Verwendung der Endpoints

#### Suche

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

#### Suchvorschläge / Autocomplete

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

`<ihre-shopid>` muss durch Ihre ShopID / CommonID der für Sie bereitgestellten Shop-Plattform ersetzt werden.

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl/Info**                                             | **Endpunkte** | **GET**               | **POST**            | **PUT**             | **DELETE**          |
| ----------------------------------------------------------- | ------------- | --------------------- | ------------------- | ------------------- | ------------------- |
| Volltextsuche, Kategorie-Navigation, Filterung & Sortierung | search/       | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| Suchvorschläge (Suggest / Autocomplete)                     | suggest/      | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |

***

## Datenfelder der Search-Response

Die Search-API liefert bei `GET search` ein JSON-Objekt mit mehreren Bereichen für Treffer und Filter.

Die verfügbaren Felder in den Ergebnissen hängen von der [Backend-Konfiguration](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) (`display_fields`, `filter_fields`) ab.

### Bereiche für Produkte, Kategorien und Content

Dieser Abschnitt beschreibt die Aufteilung der Suchergebnisse in die Bereiche `product`, `category` und `optional content` mit jeweils eigener Trefferliste und Trefferanzahl. Darüber hinaus wird erläutert, welche zusätzlichen Metadaten (z. B. `total,` `filters`, `applied_filters`, `zero_result_filters` und `wssearchdata`) in der Response enthalten sind und wofür sie verwendet werden.

#### Beispiel einer Search-Response-Struktur (verkürzt)

```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": "schwarz",
          "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": "Laufschuhe",
          "url": "/category/laufschuhe"
        }
      }
    ],
    "sub_total": 5
  },
  "total": 155,
  "filters": { ... },
  "applied_filters": { ... },
  "zero_result_filters": ["inventoryamount"],
  "wssearchdata": "..."
}
```

#### Parameterbeschreibungen

| **Name**              | **Typ** | **Verwendung**                                                                                                                                                                                                                                                                |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `product`             | object  | Ergebnisse der Produkt-Kontext. Enthält eine Trefferliste und die Anzahl der gefundenen Produkte.                                                                                                                                                                             |
| `category`            | object  | Ergebnisse im Kategorie-Kontext. Enthält eine Trefferliste und die Anzahl der gefundenen Kategorien.                                                                                                                                                                          |
| `content`             | object  | Ergebnisse im Content-Kontext, z.B. statische Seiten wie Über uns, Ratgeber etc. (optional)                                                                                                                                                                                   |
| `total`               | int     | Gesamtanzahl aller Treffer über alle Indizes / Bereiche hinweg. (Summe aus `product.sub_total`, `category.sub_total` und ggf. `content.sub_total`).                                                                                                                           |
| `filters`             | object  | Liste der verfügbaren Filter für die aktuelle Suche (z.B. Marke, Farbe, Preisbereich) inklusive Labels, möglicher Werte und ggf. Min-/Max-Werten.                                                                                                                             |
| `applied_filters`     | object  | Aktuell gesetzte Filter der Anfrage.                                                                                                                                                                                                                                          |
| `zero_result_filters` | array   | Liste von statischen Filtern, die im aktuellen Kontext zu 0 Treffern führen würden. (z.B. bestimmte Größen oder Farben, für die aktuell keine Produkte gefunden werden).      Hinweis: Nur für `WebComponents` relevant.                                                      |
| `wssearchdata`        | string  | Zusatzdaten für das WEBSALE-Bekleidungsmodul (z. B. Query- und Farbwerte)  Das [WEBSALE Bekleidungsmodul](https://doku.websale.net/index.html?guide_bekleidungsmodul.html) ist eine Funktion, die ausschließlich in der WEBSALE Shopsoftware Version V8s zur Verfügung steht. |

Die Bereiche `product`, `category` und optional `content` haben jeweils die gleiche Struktur

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

| **Name**    | **Typ** | **Verwendung**                                                                                                                                |
| ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `results`   | array   | Liste der einzelnen Treffer in diesem Bereich. Jedes Element im Array repräsentiert z.B. ein Produkt, eine Kategorie oder eine Content-Seite. |
| `sub_total` | int     |                                                                                                                                               |

Einzelnes Ergebnis in `results` (Beispiel verkürzt)

```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": "schwarz",
    "size": ["41", "42", "43"],
    "image": "https://example.com/image.jpg",
    "url": "/product/nike-air-max"
  }
}
```

| **Name**  | **Typ** | **Verwendung**                                                                                                                                                                                     |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id`     | string  | Interne ID des Dokuments im Suchindex Dient zur eindeutigen Identifikation des Treffers im Index.                                                                                                  |
| `_source` | object  | Inhalt des Dokuments laut Suchindex. Welche Felder hier enthalten sind, wird über die Konfiguration der `display_fields` gesteuert und ist je Index (Produkt, Kategorie, Content) unterschiedlich. |

### Filter-Informationen

### `filters`

`filters` beschreibt, welche Filter für die aktuelle Suche zur Verfügung stehen.

Die Struktur ist abhängig vom Filtertyp, z.B. Checkbox, Listbox etc.

#### Checkbox-Filter

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

#### Range-Filter (z. B. Preis)

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

Die tatsächlich verfügbaren Filterfelder werden im [Backend](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) über `filter_fields` konfiguriert.

### `applied_filters`

`applied_filters` spiegelt wider, welche Filter über die URL-Parameter aktuell aktiv sind.

#### Struktur

```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 oder [ \"array\", \"von\", \"werten\" ]",
      "field": "{technischer-feldname}"
    }
  ]
}
```

* `op_type`: verwendeter Operator (z. B. `eq`, `gte`)
* `value`: ein Wert oder eine Liste von Werten
* `field`: Name des Feldes, auf das sich der Filter bezieht

### `zero_result_filters`

`zero_result_filters` enthält die Namen statischer Custom-Filter (z. B. `"inventoryamount"`), die im aktuellen Kontext zu 0 Treffern führen würden.

Dabei geht es nicht um dynamische Filter aus dem Parameter `filters`. Diese dynamischen Filter führen per Definition nie zu 0 Ergebnissen.\
0 Treffer treten nur bei Custom-/statischen Filtern auf, die z. B. über `WebComponents` erstellt werden und immer zur Verfügung stehen – unabhängig von der aktuellen Suche.

### `wssearchdata`

`wssearchdata` ist ein technisches Feld für das [WEBSALE Bekleidungsmodul](https://doku.websale.net/index.html?guide_bekleidungsmodul.html) der Shopversion V8s.

Es enthält u. a. Informationen zu Query und Farbfiltern und wird dafür genutzt, farbige Variantenbilder auf Produktlisten korrekt zu laden.

Für die Anbindung einer eigenen Frontend-Suche kann das Feld in der Regel unverändert an die entsprechenden Skripte übergeben werden.

## Verwendung der Methoden

### GET `api/search`

Mit diesem Aufruf werden Suchergebnisse aus dem Suchindex geladen. Der Endpunkt kann sowohl für klassische Volltextsuche als auch für reine Filter-/Kategorie-Navigation (ohne Suchbegriff) verwendet werden.

#### **Beispiel-Anfrage**

Einfache Suche nach „laufschuhe“ im Subshop `01-aa`

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

`<ihre-shopid>` ist dabei die Shop-/CommonID der Shop-Plattform - siehe Kapitel 1 zur Basis-URL.

#### Beispiel-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 zu den einzelnen Feldern sind im Abschnitt zur [Search-Response-Struktur](#3-datenfelder-der-search-response) beschrieben.

#### **Übersicht der Query-Parameter für GET** `api/search`

| **Parameter**                     | **Typ** | **Beschreibung**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device`                          | string  | Gerätetyp, optional für Logging, z.B. `desktop`, `mobile`, `tablet`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `filter_{OPERATOR}[{FIELD_NAME}]` |         | Filter werden über separate Query-Parameter mit Operator-Syntax übergeben.  - eq → Equals (exakte Übereinstimmung) - neq → Not Equals (Ausschluss) - gte → Greater Than or Equal - lte → Less Than or Equal - rm → Remove  Für mehrere Werte desselben Filters kann der Parameter mehrfach übergeben werden (ODER-Verknüpfung).  Weitere Details zu Filterparametern finden Sie unter [URL-Filterparameter (Query-Parameter)](https://websale.atlassian.net/wiki/spaces/Doku/pages/3130949644/URL-Filterparameter+Query-Parameter) in der allgemeinen Dokumentation des Suchmoduls. |
| `from`                            | integer | Offset für Pagination resp. Blätterfunktion (Startposition der Trefferliste)  Standard: `0`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `language`                        | string  | Browser-Sprache, optional für Logging / Auswertung, z.B. `de-DE`, `en-US`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `sessionId`                       | string  | Session-Tracking-ID, optional für Logging, z.B. `sess_abc123`  Standard: `unknown`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `size`                            | integer | Anzahl der Ergebnisse pro Seite.  Standard: `16`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sortOrder`                       | string  | Sortierreihenfolge. Konkrete Sortfelder sind [konfigurationsabhängig](https://websale.atlassian.net/wiki/spaces/Doku/pages/2944139282/Konfiguration+des+Such-Moduls) (z. B. Relevanz, Preis).  Standard: `_score_desc`                                                                                                                                                                                                                                                                                                                                                              |
| `subshop`                         | string  | **Pflichtfeld**. Subshop-Identifier (lowercase). Bestimmt den Suchkontext / Index. Beispiel: `01-aa`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `query`                           | string  | Suchbegriff für Volltextsuche. Wenn keine `query` übergeben wird, muss stattdessen ein `filter_eq[catids]` gesetzt sein (Suche auf Kategorie-Ebene).   Mindestens einer der Parameter `query` oder `filter_eq[catids]` muss in der Anfrage enthalten sein, zusätzlich zu `subshop`.                                                                                                                                                                                                                                                                                                 |

#### Weitere Beispiel-Aufrufe für GET `api/search`

#### Kategorie-Navigation (ohne Suchbegriff)

```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`: verwendet den Suchindex des Subshops `01-aa`.
* `filter_eq[catids]=electronics`: beschränkt die Treffer auf die Kategorie `electronics`.\
  Hinweis: Bei `Backend-Suchmodul-Versionen < 1.7.x` muss hier der Kategoriename als String (zB. '`electronics`') übergeben werden; ab `Version 1.7.x` wird an dieser Stelle die tatsächliche Kategorie ID erwartet.
* `from=0&size=24`: liefert die erste Seite mit bis zu 24 Treffern.
* Ergebnis: Kategorie-Navigation in `electronics` ohne Volltextsuchbegriff.

#### Filter-Kombinationen (Marke, Preis, Farbe)

```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]=schwarz
```

* `query=smartphone`: Volltextsuche nach „smartphone“.
* `subshop=01-aa`: Suche im Subshop `01-aa`.
* `sortOrder=price_asc`: Sortierung nach Preis aufsteigend.
* `filter_eq[brand]=Samsung&filter_eq[brand]=Apple`: nur Produkte der Marken Samsung **oder** Apple.
* `filter_gte[price]=200&filter_lte[price]=800`: Preisbereich 200–800 (inklusive).
* `filter_eq[color]=schwarz`: nur schwarze Produkte.
* Ergebnis: gefilterte Smartphone-Suche, preisaufsteigend sortiert.

#### Pagination (Seite 2 bei 24 Ergebnissen pro Seite)

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

* `query=schuhe`: Volltextsuche nach „schuhe“.
* `subshop=01-aa`: Suche im Subshop `01-aa`.
* `size=24`: 24 Treffer pro Seite.
* `from=24`: Überspringt die ersten 24 Treffer → entspricht Seite 2.
* Ergebnis: zweite Seite der Suchergebnisse für „schuhe“.

#### Negativ-Filter (Farben ausschließen)

```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]=weiß&filter_neq[color]=beige
```

* `query=shirts`: Volltextsuche nach „shirts“.
* `subshop=01-aa`: Suche im Subshop `01-aa`.
* `filter_neq[color]=weiß&filter_neq[color]=beige`: schließt weiße und beige Shirts aus.
* Ergebnis: alle Shirt-Treffer, **außer** in den Farben Weiß und Beige.

#### Preis-Range mit Sortierung nach Preis

```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`: Volltextsuche nach „laptop“.
* `subshop=01-aa`: Suche im Subshop `01-aa`.
* `filter_gte[price]=600&filter_lte[price]=1500`: Preisbereich 600–1500 (inklusive).
* `sortOrder=price_asc`: Sortierung nach Preis aufsteigend.
* Ergebnis: Laptops im Preisbereich 600–1500, günstigste zuerst.

### GET `api/suggest`

Der Endpunkt `GET /api/suggest` liefert Suchvorschläge für einen eingegebenen Teil-Suchbegriff.

Die Vorschläge basieren primär auf Logdaten (häufig gesuchte Begriffe) und können bei Bedarf um automatisch generierte Completions ergänzt werden. Zusätzlich kann ein Text für Ghost-Text-Vervollständigung zurückgegeben werden.

#### Beispiel-Aufruf

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

#### Beispiel-Response

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

* `suggestions` ist absteigend anhand des Parameters `hitCount` sortiert und sind aus Logdaten generierte Suchvorschläge. Diese werden bei Bedarf mit `completion` aufgefüllt.
* `completion` liefert einen Text, mit dem das Suchfeld automatisch hinter dem aktuell eingegebenen Text ergänzt werden kann (Ghost-Text/Auto-Vervollständigung).

#### **Übersicht der Queryparameter für GET** `api/suggest`

| **Parameter** | **Typ** | **Beschreibung**                                                                                                                                          |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`       | string  | **Pflichtfeld.**  Teil-Suchbegriff, zu dem Vorschläge ermittelt werden sollen, z.B. “lauf” für Vorschläge wie beispielsweise “laufschuhe” und “laufhose”. |
| `subshop`     | string  | **Pflichtfeld.**  Subshop-Identifier der Suche.  Es muss die SubshopID, z.B. 01-aa, des gewünschten Subshops angegeben werden.                            |