/
Search API

Search API

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.

Inhaltsverzeichnis

 

1. 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.

 

2. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info

Endpunkte

GET

POST

PUT

DELETE

Befehl/Info

Endpunkte

GET

POST

PUT

DELETE

Volltextsuche, Kategorie-Navigation, Filterung & Sortierung

search/

Suchvorschläge (Suggest / Autocomplete)

suggest/

 

3. 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.

 

3.1 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

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

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

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.

 

3.2 Filter-Informationen

 

3.2.1 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.

 

3.2.2 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

 

3.2.3 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.

Eine Erklärung der unterschiedlichen Filter-Typen finden Sie hier: https://websale.atlassian.net/wiki/spaces/Doku/pages/2972352526

 

3.2.4 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.

 

 

4. Verwendung der Methoden

 

4.1 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

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

 

Kategorie-Navigation (ohne Suchbegriff)

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.

 

 

4.1 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

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.

 

© 2025 WEBSALE AG | Impressum | Datenschutz