Search API - WEBSALE Dokumentation

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

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

Examples for using the endpoints

Search

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

Search suggestions / autocomplete

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/
Search suggestions (suggest / autocomplete)	suggest/

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

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

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

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

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

Range filter (e.g. price)

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

The actually available filter fields are configured in the backend via filter_fields.

`applied_filters`

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

Structure

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

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

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

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

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)

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)

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)

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

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

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

Example response

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

​Base URL

​Examples for using the endpoints

​Search

​Search suggestions / autocomplete

​Supported methods

​Data fields of the search response

​Areas for products, categories, and content

​Example of a search response structure (shortened)

​Parameter descriptions

​Filter information

​filters

​Checkbox filter

​Range filter (e.g. price)

​applied_filters

​Structure

​zero_result_filters

​wssearchdata

​Using the methods

​GET api/search

​Example request

​Example response

​Overview of query parameters for GET api/search

​Further example calls for GET api/search

​Category navigation (without search term)

​Filter combinations (brand, price, color)

​Pagination (page 2 with 24 results per page)

​Negative filter (exclude colors)

​Price range with sorting by price

​GET api/suggest

​Example call

​Example response

​Overview of query parameters for GET api/suggest

Base URL

Examples for using the endpoints

Search

Search suggestions / autocomplete

Supported methods

Data fields of the search response

Areas for products, categories, and content

Example of a search response structure (shortened)

Parameter descriptions

Filter information

`filters`

Checkbox filter

Range filter (e.g. price)

`applied_filters`

Structure

`zero_result_filters`

`wssearchdata`

Using the methods

GET `api/search`

Example request

Example response

Overview of query parameters for GET `api/search`

Further example calls for GET `api/search`

Category navigation (without search term)

Filter combinations (brand, price, color)

Pagination (page 2 with 24 results per page)

Negative filter (exclude colors)

Price range with sorting by price

GET `api/suggest`

Example call

Example response

Overview of query parameters for GET `api/suggest`