Search

Overview

This guide focuses on the SCAYLE Search configuration in the SCAYLE Panel. To gain a better understanding of the search logic and technical implementation, refer to the Developer Guide.

The search consists of two main endpoints, the /v2/suggestions and the /v2/resolve endpoint.

While they have many similarities, there are also some differences between the two:

As a response to a search term, they may return categories, products, or navigation items.

Both endpoints rely on a good configuration to yield satisfying results.

On this page, you will find out how to define your SCAYLE Search in order to get optimal results.

Configuration

SCAYLE offers a search module that allows you to adjust the output of frontend search results.
You can access the search configuration options in the Shops area through Shops > [Shop Name] > Storefront > Search Configuration.

You can configure the following settings:

• Searchable Navigation Items
• Searchable Attributes
• Synonyms
• Typo Tolerance
• Category Exclusions
• Product Exclusions

Include Navigation Items in Search Results

As our search is category-based, you'll need to manually set the visibility of pages that you want to be searchable, such as Shipping, FAQs, Article pages or SEO pages to include them in the search results.

Define a Navigation Item as Searchable

1. the Go to Shops > Shop > Storefront > Navigation.
2. Click the pen icon next to the required navigation item.
3. Select the Include to Search checkbox.
4. In the Target, select Page from the dropdown.
5. Under Page, select the page you want to include.
6. Click SAVE.

Customers can now retrieve this page by entering relevant keywords or synonyms in the search bar. Synonyms have to be added first. Find out how to add them in the section Navigation Synonyms.

Searchable Attributes

SCAYLE uses attribute groups to define search result logic. Searchable Attributes only affect the Text Search of the Storefront API.

Guidelines

Understanding which attribute groups make for an excellent searchable attribute and which don't is essential. When an attribute group is set as searchable, the search will try to match against any of the words in the assigned attribute.

Add an Attribute to the Search Result Logic

1. Click + Add First Attribute.
2. Select an attribute from the dropdown.

Use drag and drop to assign priorities to these groups to influence their order in the search results. Attribute groups with a higher priority affect the search results order significantly more than those with a lower priority.

Synonyms

The Synonyms area bundles various options for managing synonyms. Synonyms play an essential role in the output of search results, as the system can recognize which terms are considered equivalent. Use the tabs to define synonyms for single search words or combinations of words, categories, and attributes.

Category Synonyms

We support defining synonyms for your existing categories. The category synonyms work like alternative names for the specified category, as they are stored alongside the normal name of the category.

Benefits

1. Synonyms stay attached to the category even if you rename the category
2. They are easier to maintain and feature less risk
3. They work with autocomplete endpoints
4. They work with typo tolerance

Guidelines

As a general guideline, we recommend adding category synonyms to applicable categories instead of word synonyms. Adding category synonyms will work seamlessly with other endpoint functionalities, such as autocomplete and typo tolerance.

As an example, if a category is called "Shirts", but users search for "T-Shirt" then this would be a good candidate to add "T-Shirt" as a synonym.
On our search endpoints, the category "Shirts" would then be returned when the user types in "Shirts" or "T-Shirt".

Before you start:

Add a New Category Synonym

1. Go to Shops > [Shop Name] > Storefront > Search Configuration > Synonyms.
2. Select CATEGORIES tab.
3. Click + New Category.
4. A drop-down menu opens where you select the corresponding category and enter suitable synonyms.

Add Category Synonyms in Bulk

To find out how to add category synonyms in bulk, please see the documentation on imports & jobs in the User Guide.

Attribute Group Synonyms

We support defining synonyms for your existing attributes. Similar to the category synonyms, these are alternative names for your specified attribute and are stored alongside the normal name of the attribute.

Benefits

1. Synonyms stay attached to the attribute even if you rename the attribute
2. They are easier to maintain and feature less risk
3. They work with autocomplete endpoints
4. They work with typo tolerance

Guidelines

As an example, if an attribute group "color" has an attribute "purple", but users search "lila" then this would be a good candidate to add "lila" as a synonym.

Before you start:

For attributes to be used for matching search terms to products, you must add these attributes to the Search Result Logic first.

Add a New Attribute Group Synonym

1. Go to Shops > [Shop Name] > Storefront > Search Configuration > Synonyms.
2. Select the ATTRIBUTES tab.
3. Click + New Attribute.
4. In the popup, select Attribute group, Attribute, and Synonyms.

Add Attribute Group Synonyms in Bulk

To find out how to add attribute group synonyms in bulk, please see the documentation on imports & jobs in the User Guide.

Word synonyms

Word Synonyms allow you to dynamically replace certain words and combinations of words from the user's search term.

Benefits

Word synonyms are synonyms that apply across our search endpoints suggestions and resolve, but also work for product search through the products endpoint, which can be used as a fallback, when no matching category or navigation item is found.

Guidelines

The general guideline is to put existing categories, product names and attributes on the left and terms that users might search for (but don't have a matching category/product name/attribute) on the right.

Word synonyms work best for cases where a user searches for a single word, which is a combined term of an existing attribute and an existing category. This is quite common in some languages, like German.
As an example, if a user searches "leinenhose", but "leinen" is an attribute and "hose" is a category, then this is a good candidate for adding a word synonym, where "leinenhose" (the right term) would get mapped into "leinen hose" (the left term).

Word synonyms are also good candidates for improving search on product names.
As an example, the product is called "air max", but the users search for "airmax". This is then a good candidate for a word synonym, where "airmax" (right term) would get mapped into "air max" (left term).

Add a New Word Synonym

1. Go to Shops > [Shop Name] > Storefront > Search Configuration > Synonyms.
2. Select the WORDS tab.
3. Click + New Word to enter search terms and synonyms for words.
4. Under Word, enter the terms that your users are searching for.
5. Under Synonyms, enter the alternatives for the search term.

When searching, the searched terms on the right side (in the screenshot below) will be linked with the term on the left.
As an example, if there is a synonym set up for "denim => jeans" and the user searches for "denim", in the background we will search for "jeans".

Navigation Synonyms

Add a synonym of a navigation item at a local shop level.

Benefits

In the case of navigation items, there may be a lot of use cases for different wording. While a product usually has a given name, a page can be named in very different ways from website to website. Navigation item synonyms allow for you to cover those different wordings.

Guidelines

When you want your users to be able to search for navigation items, make sure to include some synonyms as well. Imagine you have a page called "Shipping", that informs user about expected delivery timelines, delivery cost, etc.

Once you define that navigation item as searchable, consider what synonyms users could also be searching for. An example for a good synonym in this use case would be "Delivery".

If you have an FAQ page, consider adding "Frequently Asked Questions" as a synonym.

Add a Navigation Item Synonym

1. Go to Shops > Country > Storefront > Search > Synonyms.
2. In the NAVIGATION ITEMS section, click + ADD SYNONYM.
3. Click SAVE SYNONYM.

Typo Tolerance

For our previous endpoints /v1/typeahead and /v1/resolve it was allowed to configure the typo tolerance we apply; however, we recommend leaving this with AUTO.

In the new V2 endpoints, /v2/suggestions and /v2/resolve, the setting is not considered anymore. The typo tolerance settings are explained more in detail in the Developer Guide.

Stop Words

In the Words area, you define "stop words". Stop words are those words that occur particularly frequently but do not have much meaning or are used as filler words (for example, "the", "that", "everything", "at", "on" or "in"). By excluding stop words from search queries, the quality of generated search results is increased.

Excluding Categories from Search Results

Benefits

When you exclude a specific category from the search results, they will not be returned through any of our search endpoints. You may use this functionality if, for example, you have a category for VIP products that should not be visible to every user of your shop.

Exclude a Category from Search Results

1. In the SCAYLE Panel, go to Shops > [Shop Name] > Products > Categories.
2. Under GENERAL INFO > Category Configuration, select the Exclude from Search checkbox.
3. Click SAVE.

Result: Once indexers have run, this shop category will not be considered for the search in the Shop Storefront anymore.

Excluding Products from Search Results

Benefits

When you exclude a specific product from the search results, it will not be returned through any of our search endpoints. You may use this functionality if, for example, you have some specific VIP products that should not be visible to every user of your shop.

Exclude a Product from Search Results

1. In the SCAYLE Panel, go to Shops > [Shop Name] > Products and select the product you want to exclude from the search.
2. Under Product > Product Attributes, set the isExcludedFromSearch dropdown to true.
3. Click SAVE.

Result: Once indexers have run, this product will not be considered for the search in the Shop Storefront anymore.

Exact Attribute Search

The Exact Attribute Search enables precise product searches based on specific attributes, such as product IDs. Only products with an exact match on a configured attribute (within a relevant Attribute Group) will be returned by the Storefront API. This functionality is particularly useful for scenarios like ID-based product searches.

Users with the permission shop__additional_settings__exact-attribute-search__edit can view and edit the Attribute Groups considered for Exact Attribute Search.

Only basic advanced Attribute Groups can be selected for this feature. These Attribute Groups must meet the following criteria:

• Configured as advanced.
• Contain only one field of the following types:
  • Text
  • Long Text
  • Numeric

A maximum of 25 Attribute Groups can be configured as relevant for the Exact Attribute Search.

How to Configure Exact Attribute Search

1. Navigate to Global Shop > Storefront > Search Configuration in the SCAYLE Panel.
2. Locate the “Exact Attribute Search” configuration option.
3. Choose the Attribute Groups for exact matching by selecting from the list of eligible groups.

By using this feature, you can enhance the precision of search results in the shop frontend, ensuring users find the exact products they are searching for based on the configured attributes.

Frequently Asked Questions

General

What takes priority if a search term matches both a category and a Product ID?

Our search follows a category-first approach, meaning categories are always prioritized in the results. Next, products are displayed if there is an exact match with one of their searchable IDs. Finally, searchable navigation items are returned.
As an example: the search term "501" may match both, a product with the ID "501", or a category for the well-known jeans model. In that case, we make sure the user is redirected to the category.

Can a search request for a specific Product ID be redirected directly to the Product Detail Page (PDP)?

Yes, this is possible, but it requires proper frontend implementation. Storefront API tries to resolve the Product ID based on the Product ID, Reference Key or EAN if the perfect match is provided. You can add further advanced Attribute Groups to this logic by adding them to the Exact Attribute Search.

My company uses offline catalogs. How can I help my customers to find the products from the offline catalog in our web-store?

If the articles in your offline catalog have Catalog IDs, we recommend adding these to the Specific Attribute Search. Customers can then search for the Catalog ID on your web-store to find the product online. Find out how to add IDs to the Exact Attribute Search here.

Can a Product ID be set up as a synonym for a specific term?

Technically, it is possible to set up a word synonym for a Product ID. However, with the Search V2 endpoints, a perfect match is required for the product search, as no fuzziness is applied.

We use Navigation Items to create content pages like FAQs, Shipping Costs, Size Guides, etc. I read that Navigation Items are supported in the Search V2 endpoints. When set up in the SCAYLE Panel, are they included by default?

If your e-commerce shop already uses Navigation Items and you tag them with the “Include in search” checkmark, they will be available to the new Search V2 endpoints. However, to display them in the front-end search, you must implement additional front-end changes.

I recently updated some search configurations for synonyms in the SCAYLE Panel for my e-commerce shop. When will these changes be visible to users?

The changes won't be applied immediately. However, depending on the client and the size of the shop, it takes between 1 to 3 hours for the changes to become visible to your users.

What technical requirements must be met to implement Search V2 endpoints?

For clients using our NPM packages, the only requirement is to use the @scayle/storefront-api NPM package.

Where can I find more information on configuring search with Search V2 endpoints?

You can refer to the SCAYLE Configuration guidelines or visit our SCAYLE Academy platform, where you can take search courses to enhance your search skills.

Can we choose where to direct the user if there are multiple categories with similar names?

Yes, the best approach is to exclude the categories you don’t want users to find, leaving only the ones you want them to be directed to. You can exclude categories through the configuration settings outlined here.

Why is my search term not resolved to a category page?

The highest priority is to resolve search terms to specific category pages. In case you identify that certain search terms are not resolved to a category page but rather redirected to a search result page, you can take the following actions:
Try to discover the users' intentions when searching for the term. In most cases, the term can be translated to a shop category. For instance, customers searching for “denim” could also refer to “jeans.”
Check whether you maintain a shop category that matches the meaning of the search term. If yes, you can create a category synonym to map further searches with the term to the corresponding category page.
If there is no matching category, you can create one. This is especially recommended when the search term is frequently used.
If the search term is only used a few times, it is also feasible to accept that users are redirected to a search result page. In such cases, we recommend configuring a proper setup of Searchable Attributes.

How can I improve the results on my Result Page?

A search results page should only be shown in exceptional cases, as the goal is to always redirect the user to a matched category page.
Still, the results on the search results page should be of good quality. For that, a good configuration of the Searchable Attributes is key.
Check our configuration guide on how to configure your Searchable Attributes.
Furthermore, you can create word synonyms for products that users may search for with different spellings (for example, Air Max and Airmax). Find out how to create word synonyms here.

How can I improve my search results with compound words?

Compound words are individual words made from two or more words working together. These can be very typical in the German language, for example: "Leinenhose", "Strickjacke", "Kaschmirpullover", or "Rippenhose".
In this case, we recommend creating a word synonym that splits the two words into separate words.
Leinen Hose <= Leinenhose
This will allow our system to correctly identify the category and other attributes in the search term.

In which order do products get returned when two or more products fit a search term identically well?

In that case, the products are ordered by ID (highest to lowest).

What happens if a search term matches both a category name and a productId?

In that case, the product with the matching productId would be returned, as the productId is given more priority.

Configurations

I read that your Search V2 endpoints support boolean filters, such as “New” or “Sale”, in addition to attribute filters. However, when I search for “shoes sale,” I am not redirected to the “Shoes” category with the “Sale” filter applied.

While the Search V2 endpoints do support boolean filters like “Sale” or “New,” proper functionality in the e-commerce shop requires a frontend implementation to handle this use case and redirect the user to the correct URL. In the response body of the Storefront API search endpoints, you will find data on the category and applied filters, which you can use to build frontend logic that forwards the user to the PLP page with the filters applied. Also, note that boolean filters will only be applied if there are products matching both the category and the filters.

Can I set up the same synonym for two different words? Will it work with new Search V2 endpoints? Example: “trousers” & “pants” with synonyms “jeans”

Yes, you can configure this in the Word Synonyms section of the SCAYLE Panel. This configuration works with the new Search V2 endpoints, provided they are implemented according to our guidelines.

Can synonyms be set up for boolean-defined filters? For example, can "sale" be synonymous with "discount"?

Yes, you can set this up in the Word Synonyms section of the SCAYLE Panel. This means that if a user searches for “discount shirts,” the search will behave as if “sale shirts” had been entered.

Can I create a synonym for the overall brand category instead of separate gender-specific ones?

If your shop uses distinct brand categories for different genders, you must set the synonyms for each category individually. For example, setting a synonym for Brands/SCAYLE will not automatically apply to Men/Brands/SCAYLE and Women/Brands/SCAYLE.

Can I configure which filters for a specific category will be considered in the search?

Yes, all filters assigned to a category are considered by the search algorithm. You can add or remove filters as needed, which will determine whether they appear on the category page and in the search results.

I want to be able to search for products and see search results in multiple languages. For example, when searching in the English store for "Hose" (pants in German), will the redirection to the pants category work?

Translations are not supported by default. However, you can implement synonyms for specific categories, attribute groups, or even individual words to handle translations. For instance, setting up "hose" as a category synonym for "pants" will enable the redirection. You can configure various types of synonyms: Category synonyms, attribute group synonyms, word synonyms, and navigation synonyms.

How can I disable Typo Tolerance for number searches, so that users can search for the exact item ID?

When searching for a productId, no typo tolerance is applied. The product is only returned if there is an exact match.

Further education - SCAYLE Academy

Course

The new SCAYLE search

Functionality of the V2 search endpoints

• Search
• Business

Pia Nadolny

Junior Business Consultant

Onsite Search

The new SCAYLE search

• Beginner
• 2 lessons
• 6m

Play tutorial