Search

How it works

To generate a search results page, execute a Search request and follow these steps:

• Check if a redirect is possible.
• Use the facets from the response to display Facets.
• Use the items from the response to display products.
• Use the configuration to display paging & sorting options.

💡

If you want to display a product lister page, visit the Merchandising section.

Structure

After successfully executing the search request, the reponse XML or JSON response will contain everything you need to generate a search results page. The XML response will have this structure:

• facets: see Facets.
• items: see Items.
• properties: see Properties.
• searchbanners: See Search banners.

<navigation xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <facets>
    <facet>
      <!-- omitted for brevity -->
    </facet>
  </facets>
  <items>
    <item>
      <!-- omitted for brevity -->
    </item>
	</items>
	<properties>
    <nrofitems>4480</nrofitems>
    <pagesize>12</pagesize>
    <nrofpages>374</nrofpages>
    <currentpage>1</currentpage>
    <selectedcategory>100022</selectedcategory>
    <searchterm/>
    <suggestedsearchterm/>
    <isdirectsearch>false</isdirectsearch>
    <isrootcategory>false</isrootcategory>
    <pageurl>?tn_cid=100022&tn_sort=Aanbevolen</pageurl>
    <reseturl>?tn_cid=100022</reseturl>
    <sortfields>
      <!-- omitted for brevity -->
    </sortfields>
    <redirects>
      <!-- omitted for brevity -->
    </redirects>
  </properties>
</navigation>

Facets

To implement facets, read our guide on Facets.

Items

To implement items, go to Items.

Properties

• nrofitems, pagesize, nrofpages and currentpage: see Paging.
• selectedcategory: the currently selected category. This is the value of the tn_cid parameter. In case of a category path it's the last one in the list (e.g. for tn_cid=100022-100021968 the value is 100021968 ).
• searchterm: the current searchterm.
• suggestedsearchterm: suggested searchterm for a follow-up search request.
• isdirectsearch: indicator for a pure direct search. true when there is:
  • a searchterm
  • one category selected
  • no active sortoption (defaulting to recommended)
• isrootcategory: indicates if the current category is the root category.
• pageurl: current request url without paging properties.
• reseturl: a predefined request url to easily reset all selected facets, sorting and paging.

Redirects

If the properties.redirects contains one or more <url> properties, use any of those, to redirect to that value.

For example, searching for sale could result in a server-side redirect to /sale/:

<navigation xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <facets>
    <!-- omitted for brevity -->
  </facets>
  <items>
    <!-- omitted for brevity -->
	</items>
	<properties>
    <!-- omitted for brevity -->
    <redirects>
      <url>/sale/</url>
    </redirects>
  </properties>
</navigation>

Banners

A search response can contain search banners. A promotional piece that can be displayed related to a search term. Multiple banners can be returned, depending on the configuration. The banners for mobile & desktop are returned as seperate entries.

<navigation xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <facets>
    <!-- omitted for brevity -->
  </facets>
  <items>
    <!-- omitted for brevity -->
	</items>
	<properties>
    <!-- omitted for brevity -->
  </properties>
  <searchbanners>
    <searchbanner>
      <imageurl>https://www.tweakwise.com/images/banner-editor.png</imageurl>
      <clickurl>https://www.tweakwise.com/</clickurl>
      <clicktarget>_blank</clicktarget>
      <type>Desktop</type>
      <location>ContainerTop</location>
      <categorieid>1000</categorieid>
    </searchbanner>
    <searchbanner>
      <imageurl>https://www.tweakwise.com/images/banner-promo.png</imageurl>
      <clickurl>https://www.tweakwise.com/</clickurl>
      <clicktarget>_blank</clicktarget>
      <type>Mobile</type>
      <location>ListTop</location>
      <categorieid>1000</categorieid>
    </searchbanner>
  </searchbanners>
</navigation>

There are a couple of reserved locations that can be used:

• Container top: on top of the page, full container width.
• List top: above the page title, not container width.
• Products top: above the products.

If using API implementation, you can give any meaning to these values. To see how this could be interpreted, see our support article: How do I set up a new search banner?.

Sorting

To support different ways of sorting (or ordering) of items, go to Sorting, ordering and paging.

Paging

To implement paging, go to Sorting, ordering and paging.

Language

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

Overrides

To override default values or specific app configuration, go to Override App Configuration.

💡

Need even more control?

In general, the response times of our endpoints are so fast we can provide both facets and products in a single response. This makes a traditional implementation of search and/or merchandising easy.

If you want even more control or want to squeeze the last piece of performance, take a look at the Facets and Products endpoints.