Search API - WEBSALE Dokumentation

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 und 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:

https://<ihre-shopid>.search.websale.net/api/

Beispiele für die Verwendung der Endpoints

Suche

https://<ihre-shopid>.search.websale.net/api/search?query=schuhe&subshop=01-aa&from=0&size=24

Suchvorschläge / Autocomplete

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/
Suchvorschläge (Suggest / Autocomplete)	suggest/

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 (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)

{
  "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 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

"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)

{
  "_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

"brand": {
  "label": "Marke",
  "values": ["Nike", "Adidas", "Puma"]
}

Range-Filter (z. B. Preis)

"price": {
  "label": "Preis",
  "min": 29.99,
  "max": 299.99
}

Die tatsächlich verfügbaren Filterfelder werden im Backend über filter_fields konfiguriert.

`applied_filters`

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

Struktur

"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 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

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

{
  "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 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) 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 (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`

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)

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)

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)

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

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

GET https://<ihre-shopid>.search.websale.net/api/suggest?query=lauf&subshop=01-aa

Beispiel-Response

{
  "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.

​Basis-URL

​Beispiele für die Verwendung der Endpoints

​Suche

​Suchvorschläge / Autocomplete

​Unterstützte Methoden

​Datenfelder der Search-Response

​Bereiche für Produkte, Kategorien und Content

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

​Parameterbeschreibungen

​Filter-Informationen

​filters

​Checkbox-Filter

​Range-Filter (z. B. Preis)

​applied_filters

​Struktur

​zero_result_filters

​wssearchdata

​Verwendung der Methoden

​GET api/search

​Beispiel-Anfrage

​Beispiel-Response

​Übersicht der Query-Parameter für GET api/search

​Weitere Beispiel-Aufrufe für GET api/search

​Kategorie-Navigation (ohne Suchbegriff)

​Filter-Kombinationen (Marke, Preis, Farbe)

​Pagination (Seite 2 bei 24 Ergebnissen pro Seite)

​Negativ-Filter (Farben ausschließen)

​Preis-Range mit Sortierung nach Preis

​GET api/suggest

​Beispiel-Aufruf

​Beispiel-Response

​Übersicht der Queryparameter für GET api/suggest

Basis-URL

Beispiele für die Verwendung der Endpoints

Suche

Suchvorschläge / Autocomplete

Unterstützte Methoden

Datenfelder der Search-Response

Bereiche für Produkte, Kategorien und Content

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

Parameterbeschreibungen

Filter-Informationen

`filters`

Checkbox-Filter

Range-Filter (z. B. Preis)

`applied_filters`

Struktur

`zero_result_filters`

`wssearchdata`

Verwendung der Methoden

GET `api/search`

Beispiel-Anfrage

Beispiel-Response

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

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

Kategorie-Navigation (ohne Suchbegriff)

Filter-Kombinationen (Marke, Preis, Farbe)

Pagination (Seite 2 bei 24 Ergebnissen pro Seite)

Negativ-Filter (Farben ausschließen)

Preis-Range mit Sortierung nach Preis

GET `api/suggest`

Beispiel-Aufruf

Beispiel-Response

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