Guide
Smart Search

Configurations

14min

If you haven't gone through the prerequisites and the v2 structure, please have a look at Overview

There are numerous settings, preferences, and configurations available with APIv2 to fine-tune your search and category merchandising queries. This section explores them in more detail.

Sorting

The default sorting of results is RELEVANCE, which uses Klevu A.I. to determine the order. There are various other options available which you can provide to your customers as required.

This is an example how to set record sorting order.
POST
Request
Body Parameters
RELEVANCE
optional
String
This is the default sort order, which uses a combination of Klevu A.I. and your own merchandising configuration to determine the order of the results.
PRICE_ASC
optional
String
Sort the results in ascending order by the salePrice value of each record.
PRICE_DESC
optional
String
Sort the results in descending order by the salePrice value of each record.
NAME_ASC
optional
String
Sort the results in ascending by the name of each record, in alphabetical order.
NAME_DESC
optional
String
Sort the results in descending by the name of each record, in alphabetical order.
RATING_ASC
optional
String
Sort the results in ascending by each record's average rating, if this data has been indexed in your store.
RATING_DESC
optional
String
Sort the results in descending by each record's average rating, if this data has been indexed in your store.
NEW_ARRIVAL_ASC
optional
String
Sort your records in ascending order based on their published date.
NEW_ARRIVAL_DESC
optional
String
Sort your records in descending order based on their published date.
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Try it here!



Pagination

You may wish to split larger result sets over multiple pages. You can do this using pagination. Simply specify a page size for how many results each page should include, and an offset of which record to start each result set from.

This is an example how to paginate records.
POST
Request
Body Parameters
limit
optional
Integer
Specify the number of records you would like to display per page. If this field is not passed in the API, the default value is 12. You can fetch a maximum of 100 records when you pass the limit. In order to get more than 100 records, you must define the 'fields' in the API.
offset
optional
Integer
Specify the index at which to start counting the number of results from. The index of the first record in a result set is 0. Thus, if you want to start from the 6th result, use an offset of 5.
typeOfSearch
optional
String
After the first has been retrieved, for subsequent pagination requests it is recommended to include the typeOfSearch value using the same value that came back in the meta data with the results of the first result. This will give a performance benefit since Klevu does not need to try different search types, and will also assure consistency of results across pages.
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Understanding response format

Params

Description



noOfResults

The number of results requested to be returned for this query.



totalResultsFound

The total number of results found for this query.



offset

The index of the first result returned in this response.



typeOfSearch

The query type that was executed by Klevu to retrieve the results.



Try it here!



Fields

By default, Klevu will return most of the data available in a record. If you only need certain elements and want to keep the response size small for performance reasons, you can specify only the fields you are interested in.

This is an example how to limit fields/attributes in search response.
POST
Request
Body Parameters
fields
optional
Array
An array of the attribute IDs that you wish to retrieve, eg. "id", "name", "salePrice", etc. Please refer to Searching for Records to see all of the available fields.
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Try it here!



Grouping

The groupBy parameter takes the name of a field indexed in the Klevu Search backend and ensures that there is only one record for each unique value of this field in the search results.

By default, the groupBy operation is performed on the itemGroupId field. When querying for KLEVU_CATEGORY or KLEVU_CMS records, it is recommended to use name as the groupBy parameter value.

This is an example how to group search results.
POST
Request
Body Parameters
groupBy
optional
String
The key of the attribute to group by, for example 'name'. Currently the only supported values are id and name.
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Try it here!



Type of search

The typeOfSearch parameter defines the behaviour when identifying matches for a searched term. For example, whether all or just one of the entered words must be matched, whether to allow spelling mistakes, etc.

This is an example how to change type of search results.
POST
Request
Body Parameters
DEFAULT
optional
String
When this value is specified, Klevu will go through a number of attempts to find matching records. The first type attempted is WILDCARD_AND. If there aren't any results found, Klevu tries to find products with the FUZZY_AND query type. As long as no matches are found, Klevu will continue to fire different query types in the following order: WILDCARD_AND FUZZY_AND WILDCARD_OR FUZZY_OR Note that when a search term only contains a single word, or more than six words, the 'OR' query types will be skipped.
WILDCARD_AND
optional
String
This is an 'AND' query so all words of the query must be found somewhere in a record for it to be included in the results. The last word of the query will have a wildcard suffix appended. For example, if the searched query is "hooded jacket", this will become "hooded jacket*", ie. Klevu will try to find records containing the word "hooded" AND any words beginning with "jacket".
FUZZY_AND
optional
String
This is the same as a WILDCARD_AND query, however a certain amount of 'fuzziness' is allowed to account for spelling mistakes. For example, if the searched query contains spelling mistakes like "hooder jakcet", Klevu will still be able to match any records containing the words "hooded" AND "jacket".
WILDCARD_OR
optional
String
This is an 'OR' query so at least one of the words in the query must be found somewhere in a record for it to be included in the results. The last word of the query will have a wildcard suffix appended. For example, if the searched query is "hooded jacket", this will become "hooded jacket*", ie. Klevu will try to find records containing the word "hooded" OR any words beginning with "jacket".
FUZZY_OR
optional
String
This is the same as a WILDCARD_OR query, however a certain amount of 'fuzziness' is allowed to account for spelling mistakes. For example, if the searched query contains spelling mistakes like "hooder jakcet", Klevu will still be able to match any records containing the words "hooded" OR "jacket".
AND
optional
String
All of the exact words of a query must be found in a record for it to be included in the results. No fuzziness or wildcards are included. For example a search for "hooded jacket" will only return records which contain the exact terms "hooded" AND "jacket".
OR
optional
String
At least one exact word of a query must be found in a record for it to be included in a results. No fuzziness or wildcards are included. For example a search for "hooded jacket" will only return records which contain one of the exact terms "hooded" OR "jacket".
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Try it here!



Preferences

There are a number of preferences available for fine-tuning your queries. For example, you can control whether or not to allow fuzzy search for spelling mistakes on a query by query basis. The available searchPrefs are detailed below.

This is an example how to use different search preferences.
POST
Request
Body Parameters
showOutOfStockProducts
optional
String
Whether or not your store should include 'Out of Stock' products in search results by default can be configured within the Klevu Merchant Centre. However, if you would like to override this for a particular query, please include one of these flags.
hideOutOfStockProducts
optional
String
Flag to hide out-of-stock products.
disableStockSorting
optional
String
This can be used in conjunction with showOutOfStockProducts. If your store is configured to display out of stock products, they will be displayed at the very end of the search results after all in stock products have been displayed. By using this flag you can disable this logic, and cause all products to be ranked in an order that disregards their stock status.
includeStopwords
optional
String
By default, functional words such as prepositions, pronouns, articles, etc. are excluded from searches. Add this flag to include these stopwords in your search.
excludeIds
optional
String
Use this flag to disable the searching of record IDs.
includeDescription
optional
String
Whether or not a record's 'description' is considered for search results can be configured by Klevu Support on a store-by-store basis, however if you would like to override this for a particular query, please include one of these flags.
excludeDescription
optional
String
Use this flag to exclude search in the description.
disableFuzzyMatch
optional
String
This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the FUZZY_AND and FUZZY_OR search types from being attempted.
disableWildcard
optional
String
This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the WILDCARD_AND and WILDCARD_OR search types from being attempted.
disableORSearch
optional
String
This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the WILDCARD_OR and FUZZY_OR search types from being attempted.
partialMatch
optional
String
Enable partial match for the last word of a query, where the last word searched can be a substring of any other word found in a record. This can be useful for non-English languages. For example let's say a product has the name "rödvinsglas" (red wine glass). If searching for "högt glas" (tall glass) it may not match since the record has no words starting with 'glas'. By providing this flag, the search would become "högt *glas*" meaning it would match the record since it contains a word which ends with 'glas'.
partialMatchForAllWords
optional
String
Similar to partialMatch, but for all words rather than just the last. In the same "rödvinsglas" example, a search for "högt glas" would become "*högt* *glas*", so any records containing words containing 'högt' or 'glas' would result in a match.
disableWordShingles
optional
String
For a query longer than one word, all the possible bigrams and trigrams (i.e. formed out of query terms) are looked up in records and the ones having one or more of them are boosted higher up in the search results. You can use this flag to disable such boosting.
searchCompoundsAsAndQuery
optional
String
When a compound word is searched for, i.e. two or more individual words joined together as one word, Klevu automatically disjoints them if the de-compounding feature is enabled for your store. For example, a search for "fairylights" would be treated as "fairy lights", but with the added condition that those words must appear within 5 words of each other in a matching record. If you would prefer that the words "fairy" and "light" could be found anywhere within the record, not necessarily near one another, then please include this flag.
enableBoostingOriginalTermsInSynonyms
optional
String
By default, synonyms are treated equally to their query term. Should you wish to give higher priority to the actual terms your customer entered in the query over their synonyms, please include this flag in your search preferences.
showDisabledFacets
optional
String
It is possible to configure which facets or filters should be enabled or disabled within the Klevu Merchant Centre. By including this flag, all facets will be returned regardless of whether they have been disabled in the KMC.
showFiltersWithSmallCount
optional
String
By default some filters are excluded from the results if they only have a small number of results. Please use this flag to override this logic and include all filters in the response.
includeCategoryFilterInCatNav
optional
String
When the typeOfRequest is 'CATNAV', the filter for 'Category' is automatically excluded since you are already within the context of a category. Use this flag to override this logic and return the category filters even for CatNav requests.
enableScores
optional
String
include the score information with the response fields: klevu_product_boosting and klevu_manual_boosting.
disableGrouping
optional
String
By default, Klevu groups results by itemGroupId. Use this flag to disable the grouping of products.
Request Body (JSON)
PHP
JS
Java
Node.js
Responses
200


Try it here!