Examples
19 min
If you haven't gone through the prerequisites and the v2 structure, please have a look at Overview
Custom Record Type
In addition to Products, Categories and CMS Pages, Klevu APIv2 allows you to search for custom entities.
For example, if you want to display results for recipes, articles or physical stores within your search you can do so by utilising the typeOfRecords parameter.
Custom Record type
This is an example how to search for custom record type.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- typeOfRecordsArrayrequiredDescription
Request Body (JSON)
{
"recordQueries": [
{
"id": "customeEntitySearch1",
"settings": {
"query": {
"term": "fish"
},
"limit": 1,
"typeOfRecords": [
"ACME_RECIPE"
],
"fields": [
"id",
"name",
"typeOfRecord"
]
}
},
{
"id": "customeEntitySearch2",
"settings": {
"query": {
"term": "london"
},
"limit": 1,
"typeOfRecords": [
"ACME-STORE"
],
"fields": [
"id",
"name",
"typeOfRecord"
]
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"id": "customeEntitySearch1",
"settings": {
"query": {
"term": "fish"
},
"limit": 1,
"typeOfRecords": [
"ACME_RECIPE"
],
"fields": [
"id",
"name",
"typeOfRecord"
]
}
},
{
"id": "customeEntitySearch2",
"settings": {
"query": {
"term": "london"
},
"limit": 1,
"typeOfRecords": [
"ACME-STORE"
],
"fields": [
"id",
"name",
"typeOfRecord"
]
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"id":"customeEntitySearch1","settings":{"query":{"term":"fish"},"limit":1,"typeOfRecords":["ACME_RECIPE"],"fields":["id","name","typeOfRecord"]}},{"id":"customeEntitySearch2","settings":{"query":{"term":"london"},"limit":1,"typeOfRecords":["ACME-STORE"],"fields":["id","name","typeOfRecord"]}}],"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"id\": \"customeEntitySearch1\",\n \"settings\": {\n \"query\": {\n \"term\": \"fish\"\n },\n \"limit\": 1,\n \"typeOfRecords\": [\n \"ACME_RECIPE\"\n ],\n \"fields\": [\n \"id\",\n \"name\",\n \"typeOfRecord\"\n ]\n }\n },\n {\n \"id\": \"customeEntitySearch2\",\n \"settings\": {\n \"query\": {\n \"term\": \"london\"\n },\n \"limit\": 1,\n \"typeOfRecords\": [\n \"ACME-STORE\"\n ],\n \"fields\": [\n \"id\",\n \"name\",\n \"typeOfRecord\"\n ]\n }\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"id":"customeEntitySearch1","settings":{"query":{"term":"fish"},"limit":1,"typeOfRecords":["ACME_RECIPE"],"fields":["id","name","typeOfRecord"]}},{"id":"customeEntitySearch2","settings":{"query":{"term":"london"},"limit":1,"typeOfRecords":["ACME-STORE"],"fields":["id","name","typeOfRecord"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 8,
"responseCode": 200
},
"queryResults": [
{
"id": "customeEntitySearch1",
"meta": {
"qTime": 5,
"noOfResults": 1,
"totalResultsFound": 2,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "fish",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Recipe: Fish and Chips",
"klevu_category": "ACME_RECIPE @ku@kuCategory@ku@",
"id": "recipe_1",
"typeOfRecord": "ACME_RECIPE"
}
],
"filters": []
},
{
"id": "customeEntitySearch2",
"meta": {
"qTime": 7,
"noOfResults": 1,
"totalResultsFound": 1,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "london",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Shop: London",
"klevu_category": "ACME-STORE @ku@kuCategory@ku@",
"id": "shop_2",
"typeOfRecord": "ACME-STORE"
}
],
"filters": []
}
]
}Try it here
Multiple Queries
Klevu APIv2 allows you to request multiple Product, Category, CMS Pages and Custom Entity queries all at the same time. All of these queries are usually fired simultaneously, meaning the total time taken is the duration of the slowest query, rather than the total of all queries.
In the example to the right, a single HTTP request is returning:
- 3x search suggestions
- 3x categories
- 5x products with filters
- 3x different products without filters
- 5x cms pages or recipes (a custom entity)
- 1x store (a custom entity)
Furthermore, all of the configuration and preferences found within this documentation can be applied to each and evey query separately, making an extremely powerful and fast way to display search results.
Multiple Queries
This is an example how to search for multiple queries.
POST
https://{{hostname}}/cs/v2/search
Request Body (JSON)
{
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
},
"suggestions": [
{
"id": "suggestionSearch",
"typeOfQuery": "AUTO_SUGGESTIONS",
"query": "a",
"limit": 3
}
],
"recordQueries": [
{
"id": "categorySearch",
"settings": {
"query": {
"term": "a"
},
"limit": 3,
"typeOfRecords": [
"KLEVU_CATEGORY"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "productSearch1",
"settings": {
"query": {
"term": "a"
},
"limit": 5,
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name"
]
},
"filters": {
"filtersToReturn": {
"enabled": true
}
}
},
{
"id": "productSearch2",
"settings": {
"query": {
"term": "b"
},
"limit": 3,
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "cmsAndRecipeSearch",
"settings": {
"query": {
"term": "a"
},
"limit": 5,
"typeOfRecords": [
"KLEVU_CMS",
"ACME_RECIPE"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "storeSearch",
"settings": {
"query": {
"term": "a"
},
"limit": 1,
"typeOfRecords": [
"ACME-STORE"
],
"fields": [
"id",
"name"
]
}
}
]
}
php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
},
"suggestions": [
{
"id": "suggestionSearch",
"typeOfQuery": "AUTO_SUGGESTIONS",
"query": "a",
"limit": 3
}
],
"recordQueries": [
{
"id": "categorySearch",
"settings": {
"query": {
"term": "a"
},
"limit": 3,
"typeOfRecords": [
"KLEVU_CATEGORY"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "productSearch1",
"settings": {
"query": {
"term": "a"
},
"limit": 5,
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name"
]
},
"filters": {
"filtersToReturn": {
"enabled": true
}
}
},
{
"id": "productSearch2",
"settings": {
"query": {
"term": "b"
},
"limit": 3,
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "cmsAndRecipeSearch",
"settings": {
"query": {
"term": "a"
},
"limit": 5,
"typeOfRecords": [
"KLEVU_CMS",
"ACME_RECIPE"
],
"fields": [
"id",
"name"
]
}
},
{
"id": "storeSearch",
"settings": {
"query": {
"term": "a"
},
"limit": 1,
"typeOfRecords": [
"ACME-STORE"
],
"fields": [
"id",
"name"
]
}
}
]
}
',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"context":{"apiKeys":["klevu-156925593843210765"]},"suggestions":[{"id":"suggestionSearch","typeOfQuery":"AUTO_SUGGESTIONS","query":"a","limit":3}],"recordQueries":[{"id":"categorySearch","settings":{"query":{"term":"a"},"limit":3,"typeOfRecords":["KLEVU_CATEGORY"],"fields":["id","name"]}},{"id":"productSearch1","settings":{"query":{"term":"a"},"limit":5,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]},"filters":{"filtersToReturn":{"enabled":true}}},{"id":"productSearch2","settings":{"query":{"term":"b"},"limit":3,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]}},{"id":"cmsAndRecipeSearch","settings":{"query":{"term":"a"},"limit":5,"typeOfRecords":["KLEVU_CMS","ACME_RECIPE"],"fields":["id","name"]}},{"id":"storeSearch","settings":{"query":{"term":"a"},"limit":1,"typeOfRecords":["ACME-STORE"],"fields":["id","name"]}}]});
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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n },\n \"suggestions\": [\n {\n \"id\": \"suggestionSearch\",\n \"typeOfQuery\": \"AUTO_SUGGESTIONS\",\n \"query\": \"a\",\n \"limit\": 3\n }\n ],\n \"recordQueries\": [\n {\n \"id\": \"categorySearch\",\n \"settings\": {\n \"query\": {\n \"term\": \"a\"\n },\n \"limit\": 3,\n \"typeOfRecords\": [\n \"KLEVU_CATEGORY\"\n ],\n \"fields\": [\n \"id\",\n \"name\"\n ]\n }\n },\n {\n \"id\": \"productSearch1\",\n \"settings\": {\n \"query\": {\n \"term\": \"a\"\n },\n \"limit\": 5,\n \"typeOfRecords\": [\n \"KLEVU_PRODUCT\"\n ],\n \"fields\": [\n \"id\",\n \"name\"\n ]\n },\n \"filters\": {\n \"filtersToReturn\": {\n \"enabled\": true\n }\n }\n },\n {\n \"id\": \"productSearch2\",\n \"settings\": {\n \"query\": {\n \"term\": \"b\"\n },\n \"limit\": 3,\n \"typeOfRecords\": [\n \"KLEVU_PRODUCT\"\n ],\n \"fields\": [\n \"id\",\n \"name\"\n ]\n }\n },\n {\n \"id\": \"cmsAndRecipeSearch\",\n \"settings\": {\n \"query\": {\n \"term\": \"a\"\n },\n \"limit\": 5,\n \"typeOfRecords\": [\n \"KLEVU_CMS\",\n \"ACME_RECIPE\"\n ],\n \"fields\": [\n \"id\",\n \"name\"\n ]\n }\n },\n {\n \"id\": \"storeSearch\",\n \"settings\": {\n \"query\": {\n \"term\": \"a\"\n },\n \"limit\": 1,\n \"typeOfRecords\": [\n \"ACME-STORE\"\n ],\n \"fields\": [\n \"id\",\n \"name\"\n ]\n }\n }\n ]\n}\n");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"context":{"apiKeys":["klevu-156925593843210765"]},"suggestions":[{"id":"suggestionSearch","typeOfQuery":"AUTO_SUGGESTIONS","query":"a","limit":3}],"recordQueries":[{"id":"categorySearch","settings":{"query":{"term":"a"},"limit":3,"typeOfRecords":["KLEVU_CATEGORY"],"fields":["id","name"]}},{"id":"productSearch1","settings":{"query":{"term":"a"},"limit":5,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]},"filters":{"filtersToReturn":{"enabled":true}}},{"id":"productSearch2","settings":{"query":{"term":"b"},"limit":3,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name"]}},{"id":"cmsAndRecipeSearch","settings":{"query":{"term":"a"},"limit":5,"typeOfRecords":["KLEVU_CMS","ACME_RECIPE"],"fields":["id","name"]}},{"id":"storeSearch","settings":{"query":{"term":"a"},"limit":1,"typeOfRecords":["ACME-STORE"],"fields":["id","name"]}}]})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 21,
"responseCode": 200
},
"suggestionResults": [
{
"id": "suggestionSearch",
"suggestions": [
{
"suggest": "<b>a</b>tomic"
},
{
"suggest": "<b>a</b>tomic endurance"
},
{
"suggest": "<b>a</b>tomic endurance running"
}
]
}
],
"queryResults": [
{
"id": "categorySearch",
"meta": {
"qTime": 8,
"noOfResults": 3,
"totalResultsFound": 1,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "a",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Accessories",
"id": "category_156704342078"
}
],
"filters": []
},
{
"id": "productSearch1",
"meta": {
"qTime": 14,
"noOfResults": 5,
"totalResultsFound": 447,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "a",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Affirm Water Bottle",
"id": "31366498222142"
},
{
"name": "Cruise Dual Analog Watch",
"id": "31366496124990"
},
{
"name": "Ariel Roll Sleeve Sweatshirt",
"id": "31366458376254"
},
{
"name": "Livingston All-Purpose Tight",
"id": "31366468010046"
},
{
"name": "Livingston All-Purpose Tight",
"id": "31366467977278"
}
],
"filters": [
{
"key": "tags",
"label": "Tags",
"type": "OPTIONS",
"options": [
{
"count": 192,
"name": "machine",
"value": "machine",
"selected": false
},
{
"count": 143,
"name": "comfortable",
"value": "comfortable",
"selected": false
},
{
"count": 120,
"name": "comfort",
"value": "comfort",
"selected": false
},
{
"count": 116,
"name": "winter",
"value": "winter",
"selected": false
},
{
"count": 106,
"name": "cotton",
"value": "cotton",
"selected": false
},
{
"count": 80,
"name": "Hoodie",
"value": "Hoodie",
"selected": false
},
{
"count": 77,
"name": "Flexible",
"value": "Flexible",
"selected": false
},
{
"count": 76,
"name": "Cold-whether",
"value": "Cold-whether",
"selected": false
},
{
"count": 67,
"name": "Short",
"value": "Short",
"selected": false
},
{
"count": 62,
"name": "royal",
"value": "royal",
"selected": false
}
]
},
{
"key": "category",
"label": "category",
"type": "OPTIONS",
"options": [
{
"count": 83,
"name": "Hoodies & Sweatshirts",
"value": "Hoodies & Sweatshirts",
"selected": false
},
{
"count": 81,
"name": "Jackets",
"value": "Jackets",
"selected": false
},
{
"count": 77,
"name": "Pants",
"value": "Pants",
"selected": false
},
{
"count": 71,
"name": "Smart Collection 1",
"value": "Smart Collection 1",
"selected": false
},
{
"count": 69,
"name": "Tees",
"value": "Tees",
"selected": false
},
{
"count": 68,
"name": "Shorts",
"value": "Shorts",
"selected": false
},
{
"count": 59,
"name": "Smart Collection 3",
"value": "Smart Collection 3",
"selected": false
},
{
"count": 53,
"name": "Hoodies",
"value": "Hoodies",
"selected": false
},
{
"count": 42,
"name": "Bras & Tanks",
"value": "Bras & Tanks",
"selected": false
},
{
"count": 39,
"name": "Tanks",
"value": "Tanks",
"selected": false
}
]
},
{
"key": "size",
"label": "Size",
"type": "OPTIONS",
"options": [
{
"count": 143,
"name": "Small",
"value": "Small",
"selected": false
},
{
"count": 141,
"name": "Medium",
"value": "Medium",
"selected": false
},
{
"count": 140,
"name": "Large",
"value": "Large",
"selected": false
},
{
"count": 9,
"name": "Free Size",
"value": "Free Size",
"selected": false
},
{
"count": 3,
"name": "S",
"value": "S",
"selected": false
},
{
"count": 2,
"name": "XL",
"value": "XL",
"selected": false
},
{
"count": 2,
"name": "XXL",
"value": "XXL",
"selected": false
},
{
"count": 2,
"name": "medium",
"value": "medium",
"selected": false
}
]
},
{
"key": "brand",
"label": "brand",
"type": "OPTIONS",
"options": [
{
"count": 169,
"name": "KSD",
"value": "KSD",
"selected": false
},
{
"count": 144,
"name": "MNH",
"value": "MNH",
"selected": false
},
{
"count": 138,
"name": "KKE",
"value": "KKE",
"selected": false
},
{
"count": 7,
"name": "Klevu Search Demo",
"value": "Klevu Search Demo",
"selected": false
},
{
"count": 1,
"name": "KKE New",
"value": "KKE New",
"selected": false
}
]
},
{
"key": "type",
"label": "Type",
"type": "OPTIONS",
"options": [
{
"count": 83,
"name": "Hoodies & Sweatshirts",
"value": "Hoodies & Sweatshirts",
"selected": false
},
{
"count": 77,
"name": "Pants",
"value": "Pants",
"selected": false
},
{
"count": 69,
"name": "Tees",
"value": "Tees",
"selected": false
},
{
"count": 68,
"name": "Shorts",
"value": "Shorts",
"selected": false
},
{
"count": 62,
"name": "Jackets",
"value": "Jackets",
"selected": false
},
{
"count": 42,
"name": "Bras & Tanks",
"value": "Bras & Tanks",
"selected": false
},
{
"count": 18,
"name": "Tanks",
"value": "Tanks",
"selected": false
},
{
"count": 14,
"name": "Bags",
"value": "Bags",
"selected": false
},
{
"count": 10,
"name": "Fitness Equipment",
"value": "Fitness Equipment",
"selected": false
},
{
"count": 9,
"name": "Watches",
"value": "Watches",
"selected": false
}
]
},
{
"key": "salePrice",
"label": "salePrice",
"type": "OPTIONS",
"options": [
{
"count": 47,
"name": "29.00",
"value": "29.00",
"selected": false
},
{
"count": 35,
"name": "39.00",
"value": "39.00",
"selected": false
},
{
"count": 26,
"name": "32.00",
"value": "32.00",
"selected": false
},
{
"count": 24,
"name": "42.00",
"value": "42.00",
"selected": false
},
{
"count": 22,
"name": "24.00",
"value": "24.00",
"selected": false
},
{
"count": 22,
"name": "28.00",
"value": "28.00",
"selected": false
},
{
"count": 20,
"name": "48.00",
"value": "48.00",
"selected": false
},
{
"count": 17,
"name": "45.00",
"value": "45.00",
"selected": false
},
{
"count": 16,
"name": "57.00",
"value": "57.00",
"selected": false
},
{
"count": 14,
"name": "49.00",
"value": "49.00",
"selected": false
}
]
}
]
},
{
"id": "productSearch2",
"meta": {
"qTime": 10,
"noOfResults": 3,
"totalResultsFound": 419,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "b",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Wayfarer Messenger Bag",
"id": "31366499991614"
},
{
"name": "Prima Compete Bra Top",
"id": "31366445826110"
},
{
"name": "Lucia Cross-Fit Bra",
"id": "31366444220478"
}
],
"filters": []
},
{
"id": "cmsAndRecipeSearch",
"meta": {
"qTime": 10,
"noOfResults": 5,
"totalResultsFound": 7,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "a",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Recipe: Fish and Chips",
"id": "recipe_1"
},
{
"name": "About Us",
"id": "page_47677767742"
},
{
"name": "Recipe: Fish & Chips",
"id": "page_50756288574"
},
{
"name": "Recipe: Fish Pie",
"id": "page_51008929854"
},
{
"name": "Recipe: Fish Pie",
"id": "recipe_2"
}
],
"filters": []
},
{
"id": "storeSearch",
"meta": {
"qTime": 10,
"noOfResults": 1,
"totalResultsFound": 2,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "a",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Shop: London",
"id": "shop_2"
}
],
"filters": []
}
]
}Try it here!
Fallback Queries
Sometimes customers will search for something which yields few or no results.
In this scenario, you can either present your customer with a 'no results found' message, or you can use the result of another query to show some records which they may be interested in.
We call this a fallback query.
Any query flagged as isFallbackQuery: true will not execute unless certain criteria are met. With this approach you can present customers with alternative results, without needing to make any additional HTTP requests, and also without the jeopardising performance of the initial query.
Fallback Queries
This is an example how to fetch results as a part of fall back queries.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- fallbackQueryIdstringrequiredDescription
- fallbackWhenCountLessThanIntegerDescription
- isFallbackQueryBooleanDescription
Request Body (JSON)
{
"recordQueries": [
{
"id": "myInitialQuery",
"settings": {
"query": {
"term": "short"
},
"typeOfSearch": "WILDCARD_AND",
"fallbackQueryId": "myFallbackQuery",
"fallbackWhenCountLessThan": 3
}
},
{
"id": "myFallbackQuery",
"isFallbackQuery": true,
"settings": {
"query": {
"term": "short"
},
"typeOfSearch": "FUZZY_OR"
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"id": "myInitialQuery",
"settings": {
"query": {
"term": "short"
},
"typeOfSearch": "WILDCARD_AND",
"fallbackQueryId": "myFallbackQuery",
"fallbackWhenCountLessThan": 3
}
},
{
"id": "myFallbackQuery",
"isFallbackQuery": true,
"settings": {
"query": {
"term": "short"
},
"typeOfSearch": "FUZZY_OR"
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"id":"myInitialQuery","settings":{"query":{"term":"short"},"typeOfSearch":"WILDCARD_AND","fallbackQueryId":"myFallbackQuery","fallbackWhenCountLessThan":3}},{"id":"myFallbackQuery","isFallbackQuery":true,"settings":{"query":{"term":"short"},"typeOfSearch":"FUZZY_OR"}}],"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"id\": \"myInitialQuery\",\n \"settings\": {\n \"query\": {\n \"term\": \"short\"\n },\n \"typeOfSearch\": \"WILDCARD_AND\",\n \"fallbackQueryId\": \"myFallbackQuery\",\n \"fallbackWhenCountLessThan\": 3\n }\n },\n {\n \"id\": \"myFallbackQuery\",\n \"isFallbackQuery\": true,\n \"settings\": {\n \"query\": {\n \"term\": \"short\"\n },\n \"typeOfSearch\": \"FUZZY_OR\"\n }\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"id":"myInitialQuery","settings":{"query":{"term":"short"},"typeOfSearch":"WILDCARD_AND","fallbackQueryId":"myFallbackQuery","fallbackWhenCountLessThan":3}},{"id":"myFallbackQuery","isFallbackQuery":true,"settings":{"query":{"term":"short"},"typeOfSearch":"FUZZY_OR"}}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 15,
"responseCode": 200
},
"queryResults": [
{
"id": "myInitialQuery",
"meta": {
"qTime": 12,
"noOfResults": 12,
"totalResultsFound": 105,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "short",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384016334910",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "45.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-green_main_3ac6ebe5-2c3e-45cf-91cf-ec54de5e5e3a_medium.jpg?v=1575477721",
"currency": "GBP",
"inStock": "yes",
"id": "31366431146046",
"imageHover": "",
"sku": "WSH12-28-Green",
"brand": "KSD",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-green_main_3ac6ebe5-2c3e-45cf-91cf-ec54de5e5e3a_medium.jpg?v=1575477721",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "45.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-green",
"tags": "body-hugging, Green, nylon, Running, Short",
"size": "Small",
"name": "Erika Running Short",
"shortDesc": "A great short with a body-hugging design, the Erika Running Short is perfect for runners who prefer a fitted short rather than the traditional baggy variety. • Seafoam pattern running shorts. • Elastic waistband. • Snug fit. • 4''",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384016269374",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "45.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-purple_main_c57ce41e-7b0e-4cd2-a0de-18ddb6d2017a_medium.jpg?v=1575477720",
"currency": "GBP",
"inStock": "yes",
"id": "31366431080510",
"imageHover": "",
"sku": "WSH12-28-Purple",
"brand": "KSD",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-purple_main_c57ce41e-7b0e-4cd2-a0de-18ddb6d2017a_medium.jpg?v=1575477720",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "45.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-purple",
"tags": "body-hugging, nylon, Red, Running, Short",
"size": "Large",
"name": "Erika Running Short",
"shortDesc": "A great short with a body-hugging design, the Erika Running Short is perfect for runners who prefer a fitted short rather than the traditional baggy variety. • Seafoam pattern running shorts. • Elastic waistband. • Snug fit. • 4''",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384016203838",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "45.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-red_main_9999e03f-694d-4f0c-83ab-8c0200029275_medium.jpg?v=1575477719",
"currency": "GBP",
"inStock": "yes",
"id": "31366431014974",
"imageHover": "",
"sku": "WSH12-28-Red",
"brand": "KSD",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-red_main_9999e03f-694d-4f0c-83ab-8c0200029275_medium.jpg?v=1575477719",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "45.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-red",
"tags": "body-hugging, nylon, Red, Running, Short",
"size": "Medium",
"name": "Erika Running Short",
"shortDesc": "A great short with a body-hugging design, the Erika Running Short is perfect for runners who prefer a fitted short rather than the traditional baggy variety. • Seafoam pattern running shorts. • Elastic waistband. • Snug fit. • 4''",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384040386622",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "32.50",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh03-black_main_a8796b84-9c70-4146-9c73-2295b0d260a7_medium.jpg?v=1575478122",
"currency": "GBP",
"inStock": "yes",
"id": "31366465781822",
"imageHover": "",
"sku": "MSH03-32-Black",
"brand": "KKE",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh03-black_main_a8796b84-9c70-4146-9c73-2295b0d260a7_medium.jpg?v=1575478122",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "32.5",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/meteor-workout-short-black",
"tags": "black, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Small",
"name": "Meteor Workout Short",
"shortDesc": "Step into the Meteor Workout Short for an incredibly lightweight fitness experience. Its breathable construction and an inner brief provide additional comfort and support, while the adjustable waistband offers the perfect fit to take you to the fi",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384039665726",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "29.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-gray_main_0f869cff-09fb-403a-a209-cf092f4d3c1a_medium.jpg?v=1575478112",
"currency": "GBP",
"inStock": "yes",
"id": "31366465060926",
"imageHover": "",
"sku": "MSH05-32-Gray",
"brand": "KSD",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-gray_main_0f869cff-09fb-403a-a209-cf092f4d3c1a_medium.jpg?v=1575478112",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "29.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-gray",
"tags": "Gray, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Medium",
"name": "Hawkeye Yoga Short",
"shortDesc": "What more do you need than a sporty yoga short made with organic cotton and a little spandex for mobility? The Hawkeye Yoga Short brings a stylish, standard fit you can sport with confidence outside the studio. • Dark gray shorts with red a",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384037830718",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "27.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-black_main_2ef78733-04a5-4345-9f5f-992d0cfffe8d_medium.jpg?v=1575478090",
"currency": "GBP",
"inStock": "yes",
"id": "31366462472254",
"imageHover": "",
"sku": "MSH12-32-Black",
"brand": "KKE",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-black_main_2ef78733-04a5-4345-9f5f-992d0cfffe8d_medium.jpg?v=1575478090",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "27.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-black",
"tags": "Black, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Small",
"name": "Pierce Gym Short",
"shortDesc": "The Pierce Gym Short is similar to our Arcadio Gym Short, but designed with a fitted, tapered look. A flat waistband with an adjustable drawstring adds comfort, with zippered pockets for safe, easy storage. • Dark red cotton shorts. • 8",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384039796798",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "29.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-black_main_f61ee526-b9d3-4eaa-b7b2-80dc400f31b0_medium.jpg?v=1575478115",
"currency": "GBP",
"inStock": "yes",
"id": "31366465191998",
"imageHover": "",
"sku": "MSH05-32-Black",
"brand": "KKE",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-black_main_f61ee526-b9d3-4eaa-b7b2-80dc400f31b0_medium.jpg?v=1575478115",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "29.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-black",
"tags": "Black, Machine, motion-friendly, Nylon, Relaxed fit, Smooth, Summer, yoga-short",
"size": "Small",
"name": "Hawkeye Yoga Short",
"shortDesc": "What more do you need than a sporty yoga short made with organic cotton and a little spandex for mobility? The Hawkeye Yoga Short brings a stylish, standard fit you can sport with confidence outside the studio. • Dark gray shorts with red a",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384039731262",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "29.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-blue_main_2130114d-06b0-4793-8fc2-bf77411297e4_medium.jpg?v=1575478114",
"currency": "GBP",
"inStock": "yes",
"id": "31366465126462",
"imageHover": "",
"sku": "MSH05-32-Blue",
"brand": "MNH",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-blue_main_2130114d-06b0-4793-8fc2-bf77411297e4_medium.jpg?v=1575478114",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "29.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-blue",
"tags": "Blue, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Large",
"name": "Hawkeye Yoga Short",
"shortDesc": "What more do you need than a sporty yoga short made with organic cotton and a little spandex for mobility? The Hawkeye Yoga Short brings a stylish, standard fit you can sport with confidence outside the studio. • Dark gray shorts with red a",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384037765182",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "27.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-gray_main_4bb28c53-a928-47a0-92ea-ecd303f97dba_medium.jpg?v=1575478089",
"currency": "GBP",
"inStock": "yes",
"id": "31366462439486",
"imageHover": "",
"sku": "MSH12-32-Gray",
"brand": "MNH",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-gray_main_4bb28c53-a928-47a0-92ea-ecd303f97dba_medium.jpg?v=1575478089",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "27.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-gray",
"tags": "Gray, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Large",
"name": "Pierce Gym Short",
"shortDesc": "The Pierce Gym Short is similar to our Arcadio Gym Short, but designed with a fitted, tapered look. A flat waistband with an adjustable drawstring adds comfort, with zippered pockets for safe, easy storage. • Dark red cotton shorts. • 8",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384037699646",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "27.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-red_main_6c29f610-d5f7-4e1a-bde4-1fb148964be5_medium.jpg?v=1575478088",
"currency": "GBP",
"inStock": "yes",
"id": "31366462373950",
"imageHover": "",
"sku": "MSH12-32-Red",
"brand": "KSD",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-red_main_6c29f610-d5f7-4e1a-bde4-1fb148964be5_medium.jpg?v=1575478088",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "27.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-red",
"tags": "Cotton, Machine, Relaxed fit, Res, Short, Summer",
"size": "Medium",
"name": "Pierce Gym Short",
"shortDesc": "The Pierce Gym Short is similar to our Arcadio Gym Short, but designed with a fitted, tapered look. A flat waistband with an adjustable drawstring adds comfort, with zippered pockets for safe, easy storage. • Dark red cotton shorts. • 8",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384038322238",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "32.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-blue_main_774a1fbb-9eab-4d4f-9261-f1e0c028b492_medium.jpg?v=1575478097",
"currency": "GBP",
"inStock": "yes",
"id": "31366463094846",
"imageHover": "",
"sku": "MSH10-32-Blue",
"brand": "KKE",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-blue_main_774a1fbb-9eab-4d4f-9261-f1e0c028b492_medium.jpg?v=1575478097",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "32.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/sol-active-short-blue",
"tags": "Blue, Machine, Navy polyster, Relaxed fit, Short, Summer",
"size": "Small",
"name": "Sol Active Short",
"shortDesc": "You'll let your fear go and push your limits in your new Sol Active Short. Featuring ultra-breathable performance fabric and a flat comfort-fit waistband, the Sol Active Short is perfect for high-intensity circuits or high-heat bikram. • Li",
"category": "Shorts"
},
{
"discount": "",
"hideGroupPrices": "",
"type": "Shorts",
"itemGroupId": "4384038256702",
"freeShipping": "",
"storeBaseCurrency": "GBP",
"price": "32.00",
"toPrice": "",
"imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-green_main_18d664f2-5ba2-421d-b89a-87cb73d86416_medium.jpg?v=1575478095",
"currency": "GBP",
"inStock": "yes",
"id": "31366463029310",
"imageHover": "",
"sku": "MSH10-32-Green",
"brand": "MNH",
"startPrice": "",
"image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-green_main_18d664f2-5ba2-421d-b89a-87cb73d86416_medium.jpg?v=1575478095",
"deliveryInfo": "",
"hideAddToCart": "",
"salePrice": "32.0",
"swatchesInfo": "",
"weight": "",
"klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
"totalVariants": 0,
"groupPrices": "",
"url": "https://jsv2-shopify-demo.ksearchmisc.com/products/sol-active-short-green",
"tags": "Green, Machine, Nylon, Relaxed fit, Short, Summer",
"size": "Large",
"name": "Sol Active Short",
"shortDesc": "You'll let your fear go and push your limits in your new Sol Active Short. Featuring ultra-breathable performance fabric and a flat comfort-fit waistband, the Sol Active Short is perfect for high-intensity circuits or high-heat bikram. • Li",
"category": "Shorts"
}
],
"filters": []
}
]
}Try it here!
Hand-Picked Products
Sometimes merchants want to take control over which records are included or excluded, or whether certain records should always take precedence over others.
This can be done via query-time manual merchandising.
Hand-picked Queries
This is an example how to merchandise search results using APIs.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- topIdsArrayrequiredDescription
- includeIdsArrayDescription
- excludeIdsArrayDescription
Request Body (JSON)
{
"recordQueries": [
{
"settings": {
"topIds": [
{
"key": "id",
"value": "31366496223294"
},
{
"key": "itemGroupId",
"value": "4384052412478"
}
],
"includeIds": [
{
"key": "id",
"value": "31366496223294"
}
],
"excludeIds": [
{
"key": "id",
"value": "31366451953726"
}
],
"query": {
"term": "short"
},
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name",
"itemGroupId"
],
"limit": 10
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"settings": {
"topIds": [
{
"key": "id",
"value": "31366496223294"
},
{
"key": "itemGroupId",
"value": "4384052412478"
}
],
"includeIds": [
{
"key": "id",
"value": "31366496223294"
}
],
"excludeIds": [
{
"key": "id",
"value": "31366451953726"
}
],
"query": {
"term": "short"
},
"typeOfRecords": [
"KLEVU_PRODUCT"
],
"fields": [
"id",
"name",
"itemGroupId"
],
"limit": 10
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"settings":{"topIds":[{"key":"id","value":"31366496223294"},{"key":"itemGroupId","value":"4384052412478"}],"includeIds":[{"key":"id","value":"31366496223294"}],"excludeIds":[{"key":"id","value":"31366451953726"}],"query":{"term":"short"},"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name","itemGroupId"],"limit":10},"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"settings\": {\n \"topIds\": [\n {\n \"key\": \"id\",\n \"value\": \"31366496223294\"\n },\n {\n \"key\": \"itemGroupId\",\n \"value\": \"4384052412478\"\n }\n ],\n \"includeIds\": [\n {\n \"key\": \"id\",\n \"value\": \"31366496223294\"\n }\n ],\n \"excludeIds\": [\n {\n \"key\": \"id\",\n \"value\": \"31366451953726\"\n }\n ],\n \"query\": {\n \"term\": \"short\"\n },\n \"typeOfRecords\": [\n \"KLEVU_PRODUCT\"\n ],\n \"fields\": [\n \"id\",\n \"name\",\n \"itemGroupId\"\n ],\n \"limit\": 10\n },\n \"id\": \"productSearch\"\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"settings":{"topIds":[{"key":"id","value":"31366496223294"},{"key":"itemGroupId","value":"4384052412478"}],"includeIds":[{"key":"id","value":"31366496223294"}],"excludeIds":[{"key":"id","value":"31366451953726"}],"query":{"term":"short"},"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name","itemGroupId"],"limit":10},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 12,
"responseCode": 200
},
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 8,
"noOfResults": 10,
"totalResultsFound": 105,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "short",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "Summit Watch",
"id": "31366496223294",
"itemGroupId": "4384059031614"
},
{
"name": "Erika Running Short",
"id": "31366431146046",
"itemGroupId": "4384016334910"
},
{
"name": "Erika Running Short",
"id": "31366431014974",
"itemGroupId": "4384016203838"
},
{
"name": "Erika Running Short",
"id": "31366431080510",
"itemGroupId": "4384016269374"
},
{
"name": "Meteor Workout Short",
"id": "31366465781822",
"itemGroupId": "4384040386622"
},
{
"name": "Hawkeye Yoga Short",
"id": "31366465191998",
"itemGroupId": "4384039796798"
},
{
"name": "Hawkeye Yoga Short",
"id": "31366465060926",
"itemGroupId": "4384039665726"
},
{
"name": "Hawkeye Yoga Short",
"id": "31366465126462",
"itemGroupId": "4384039731262"
},
{
"name": "Pierce Gym Short",
"id": "31366462439486",
"itemGroupId": "4384037765182"
},
{
"name": "Pierce Gym Short",
"id": "31366462373950",
"itemGroupId": "4384037699646"
}
],
"filters": []
}
]
}Try it here!
Custom Queries
DEPRECATED: The use of customANDQuery is being deprecated. For better control over custom queries please review and use Advanced Filtering
You can even write your own custom queries with Klevu search, to take more control over your results. The example to the right shows how you can build a query to filter results by Small or Medium records which are NOT brand "KKE."
Custom Queries
This is an example how to merchandise search results using APIs.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- customANDQueryStringrequiredDescription
Request Body (JSON)
{
"recordQueries": [
{
"settings": {
"customANDQuery": "(size:\"Small\" OR size:\"Medium\") AND -(brand:\"KKE\")",
"fields": [
"id",
"name",
"size",
"brand"
],
"limit": 10
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"settings": {
"customANDQuery": "(size:\\"Small\\" OR size:\\"Medium\\") AND -(brand:\\"KKE\\")",
"fields": [
"id",
"name",
"size",
"brand"
],
"limit": 10
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"settings":{"customANDQuery":"(size:\"Small\" OR size:\"Medium\") AND -(brand:\"KKE\")","fields":["id","name","size","brand"],"limit":10},"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"settings\": {\n \"customANDQuery\": \"(size:\\\"Small\\\" OR size:\\\"Medium\\\") AND -(brand:\\\"KKE\\\")\",\n \"fields\": [\n \"id\",\n \"name\",\n \"size\",\n \"brand\"\n ],\n \"limit\": 10\n },\n \"id\": \"productSearch\"\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"settings":{"customANDQuery":"(size:\"Small\" OR size:\"Medium\") AND -(brand:\"KKE\")","fields":["id","name","size","brand"],"limit":10},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 7,
"responseCode": 200
},
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 5,
"noOfResults": 10,
"totalResultsFound": 209,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "*",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"size": "Small",
"name": "Stellar Solar Jacket",
"id": "31366456541246",
"brand": "KSD"
},
{
"size": "Small",
"name": "Lando Gym Jacket",
"id": "31366487441470",
"brand": "KSD"
},
{
"size": "Small",
"name": "Ingrid Running Jacket",
"id": "31366455590974",
"brand": "MNH"
},
{
"size": "Small",
"name": "Josie Yoga Jacket",
"id": "31366456279102",
"brand": "KSD"
},
{
"size": "Medium",
"name": "Hollister Backyard Sweatshirt",
"id": "31366493438014",
"brand": "MNH"
},
{
"size": "Medium",
"name": "Erika Running Short",
"id": "31366431014974",
"brand": "KSD"
},
{
"size": "Small",
"name": "Stellar Solar Jacket",
"id": "31366456672318",
"brand": "MNH"
},
{
"size": "Small",
"name": "Neve Studio Dance Jacket",
"id": "31366453461054",
"brand": "MNH"
},
{
"size": "Small",
"name": "Augusta Pullover Jacket",
"id": "31366455820350",
"brand": "KSD"
},
{
"size": "Small",
"name": "Augusta Pullover Jacket",
"id": "31366455951422",
"brand": "MNH"
}
],
"filters": []
}
]
}Try it here!
Multiple Currencies
If your store has multiple currencies and you would like to show different values based on the currency your customer is currently viewing, this can be achieved using the priceFieldSuffix parameter.
When specifying a value for priceFieldSuffix, the following fields in your response data will be replaced with the value indexed with Klevu for the corresponding currency:
- price
- salePrice
- currency
Multi-currency
This is an example how to fetch prices for specific currency.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- priceFieldSuffixStringrequiredDescription
Request Body (JSON)
{
"recordQueries": [
{
"settings": {
"priceFieldSuffix": "USD",
"query": {
"term": "short"
},
"fields": [
"id",
"name",
"price",
"salePrice",
"currency",
"storeCurrency"
],
"limit": 1,
"typeOfRecords": [
"KLEVU_PRODUCT"
]
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"settings": {
"priceFieldSuffix": "USD",
"query": {
"term": "short"
},
"fields": [
"id",
"name",
"price",
"salePrice",
"currency",
"storeCurrency"
],
"limit": 1,
"typeOfRecords": [
"KLEVU_PRODUCT"
]
},
"id": "productSearch"
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"settings":{"priceFieldSuffix":"USD","query":{"term":"short"},"fields":["id","name","price","salePrice","currency","storeCurrency"],"limit":1,"typeOfRecords":["KLEVU_PRODUCT"]},"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"settings\": {\n \"priceFieldSuffix\": \"USD\",\n \"query\": {\n \"term\": \"short\"\n },\n \"fields\": [\n \"id\",\n \"name\",\n \"price\",\n \"salePrice\",\n \"currency\",\n \"storeCurrency\"\n ],\n \"limit\": 1,\n \"typeOfRecords\": [\n \"KLEVU_PRODUCT\"\n ]\n },\n \"id\": \"productSearch\"\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"settings":{"priceFieldSuffix":"USD","query":{"term":"short"},"fields":["id","name","price","salePrice","currency","storeCurrency"],"limit":1,"typeOfRecords":["KLEVU_PRODUCT"]},"id":"productSearch"}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 7,
"responseCode": 200
},
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 5,
"noOfResults": 1,
"totalResultsFound": 104,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 2,
"searchedTerm": "short",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [
{
"storeBaseCurrency": "GBP",
"salePrice": "45.00",
"price": "45.00",
"name": "Erika Running Short",
"currency": "GBP",
"id": "31366431146046"
}
],
"filters": []
}
]
}Try it here!
Customer Groups
A common B2B requirement is different product visibility and prices based on a customer group. With Klevu APIv2 you can specify parameters to filter out products which a particular customer should not see, and also show them specific prices if they differ from the base price.
When specifying a value for priceFieldSuffix, the following fields in your response data will be replaced with the value indexed with Klevu for the corresponding currency and group:
- price
- salePrice
- currency
When specifying a value for visibilityGroupID, any records that do not belong to that group will be excluded from the results.
In the example to the right, the same product is indexed with data for currencies 'GBP' and 'USD'. It's visibility is set to groups 'my_group_1' and 'my_group_3', but not 'my_group_2'.
Customer Groups
This is an example how to fetch prices specific to customer groups.
POST
https://{{hostname}}/cs/v2/search
Body Parameters
- priceFieldSuffixStringrequiredDescription
- visibilityGroupID stringDescription
Request Body (JSON)
{
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"priceFieldSuffix": "USD-my_group_3",
"visibilityGroupID": "my_group_3",
"query": {
"term": "short"
},
"fields": [
"id",
"name",
"price",
"salePrice",
"currency",
"storeCurrency"
],
"limit": 1,
"typeOfRecords": [
"KLEVU_PRODUCT"
]
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}php
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://eucs15v2.ksearchnet.com/cs/v2/search',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"priceFieldSuffix": "USD-my_group_3",
"visibilityGroupID": "my_group_3",
"query": {
"term": "short"
},
"fields": [
"id",
"name",
"price",
"salePrice",
"currency",
"storeCurrency"
],
"limit": 1,
"typeOfRecords": [
"KLEVU_PRODUCT"
]
}
}
],
"context": {
"apiKeys": [
"klevu-156925593843210765"
]
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
javascript
var data = JSON.stringify({"recordQueries":[{"id":"productSearch","typeOfRequest":"SEARCH","settings":{"priceFieldSuffix":"USD-my_group_3","visibilityGroupID":"my_group_3","query":{"term":"short"},"fields":["id","name","price","salePrice","currency","storeCurrency"],"limit":1,"typeOfRecords":["KLEVU_PRODUCT"]}}],"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);java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"recordQueries\": [\n {\n \"id\": \"productSearch\",\n \"typeOfRequest\": \"SEARCH\",\n \"settings\": {\n \"priceFieldSuffix\": \"USD-my_group_3\",\n \"visibilityGroupID\": \"my_group_3\",\n \"query\": {\n \"term\": \"short\"\n },\n \"fields\": [\n \"id\",\n \"name\",\n \"price\",\n \"salePrice\",\n \"currency\",\n \"storeCurrency\"\n ],\n \"limit\": 1,\n \"typeOfRecords\": [\n \"KLEVU_PRODUCT\"\n ]\n }\n }\n ],\n \"context\": {\n \"apiKeys\": [\n \"klevu-156925593843210765\"\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://eucs15v2.ksearchnet.com/cs/v2/search")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();nodejs
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://eucs15v2.ksearchnet.com/cs/v2/search',
'headers': {
'Content-Type': 'application/json'
},
body: JSON.stringify({"recordQueries":[{"id":"productSearch","typeOfRequest":"SEARCH","settings":{"priceFieldSuffix":"USD-my_group_3","visibilityGroupID":"my_group_3","query":{"term":"short"},"fields":["id","name","price","salePrice","currency","storeCurrency"],"limit":1,"typeOfRecords":["KLEVU_PRODUCT"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
200
{
"meta": {
"qTime": 33,
"responseCode": 200
},
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 31,
"noOfResults": 1,
"totalResultsFound": 0,
"typeOfSearch": "FUZZY_OR",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "short",
"apiKey": "klevu-156925593843210765",
"isPersonalised": false
},
"records": [],
"filters": []
}
]
}Try it here