Configurations
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.
var data = JSON.stringify({"recordQueries":[{"settings":{"sort":"NAME_ASC","query":{"term":"short"},"fields":["id","name","rating","salePrice","score"]},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);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.
var data = JSON.stringify({"recordQueries":[{"settings":{"limit":5,"offset":4,"typeOfSearch":"WILDCARD_AND","query":{"term":"short"},"fields":["id","name"]},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);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.
var data = JSON.stringify({"recordQueries":[{"settings":{"fields":["id","name","salePrice"],"query":{"term":"short"}},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);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.
var data = JSON.stringify({"recordQueries":[{"settings":{"groupBy":"name","query":{"term":"Adrienne Trek Jacket"},"sort":"NAME_ASC","fields":["id","name"]},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);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.
var data = JSON.stringify({"recordQueries":[{"settings":{"typeOfSearch":"FUZZY_OR","query":{"term":"short"},"fields":["id","name"]},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);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.
var data = JSON.stringify({"recordQueries":[{"settings":{"searchPrefs":["showOutOfStockProducts","disableStockSorting","includeStopwords","excludeIds","includeDescription","disableFuzzyMatch","disableWildcard","disableORSearch","partialMatch","partialMatchForAllWords","disableWordShingles","searchCompoundsAsAndQuery","enableBoostingOriginalTermsInSynonyms","showDisabledFacets","showFiltersWithSmallCount","includeCategoryFilterInCatNav","enableScores","debugQuery","disableGrouping"],"query":{"term":"short"}},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}});
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);Try it here!