StatusSupport
Developers
Tweakwise.comTweakwise AppContact

Suggestions

The Endpoint Formerly Known as Autocomplete

Enhancing your webshop's search functionality with dynamic suggestions can greatly improve the user experience. This guide will walk you through the steps to implement this feature, allowing users to see relevant suggestions in real-time as they type in the search bar.

Suggestion types

Suggestion results are grouped by different types (impression below):

  1. Search Phrase Suggestion in a Category: Displaying search query suggestions within popular categories is a great way to guide visitors.
    For example, 'coffee' under kitchen appliances or 'Brabantia' under trash bins.
  2. Search Phrase Suggestions: As users type in the search bar, display suggestions to help them find what they’re looking for without the need to type the entire query.
    For example: A user types 'red', and suggestions like 'red dress', 'red tunic', and 'red shirt' appear.
  3. Category suggestions: Category suggestions quickly lead visitors to a well-filtered results page.
    For example: a user types 'sho', and suggestions like 'shorts', 'shoulder pads', or 'shoes' appear.
  4. Attribute suggestions: filter search results based on specific attributes. This method is ideal for suggesting brands or other specific attributes.
    For example: A user types 'Bra', and suggestions like 'Braun' and 'Brabantia' appear.
  5. Products
    Product suggestions allow visitors to select a specific product directly from the search bar.
    For example: A user types 'iPhone', and specific models of iPhones appear as suggestions.
Different types of suggestions in action

Different types of suggestions in action

How it works

To actually get suggestions while typing, execute Suggestions and Suggestion products.

For regular suggestions, this will result in XML or JSON result containing groups of different type of suggestions:

<suggestionGroups xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <group>
        <name>Zoeksuggesties</name>
        <type>SearchPhrase</type>
        <suggestions><!-- omitted for brevity --></suggestions>
    </group>
    <group>
        <name>Categorieën</name>
        <type>Category</type>
        <suggestions><!-- omitted for brevity --></suggestions>
    </group>
    <group>
        <name>Attributes</name>
        <type>FacetFilter</type>
        <suggestions><!-- omitted for brevity --></suggestions>
    </group>
</suggestionGroups>

For product suggestions, go to Products.

Recommendations:

  • Request Throttling / Debounce input events to prevent unnecessary requests.
  • Cancel running requests: if the user is typing, make sure you only display the latest request.

Implementation

The implementation of a suggestion should be done using the configuration in the suggestion object:

  • match: use this to display the actual suggestion text
  • navigationLink
    • path: we generate an example URL for you, to demonstrate what navigation-search url could be generated & executed when selecting the suggestion.
    • context.searchterm: contextual information on what searchterm the suggestion is found
    • context.category: see Category context.
    • context.facetfilters: see Facet filters.
  • redirects: see Redirects.

Simple

A simple suggestion when searching for 'bag'. The match or context.searchterm can be used to generate a link to the search page in your platform: 

<group>
  <name>Suggestions</name>
  <type>SearchPhrase</type>
  <suggestions>  
    <suggestion>
      <match>burkely bag</match>
      <navigationLink>
        <path><![CDATA[ /navigation-search/5eb8cbb7?tn_q=burkely%20bag ]]></path>
        <context>
          <searchterm>burkely bag</searchterm>
        </context>
      </navigationLink>
      <redirects/>
    </suggestion>
  </suggestions>
</group>

<a href="/search?q=burkely+bag">
  burkely bag
</a>

Category context

Search Phrase Suggestion in a Category and Category suggestions provide contextual information on how to display the category related to the suggestion:

  • context.category.path: the category id & path upwards
  • context.category.name: the category name

The searchterm and path can be used to generate a link to a search page in your platform that has the category pre-selected:

<group>
  <name>Categories</name>
  <type>Category</type>
  <suggestions>  
    <suggestion>
      <match>Bags</match>
      <navigationLink>
        <path><![CDATA[ /navigation/5eb8cbb7?tn_cid=6001000-60010060 ]]></path>
        <context>
          <category>
            <path>6001000-60010060</path>
            <name>Bags</name>
          </category>
        </context>
      </navigationLink>
    </suggestion>
  </suggestions>
</group>

<a href="/search?q=burkely+bag&tn_cid=6001000-60010060">
  Bags
</a>

Alternative: the category path can be used to match to a category in your platform to generate the correct user (and SEO) friendly category URL. In this case, category id 60010060 corresponds to the /bags URL:

<a href="/bags/">Bags</a>

Nested context

Every autocomplete instance is connected to a category. In addition, a category has a template configured. If a template has a category facet configured as tree, the suggestions will use the tree on that template to build relevant category context.

In that case, we also supply the parent category so that can be displayed as well:

<group>
  <name>Categories</name>
  <type>Category</type>
  <suggestions>  
    <suggestion>
      <match>Fashion</match>
      <navigationLink>
        <path><![CDATA[ /navigation/5eb8cbb7?tn_cid=6001000-60010060 ]]></path>
        <context>
          <category>
            <path>6001000-60010060</path>
            <name>Fashion</name>
            <parentPath>1-6001000</parentPath>
            <parentName>Bags</parentName>
          </category>
        </context>
      </navigationLink>
    </suggestion>
  </suggestions>
</group>

<a href="/bags/fashion/">
  Fashion in <em>Bags</em>
</a>

💡

To learn how to configure Autocomplete, read our product guide How do I set up Autocomplete?

Facet filters

The filters can be used to construct a navigation link in your platform. For example use ae-brand to display a link to the specific brand page (<a href="/burkely/">Burkely</a>): 

<group>
  <name>Merk</name>
  <type>FacetFilter</type>
  <suggestions>
    <suggestion>
      <match>Burkely</match>
      <navigationLink>
        <path><![CDATA[ /navigation/4f6fd484?tn_cid=1&tn_fk_ae_brand=Burkely ]]></path>
        <context>
          <category>
            <path>1</path>
          </category>
          <facetFilters>
            <filter>
              <key>ae_brand</key>
              <values>
                <value>Burkely</value>
              </values>
            </filter>
          </facetFilters>
        </context>
      </navigationLink>
    </suggestion>
  </suggestions>
</group>

<a href="/burkely/">
  Burkely
</a>

Redirects

A suggestion can also contain redirects. This will allow you to redirect to a specific URL based on a search suggestion.
For example, searching for sale would result in a redirect match on /sale/ (<a href="/sale/">Sale</a>):

<group>
  <name>Suggestions</name>
  <type>SearchPhrase</type>
	<suggestions>  
    <suggestion>
      <match>Sale</match>
      <navigationLink>
        <path><![CDATA[ /navigation-search/19564673?tn_q=Sale ]]></path>
        <context>
        	<searchterm>Sale</searchterm>
        </context>
      </navigationLink>
      <redirects>
        <redirect>
        	<url>/sale/</url>
        </redirect>
      </redirects>
    </suggestion>
  </suggestions>
</group>

<a href="/sale/">
  Sale
</a>

💡

Multiple redirect url's are possible, our recommendation is to pick the first

Products

To get product suggestions, execute an additional request to Suggestion products.
The result of the product suggestions are similar to the items in navigation requests: 

<suggestions xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <name>Product suggesties</name>
  <items>
    <item>
      <itemno>60010017891001</itemno>
      <title>Charm London South Bank Schoudertas zwart</title>
      <price>17.9</price>
      <brand>Charm</brand>
      <image>https://media.travelbags-cdn.nl/product-square-320/342253/image.jpg</image>
      <url i:nil="true"/>
      <attributes/>
    </item>
    <item>
      <itemno>6001001843-20</itemno>
      <title>Travelite Meet Backpack navy</title>
      <price>55.9</price>
      <brand>Travelite</brand>
      <image>https://media.travelbags-cdn.nl/product-square-320/427765/image.jpg</image>
      <url i:nil="true"/>
      <attributes/>      
    </item>
  </items>
</suggestions>

The items can be directly rendered using the available information. If more information is required, the data can be retrieved in the platform using the itemno: this is the item identifier known by Tweakwise.

Language

To specify what language should be used, go to Language Support.