Guide
Smart Search
Examples
19min
If you haven't gone through the prerequisites and the v2 structure, please have a look at Overview
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.
This is an example how to search for custom record type.
POST
Request
Body Parameters
typeOfRecords
required
Array
Specify the identifier(s) of your custom entity types that you have indexed with Klevu, for example ACME_RECIPE or ACME-STORE.
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 8,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "customeEntitySearch1",
9 "meta": {
10 "qTime": 5,
11 "noOfResults": 1,
12 "totalResultsFound": 2,
13 "typeOfSearch": "WILDCARD_AND",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 1,
17 "searchedTerm": "fish",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [
22 {
23 "name": "Recipe: Fish and Chips",
24 "klevu_category": "ACME_RECIPE @ku@kuCategory@ku@",
25 "id": "recipe_1",
26 "typeOfRecord": "ACME_RECIPE"
27 }
28 ],
29 "filters": []
30 },
31 {
32 "id": "customeEntitySearch2",
33 "meta": {
34 "qTime": 7,
35 "noOfResults": 1,
36 "totalResultsFound": 1,
37 "typeOfSearch": "WILDCARD_AND",
38 "offset": 0,
39 "debuggingInformation": {},
40 "notificationCode": 1,
41 "searchedTerm": "london",
42 "apiKey": "klevu-156925593843210765",
43 "isPersonalised": false
44 },
45 "records": [
46 {
47 "name": "Shop: London",
48 "klevu_category": "ACME-STORE @ku@kuCategory@ku@",
49 "id": "shop_2",
50 "typeOfRecord": "ACME-STORE"
51 }
52 ],
53 "filters": []
54 }
55 ]
56}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=customRecordType"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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.
This is an example how to search for multiple queries.
POST
Request
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}}]});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 21,
4 "responseCode": 200
5 },
6 "suggestionResults": [
7 {
8 "id": "suggestionSearch",
9 "suggestions": [
10 {
11 "suggest": "<b>a</b>tomic"
12 },
13 {
14 "suggest": "<b>a</b>tomic endurance"
15 },
16 {
17 "suggest": "<b>a</b>tomic endurance running"
18 }
19 ]
20 }
21 ],
22 "queryResults": [
23 {
24 "id": "categorySearch",
25 "meta": {
26 "qTime": 8,
27 "noOfResults": 3,
28 "totalResultsFound": 1,
29 "typeOfSearch": "WILDCARD_AND",
30 "offset": 0,
31 "debuggingInformation": {},
32 "notificationCode": 1,
33 "searchedTerm": "a",
34 "apiKey": "klevu-156925593843210765",
35 "isPersonalised": false
36 },
37 "records": [
38 {
39 "name": "Accessories",
40 "id": "category_156704342078"
41 }
42 ],
43 "filters": []
44 },
45 {
46 "id": "productSearch1",
47 "meta": {
48 "qTime": 14,
49 "noOfResults": 5,
50 "totalResultsFound": 447,
51 "typeOfSearch": "WILDCARD_AND",
52 "offset": 0,
53 "debuggingInformation": {},
54 "notificationCode": 1,
55 "searchedTerm": "a",
56 "apiKey": "klevu-156925593843210765",
57 "isPersonalised": false
58 },
59 "records": [
60 {
61 "name": "Affirm Water Bottle",
62 "id": "31366498222142"
63 },
64 {
65 "name": "Cruise Dual Analog Watch",
66 "id": "31366496124990"
67 },
68 {
69 "name": "Ariel Roll Sleeve Sweatshirt",
70 "id": "31366458376254"
71 },
72 {
73 "name": "Livingston All-Purpose Tight",
74 "id": "31366468010046"
75 },
76 {
77 "name": "Livingston All-Purpose Tight",
78 "id": "31366467977278"
79 }
80 ],
81 "filters": [
82 {
83 "key": "tags",
84 "label": "Tags",
85 "type": "OPTIONS",
86 "options": [
87 {
88 "count": 192,
89 "name": "machine",
90 "value": "machine",
91 "selected": false
92 },
93 {
94 "count": 143,
95 "name": "comfortable",
96 "value": "comfortable",
97 "selected": false
98 },
99 {
100 "count": 120,
101 "name": "comfort",
102 "value": "comfort",
103 "selected": false
104 },
105 {
106 "count": 116,
107 "name": "winter",
108 "value": "winter",
109 "selected": false
110 },
111 {
112 "count": 106,
113 "name": "cotton",
114 "value": "cotton",
115 "selected": false
116 },
117 {
118 "count": 80,
119 "name": "Hoodie",
120 "value": "Hoodie",
121 "selected": false
122 },
123 {
124 "count": 77,
125 "name": "Flexible",
126 "value": "Flexible",
127 "selected": false
128 },
129 {
130 "count": 76,
131 "name": "Cold-whether",
132 "value": "Cold-whether",
133 "selected": false
134 },
135 {
136 "count": 67,
137 "name": "Short",
138 "value": "Short",
139 "selected": false
140 },
141 {
142 "count": 62,
143 "name": "royal",
144 "value": "royal",
145 "selected": false
146 }
147 ]
148 },
149 {
150 "key": "category",
151 "label": "category",
152 "type": "OPTIONS",
153 "options": [
154 {
155 "count": 83,
156 "name": "Hoodies & Sweatshirts",
157 "value": "Hoodies & Sweatshirts",
158 "selected": false
159 },
160 {
161 "count": 81,
162 "name": "Jackets",
163 "value": "Jackets",
164 "selected": false
165 },
166 {
167 "count": 77,
168 "name": "Pants",
169 "value": "Pants",
170 "selected": false
171 },
172 {
173 "count": 71,
174 "name": "Smart Collection 1",
175 "value": "Smart Collection 1",
176 "selected": false
177 },
178 {
179 "count": 69,
180 "name": "Tees",
181 "value": "Tees",
182 "selected": false
183 },
184 {
185 "count": 68,
186 "name": "Shorts",
187 "value": "Shorts",
188 "selected": false
189 },
190 {
191 "count": 59,
192 "name": "Smart Collection 3",
193 "value": "Smart Collection 3",
194 "selected": false
195 },
196 {
197 "count": 53,
198 "name": "Hoodies",
199 "value": "Hoodies",
200 "selected": false
201 },
202 {
203 "count": 42,
204 "name": "Bras & Tanks",
205 "value": "Bras & Tanks",
206 "selected": false
207 },
208 {
209 "count": 39,
210 "name": "Tanks",
211 "value": "Tanks",
212 "selected": false
213 }
214 ]
215 },
216 {
217 "key": "size",
218 "label": "Size",
219 "type": "OPTIONS",
220 "options": [
221 {
222 "count": 143,
223 "name": "Small",
224 "value": "Small",
225 "selected": false
226 },
227 {
228 "count": 141,
229 "name": "Medium",
230 "value": "Medium",
231 "selected": false
232 },
233 {
234 "count": 140,
235 "name": "Large",
236 "value": "Large",
237 "selected": false
238 },
239 {
240 "count": 9,
241 "name": "Free Size",
242 "value": "Free Size",
243 "selected": false
244 },
245 {
246 "count": 3,
247 "name": "S",
248 "value": "S",
249 "selected": false
250 },
251 {
252 "count": 2,
253 "name": "XL",
254 "value": "XL",
255 "selected": false
256 },
257 {
258 "count": 2,
259 "name": "XXL",
260 "value": "XXL",
261 "selected": false
262 },
263 {
264 "count": 2,
265 "name": "medium",
266 "value": "medium",
267 "selected": false
268 }
269 ]
270 },
271 {
272 "key": "brand",
273 "label": "brand",
274 "type": "OPTIONS",
275 "options": [
276 {
277 "count": 169,
278 "name": "KSD",
279 "value": "KSD",
280 "selected": false
281 },
282 {
283 "count": 144,
284 "name": "MNH",
285 "value": "MNH",
286 "selected": false
287 },
288 {
289 "count": 138,
290 "name": "KKE",
291 "value": "KKE",
292 "selected": false
293 },
294 {
295 "count": 7,
296 "name": "Klevu Search Demo",
297 "value": "Klevu Search Demo",
298 "selected": false
299 },
300 {
301 "count": 1,
302 "name": "KKE New",
303 "value": "KKE New",
304 "selected": false
305 }
306 ]
307 },
308 {
309 "key": "type",
310 "label": "Type",
311 "type": "OPTIONS",
312 "options": [
313 {
314 "count": 83,
315 "name": "Hoodies & Sweatshirts",
316 "value": "Hoodies & Sweatshirts",
317 "selected": false
318 },
319 {
320 "count": 77,
321 "name": "Pants",
322 "value": "Pants",
323 "selected": false
324 },
325 {
326 "count": 69,
327 "name": "Tees",
328 "value": "Tees",
329 "selected": false
330 },
331 {
332 "count": 68,
333 "name": "Shorts",
334 "value": "Shorts",
335 "selected": false
336 },
337 {
338 "count": 62,
339 "name": "Jackets",
340 "value": "Jackets",
341 "selected": false
342 },
343 {
344 "count": 42,
345 "name": "Bras & Tanks",
346 "value": "Bras & Tanks",
347 "selected": false
348 },
349 {
350 "count": 18,
351 "name": "Tanks",
352 "value": "Tanks",
353 "selected": false
354 },
355 {
356 "count": 14,
357 "name": "Bags",
358 "value": "Bags",
359 "selected": false
360 },
361 {
362 "count": 10,
363 "name": "Fitness Equipment",
364 "value": "Fitness Equipment",
365 "selected": false
366 },
367 {
368 "count": 9,
369 "name": "Watches",
370 "value": "Watches",
371 "selected": false
372 }
373 ]
374 },
375 {
376 "key": "salePrice",
377 "label": "salePrice",
378 "type": "OPTIONS",
379 "options": [
380 {
381 "count": 47,
382 "name": "29.00",
383 "value": "29.00",
384 "selected": false
385 },
386 {
387 "count": 35,
388 "name": "39.00",
389 "value": "39.00",
390 "selected": false
391 },
392 {
393 "count": 26,
394 "name": "32.00",
395 "value": "32.00",
396 "selected": false
397 },
398 {
399 "count": 24,
400 "name": "42.00",
401 "value": "42.00",
402 "selected": false
403 },
404 {
405 "count": 22,
406 "name": "24.00",
407 "value": "24.00",
408 "selected": false
409 },
410 {
411 "count": 22,
412 "name": "28.00",
413 "value": "28.00",
414 "selected": false
415 },
416 {
417 "count": 20,
418 "name": "48.00",
419 "value": "48.00",
420 "selected": false
421 },
422 {
423 "count": 17,
424 "name": "45.00",
425 "value": "45.00",
426 "selected": false
427 },
428 {
429 "count": 16,
430 "name": "57.00",
431 "value": "57.00",
432 "selected": false
433 },
434 {
435 "count": 14,
436 "name": "49.00",
437 "value": "49.00",
438 "selected": false
439 }
440 ]
441 }
442 ]
443 },
444 {
445 "id": "productSearch2",
446 "meta": {
447 "qTime": 10,
448 "noOfResults": 3,
449 "totalResultsFound": 419,
450 "typeOfSearch": "WILDCARD_AND",
451 "offset": 0,
452 "debuggingInformation": {},
453 "notificationCode": 1,
454 "searchedTerm": "b",
455 "apiKey": "klevu-156925593843210765",
456 "isPersonalised": false
457 },
458 "records": [
459 {
460 "name": "Wayfarer Messenger Bag",
461 "id": "31366499991614"
462 },
463 {
464 "name": "Prima Compete Bra Top",
465 "id": "31366445826110"
466 },
467 {
468 "name": "Lucia Cross-Fit Bra",
469 "id": "31366444220478"
470 }
471 ],
472 "filters": []
473 },
474 {
475 "id": "cmsAndRecipeSearch",
476 "meta": {
477 "qTime": 10,
478 "noOfResults": 5,
479 "totalResultsFound": 7,
480 "typeOfSearch": "WILDCARD_AND",
481 "offset": 0,
482 "debuggingInformation": {},
483 "notificationCode": 1,
484 "searchedTerm": "a",
485 "apiKey": "klevu-156925593843210765",
486 "isPersonalised": false
487 },
488 "records": [
489 {
490 "name": "Recipe: Fish and Chips",
491 "id": "recipe_1"
492 },
493 {
494 "name": "About Us",
495 "id": "page_47677767742"
496 },
497 {
498 "name": "Recipe: Fish & Chips",
499 "id": "page_50756288574"
500 },
501 {
502 "name": "Recipe: Fish Pie",
503 "id": "page_51008929854"
504 },
505 {
506 "name": "Recipe: Fish Pie",
507 "id": "recipe_2"
508 }
509 ],
510 "filters": []
511 },
512 {
513 "id": "storeSearch",
514 "meta": {
515 "qTime": 10,
516 "noOfResults": 1,
517 "totalResultsFound": 2,
518 "typeOfSearch": "WILDCARD_AND",
519 "offset": 0,
520 "debuggingInformation": {},
521 "notificationCode": 1,
522 "searchedTerm": "a",
523 "apiKey": "klevu-156925593843210765",
524 "isPersonalised": false
525 },
526 "records": [
527 {
528 "name": "Shop: London",
529 "id": "shop_2"
530 }
531 ],
532 "filters": []
533 }
534 ]
535}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=multipleQueries"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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.
This is an example how to fetch results as a part of fall back queries.
POST
Request
Body Parameters
fallbackQueryId
required
String
The ID of another query which should be fired if the current query yields too few results.
fallbackWhenCountLessThan
optional
Integer
Use this parameter to specify the criteria for when a fallback query will be fired. For example, if you would like a fallback query to fire when you have two results or less, specify a value of '3'.
isFallbackQuery
optional
Boolean
Specify a value of true for any queries that should not be executed until some particular criteria are met, in another query. It is not possible for a fallback query to have its own fallback query.
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 15,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "myInitialQuery",
9 "meta": {
10 "qTime": 12,
11 "noOfResults": 12,
12 "totalResultsFound": 105,
13 "typeOfSearch": "WILDCARD_AND",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 1,
17 "searchedTerm": "short",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [
22 {
23 "discount": "",
24 "hideGroupPrices": "",
25 "type": "Shorts",
26 "itemGroupId": "4384016334910",
27 "freeShipping": "",
28 "storeBaseCurrency": "GBP",
29 "price": "45.00",
30 "toPrice": "",
31 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-green_main_3ac6ebe5-2c3e-45cf-91cf-ec54de5e5e3a_medium.jpg?v=1575477721",
32 "currency": "GBP",
33 "inStock": "yes",
34 "id": "31366431146046",
35 "imageHover": "",
36 "sku": "WSH12-28-Green",
37 "brand": "KSD",
38 "startPrice": "",
39 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-green_main_3ac6ebe5-2c3e-45cf-91cf-ec54de5e5e3a_medium.jpg?v=1575477721",
40 "deliveryInfo": "",
41 "hideAddToCart": "",
42 "salePrice": "45.0",
43 "swatchesInfo": "",
44 "weight": "",
45 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
46 "totalVariants": 0,
47 "groupPrices": "",
48 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-green",
49 "tags": "body-hugging, Green, nylon, Running, Short",
50 "size": "Small",
51 "name": "Erika Running Short",
52 "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''",
53 "category": "Shorts"
54 },
55 {
56 "discount": "",
57 "hideGroupPrices": "",
58 "type": "Shorts",
59 "itemGroupId": "4384016269374",
60 "freeShipping": "",
61 "storeBaseCurrency": "GBP",
62 "price": "45.00",
63 "toPrice": "",
64 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-purple_main_c57ce41e-7b0e-4cd2-a0de-18ddb6d2017a_medium.jpg?v=1575477720",
65 "currency": "GBP",
66 "inStock": "yes",
67 "id": "31366431080510",
68 "imageHover": "",
69 "sku": "WSH12-28-Purple",
70 "brand": "KSD",
71 "startPrice": "",
72 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-purple_main_c57ce41e-7b0e-4cd2-a0de-18ddb6d2017a_medium.jpg?v=1575477720",
73 "deliveryInfo": "",
74 "hideAddToCart": "",
75 "salePrice": "45.0",
76 "swatchesInfo": "",
77 "weight": "",
78 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
79 "totalVariants": 0,
80 "groupPrices": "",
81 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-purple",
82 "tags": "body-hugging, nylon, Red, Running, Short",
83 "size": "Large",
84 "name": "Erika Running Short",
85 "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''",
86 "category": "Shorts"
87 },
88 {
89 "discount": "",
90 "hideGroupPrices": "",
91 "type": "Shorts",
92 "itemGroupId": "4384016203838",
93 "freeShipping": "",
94 "storeBaseCurrency": "GBP",
95 "price": "45.00",
96 "toPrice": "",
97 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-red_main_9999e03f-694d-4f0c-83ab-8c0200029275_medium.jpg?v=1575477719",
98 "currency": "GBP",
99 "inStock": "yes",
100 "id": "31366431014974",
101 "imageHover": "",
102 "sku": "WSH12-28-Red",
103 "brand": "KSD",
104 "startPrice": "",
105 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/wsh12-red_main_9999e03f-694d-4f0c-83ab-8c0200029275_medium.jpg?v=1575477719",
106 "deliveryInfo": "",
107 "hideAddToCart": "",
108 "salePrice": "45.0",
109 "swatchesInfo": "",
110 "weight": "",
111 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
112 "totalVariants": 0,
113 "groupPrices": "",
114 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/erika-running-short-red",
115 "tags": "body-hugging, nylon, Red, Running, Short",
116 "size": "Medium",
117 "name": "Erika Running Short",
118 "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''",
119 "category": "Shorts"
120 },
121 {
122 "discount": "",
123 "hideGroupPrices": "",
124 "type": "Shorts",
125 "itemGroupId": "4384040386622",
126 "freeShipping": "",
127 "storeBaseCurrency": "GBP",
128 "price": "32.50",
129 "toPrice": "",
130 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh03-black_main_a8796b84-9c70-4146-9c73-2295b0d260a7_medium.jpg?v=1575478122",
131 "currency": "GBP",
132 "inStock": "yes",
133 "id": "31366465781822",
134 "imageHover": "",
135 "sku": "MSH03-32-Black",
136 "brand": "KKE",
137 "startPrice": "",
138 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh03-black_main_a8796b84-9c70-4146-9c73-2295b0d260a7_medium.jpg?v=1575478122",
139 "deliveryInfo": "",
140 "hideAddToCart": "",
141 "salePrice": "32.5",
142 "swatchesInfo": "",
143 "weight": "",
144 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
145 "totalVariants": 0,
146 "groupPrices": "",
147 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/meteor-workout-short-black",
148 "tags": "black, Machine, Nylon, Relaxed fit, Short, Summer",
149 "size": "Small",
150 "name": "Meteor Workout Short",
151 "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",
152 "category": "Shorts"
153 },
154 {
155 "discount": "",
156 "hideGroupPrices": "",
157 "type": "Shorts",
158 "itemGroupId": "4384039665726",
159 "freeShipping": "",
160 "storeBaseCurrency": "GBP",
161 "price": "29.00",
162 "toPrice": "",
163 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-gray_main_0f869cff-09fb-403a-a209-cf092f4d3c1a_medium.jpg?v=1575478112",
164 "currency": "GBP",
165 "inStock": "yes",
166 "id": "31366465060926",
167 "imageHover": "",
168 "sku": "MSH05-32-Gray",
169 "brand": "KSD",
170 "startPrice": "",
171 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-gray_main_0f869cff-09fb-403a-a209-cf092f4d3c1a_medium.jpg?v=1575478112",
172 "deliveryInfo": "",
173 "hideAddToCart": "",
174 "salePrice": "29.0",
175 "swatchesInfo": "",
176 "weight": "",
177 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
178 "totalVariants": 0,
179 "groupPrices": "",
180 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-gray",
181 "tags": "Gray, Machine, Nylon, Relaxed fit, Short, Summer",
182 "size": "Medium",
183 "name": "Hawkeye Yoga Short",
184 "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",
185 "category": "Shorts"
186 },
187 {
188 "discount": "",
189 "hideGroupPrices": "",
190 "type": "Shorts",
191 "itemGroupId": "4384037830718",
192 "freeShipping": "",
193 "storeBaseCurrency": "GBP",
194 "price": "27.00",
195 "toPrice": "",
196 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-black_main_2ef78733-04a5-4345-9f5f-992d0cfffe8d_medium.jpg?v=1575478090",
197 "currency": "GBP",
198 "inStock": "yes",
199 "id": "31366462472254",
200 "imageHover": "",
201 "sku": "MSH12-32-Black",
202 "brand": "KKE",
203 "startPrice": "",
204 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-black_main_2ef78733-04a5-4345-9f5f-992d0cfffe8d_medium.jpg?v=1575478090",
205 "deliveryInfo": "",
206 "hideAddToCart": "",
207 "salePrice": "27.0",
208 "swatchesInfo": "",
209 "weight": "",
210 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
211 "totalVariants": 0,
212 "groupPrices": "",
213 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-black",
214 "tags": "Black, Machine, Nylon, Relaxed fit, Short, Summer",
215 "size": "Small",
216 "name": "Pierce Gym Short",
217 "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",
218 "category": "Shorts"
219 },
220 {
221 "discount": "",
222 "hideGroupPrices": "",
223 "type": "Shorts",
224 "itemGroupId": "4384039796798",
225 "freeShipping": "",
226 "storeBaseCurrency": "GBP",
227 "price": "29.00",
228 "toPrice": "",
229 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-black_main_f61ee526-b9d3-4eaa-b7b2-80dc400f31b0_medium.jpg?v=1575478115",
230 "currency": "GBP",
231 "inStock": "yes",
232 "id": "31366465191998",
233 "imageHover": "",
234 "sku": "MSH05-32-Black",
235 "brand": "KKE",
236 "startPrice": "",
237 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-black_main_f61ee526-b9d3-4eaa-b7b2-80dc400f31b0_medium.jpg?v=1575478115",
238 "deliveryInfo": "",
239 "hideAddToCart": "",
240 "salePrice": "29.0",
241 "swatchesInfo": "",
242 "weight": "",
243 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
244 "totalVariants": 0,
245 "groupPrices": "",
246 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-black",
247 "tags": "Black, Machine, motion-friendly, Nylon, Relaxed fit, Smooth, Summer, yoga-short",
248 "size": "Small",
249 "name": "Hawkeye Yoga Short",
250 "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",
251 "category": "Shorts"
252 },
253 {
254 "discount": "",
255 "hideGroupPrices": "",
256 "type": "Shorts",
257 "itemGroupId": "4384039731262",
258 "freeShipping": "",
259 "storeBaseCurrency": "GBP",
260 "price": "29.00",
261 "toPrice": "",
262 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-blue_main_2130114d-06b0-4793-8fc2-bf77411297e4_medium.jpg?v=1575478114",
263 "currency": "GBP",
264 "inStock": "yes",
265 "id": "31366465126462",
266 "imageHover": "",
267 "sku": "MSH05-32-Blue",
268 "brand": "MNH",
269 "startPrice": "",
270 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh05-blue_main_2130114d-06b0-4793-8fc2-bf77411297e4_medium.jpg?v=1575478114",
271 "deliveryInfo": "",
272 "hideAddToCart": "",
273 "salePrice": "29.0",
274 "swatchesInfo": "",
275 "weight": "",
276 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
277 "totalVariants": 0,
278 "groupPrices": "",
279 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/hawkeye-yoga-short-blue",
280 "tags": "Blue, Machine, Nylon, Relaxed fit, Short, Summer",
281 "size": "Large",
282 "name": "Hawkeye Yoga Short",
283 "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",
284 "category": "Shorts"
285 },
286 {
287 "discount": "",
288 "hideGroupPrices": "",
289 "type": "Shorts",
290 "itemGroupId": "4384037765182",
291 "freeShipping": "",
292 "storeBaseCurrency": "GBP",
293 "price": "27.00",
294 "toPrice": "",
295 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-gray_main_4bb28c53-a928-47a0-92ea-ecd303f97dba_medium.jpg?v=1575478089",
296 "currency": "GBP",
297 "inStock": "yes",
298 "id": "31366462439486",
299 "imageHover": "",
300 "sku": "MSH12-32-Gray",
301 "brand": "MNH",
302 "startPrice": "",
303 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-gray_main_4bb28c53-a928-47a0-92ea-ecd303f97dba_medium.jpg?v=1575478089",
304 "deliveryInfo": "",
305 "hideAddToCart": "",
306 "salePrice": "27.0",
307 "swatchesInfo": "",
308 "weight": "",
309 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
310 "totalVariants": 0,
311 "groupPrices": "",
312 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-gray",
313 "tags": "Gray, Machine, Nylon, Relaxed fit, Short, Summer",
314 "size": "Large",
315 "name": "Pierce Gym Short",
316 "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",
317 "category": "Shorts"
318 },
319 {
320 "discount": "",
321 "hideGroupPrices": "",
322 "type": "Shorts",
323 "itemGroupId": "4384037699646",
324 "freeShipping": "",
325 "storeBaseCurrency": "GBP",
326 "price": "27.00",
327 "toPrice": "",
328 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-red_main_6c29f610-d5f7-4e1a-bde4-1fb148964be5_medium.jpg?v=1575478088",
329 "currency": "GBP",
330 "inStock": "yes",
331 "id": "31366462373950",
332 "imageHover": "",
333 "sku": "MSH12-32-Red",
334 "brand": "KSD",
335 "startPrice": "",
336 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh12-red_main_6c29f610-d5f7-4e1a-bde4-1fb148964be5_medium.jpg?v=1575478088",
337 "deliveryInfo": "",
338 "hideAddToCart": "",
339 "salePrice": "27.0",
340 "swatchesInfo": "",
341 "weight": "",
342 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
343 "totalVariants": 0,
344 "groupPrices": "",
345 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/pierce-gym-short-red",
346 "tags": "Cotton, Machine, Relaxed fit, Res, Short, Summer",
347 "size": "Medium",
348 "name": "Pierce Gym Short",
349 "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",
350 "category": "Shorts"
351 },
352 {
353 "discount": "",
354 "hideGroupPrices": "",
355 "type": "Shorts",
356 "itemGroupId": "4384038322238",
357 "freeShipping": "",
358 "storeBaseCurrency": "GBP",
359 "price": "32.00",
360 "toPrice": "",
361 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-blue_main_774a1fbb-9eab-4d4f-9261-f1e0c028b492_medium.jpg?v=1575478097",
362 "currency": "GBP",
363 "inStock": "yes",
364 "id": "31366463094846",
365 "imageHover": "",
366 "sku": "MSH10-32-Blue",
367 "brand": "KKE",
368 "startPrice": "",
369 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-blue_main_774a1fbb-9eab-4d4f-9261-f1e0c028b492_medium.jpg?v=1575478097",
370 "deliveryInfo": "",
371 "hideAddToCart": "",
372 "salePrice": "32.0",
373 "swatchesInfo": "",
374 "weight": "",
375 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
376 "totalVariants": 0,
377 "groupPrices": "",
378 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/sol-active-short-blue",
379 "tags": "Blue, Machine, Navy polyster, Relaxed fit, Short, Summer",
380 "size": "Small",
381 "name": "Sol Active Short",
382 "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",
383 "category": "Shorts"
384 },
385 {
386 "discount": "",
387 "hideGroupPrices": "",
388 "type": "Shorts",
389 "itemGroupId": "4384038256702",
390 "freeShipping": "",
391 "storeBaseCurrency": "GBP",
392 "price": "32.00",
393 "toPrice": "",
394 "imageUrl": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-green_main_18d664f2-5ba2-421d-b89a-87cb73d86416_medium.jpg?v=1575478095",
395 "currency": "GBP",
396 "inStock": "yes",
397 "id": "31366463029310",
398 "imageHover": "",
399 "sku": "MSH10-32-Green",
400 "brand": "MNH",
401 "startPrice": "",
402 "image": "https://cdn.shopify.com/s/files/1/0116/9457/1582/products/msh10-green_main_18d664f2-5ba2-421d-b89a-87cb73d86416_medium.jpg?v=1575478095",
403 "deliveryInfo": "",
404 "hideAddToCart": "",
405 "salePrice": "32.0",
406 "swatchesInfo": "",
407 "weight": "",
408 "klevu_category": "KLEVU_PRODUCT;Products;;Shorts @ku@kuCategory@ku@",
409 "totalVariants": 0,
410 "groupPrices": "",
411 "url": "https://jsv2-shopify-demo.ksearchmisc.com/products/sol-active-short-green",
412 "tags": "Green, Machine, Nylon, Relaxed fit, Short, Summer",
413 "size": "Large",
414 "name": "Sol Active Short",
415 "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",
416 "category": "Shorts"
417 }
418 ],
419 "filters": []
420 }
421 ]
422}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=fallbackQueries"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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.
This is an example how to merchandise search results using APIs.
POST
Request
Body Parameters
topIds
required
Array
Specify any records which should always be displayed at the top of the result set. You can specify a record id to control this at variant level, or a itemGroupId to control this at compound item level.
Note that this is only applicable when the sort order is by 'RELEVANCE'.
includeIds
optional
Array
Specify any records which should be included with the results, even if the Klevu search query did not match them. You can specify a record id to control this at variant level, or a itemGroupId to control this at compound item level.
excludeIds
optional
Array
Use this field to exclude certain records from the search results. You can specify a record id to control this at variant level, or an itemGroupId to control this at compound level.
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 12,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "productSearch",
9 "meta": {
10 "qTime": 8,
11 "noOfResults": 10,
12 "totalResultsFound": 105,
13 "typeOfSearch": "WILDCARD_AND",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 1,
17 "searchedTerm": "short",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [
22 {
23 "name": "Summit Watch",
24 "id": "31366496223294",
25 "itemGroupId": "4384059031614"
26 },
27 {
28 "name": "Erika Running Short",
29 "id": "31366431146046",
30 "itemGroupId": "4384016334910"
31 },
32 {
33 "name": "Erika Running Short",
34 "id": "31366431014974",
35 "itemGroupId": "4384016203838"
36 },
37 {
38 "name": "Erika Running Short",
39 "id": "31366431080510",
40 "itemGroupId": "4384016269374"
41 },
42 {
43 "name": "Meteor Workout Short",
44 "id": "31366465781822",
45 "itemGroupId": "4384040386622"
46 },
47 {
48 "name": "Hawkeye Yoga Short",
49 "id": "31366465191998",
50 "itemGroupId": "4384039796798"
51 },
52 {
53 "name": "Hawkeye Yoga Short",
54 "id": "31366465060926",
55 "itemGroupId": "4384039665726"
56 },
57 {
58 "name": "Hawkeye Yoga Short",
59 "id": "31366465126462",
60 "itemGroupId": "4384039731262"
61 },
62 {
63 "name": "Pierce Gym Short",
64 "id": "31366462439486",
65 "itemGroupId": "4384037765182"
66 },
67 {
68 "name": "Pierce Gym Short",
69 "id": "31366462373950",
70 "itemGroupId": "4384037699646"
71 }
72 ],
73 "filters": []
74 }
75 ]
76}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=handPickedQueries"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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."
This is an example how to merchandise search results using APIs.
POST
Request
Body Parameters
customANDQuery
required
String
DEPRECATED
The custom query you would like to fire, which Klevu automatically converts into an appropriate query to be included with the request. Use a - character before the parenthesis to exclude records matching the contained condition.
This is advanced usage of our API and you may need some help with building these queries, so when you need support please reach out to us via the Community Forum.
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 7,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "productSearch",
9 "meta": {
10 "qTime": 5,
11 "noOfResults": 10,
12 "totalResultsFound": 209,
13 "typeOfSearch": "WILDCARD_AND",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 1,
17 "searchedTerm": "*",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [
22 {
23 "size": "Small",
24 "name": "Stellar Solar Jacket",
25 "id": "31366456541246",
26 "brand": "KSD"
27 },
28 {
29 "size": "Small",
30 "name": "Lando Gym Jacket",
31 "id": "31366487441470",
32 "brand": "KSD"
33 },
34 {
35 "size": "Small",
36 "name": "Ingrid Running Jacket",
37 "id": "31366455590974",
38 "brand": "MNH"
39 },
40 {
41 "size": "Small",
42 "name": "Josie Yoga Jacket",
43 "id": "31366456279102",
44 "brand": "KSD"
45 },
46 {
47 "size": "Medium",
48 "name": "Hollister Backyard Sweatshirt",
49 "id": "31366493438014",
50 "brand": "MNH"
51 },
52 {
53 "size": "Medium",
54 "name": "Erika Running Short",
55 "id": "31366431014974",
56 "brand": "KSD"
57 },
58 {
59 "size": "Small",
60 "name": "Stellar Solar Jacket",
61 "id": "31366456672318",
62 "brand": "MNH"
63 },
64 {
65 "size": "Small",
66 "name": "Neve Studio Dance Jacket",
67 "id": "31366453461054",
68 "brand": "MNH"
69 },
70 {
71 "size": "Small",
72 "name": "Augusta Pullover Jacket",
73 "id": "31366455820350",
74 "brand": "KSD"
75 },
76 {
77 "size": "Small",
78 "name": "Augusta Pullover Jacket",
79 "id": "31366455951422",
80 "brand": "MNH"
81 }
82 ],
83 "filters": []
84 }
85 ]
86}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=customQueries"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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
This is an example how to fetch prices for specific currency.
POST
Request
Body Parameters
priceFieldSuffix
required
String
If you have multiple currency support enabled for your store, this parameter can be used to retrieve prices for a specific currency. For example, if the data you have indexed with Klevu includes prices for a base currency GBP and an additional currency USD, a value of 'GBP' or 'USD' here will display the relevant currency values for your records.
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 7,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "productSearch",
9 "meta": {
10 "qTime": 5,
11 "noOfResults": 1,
12 "totalResultsFound": 104,
13 "typeOfSearch": "WILDCARD_AND",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 2,
17 "searchedTerm": "short",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [
22 {
23 "storeBaseCurrency": "GBP",
24 "salePrice": "45.00",
25 "price": "45.00",
26 "name": "Erika Running Short",
27 "currency": "GBP",
28 "id": "31366431146046"
29 }
30 ],
31 "filters": []
32 }
33 ]
34}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=multiCurrency"
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
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'.
This is an example how to fetch prices specific to customer groups.
POST
Request
Body Parameters
priceFieldSuffix
required
String
If you have provided different prices for different groups when indexing your store data with Klevu, you can fetch those prices specific to a particular group.
The format of this parameter is {CURRENCY}-{GROUPID}. For example if the currency you require is USD and your indexed group ID is 'my-group-1', your query should include "priceFieldSuffix": "USD-my-group-1".
visibilityGroupID
optional
String
If you have provided visibility data for each record when indexing your store data with Klevu, you can specify an ID of that group here to exclude all records which do not belong.
The format of this parameter is {GROUPID}. For example if your indexed group ID is 'my-group-1', your query should include "visibilityGroupID": "my-group-1".
Request Body (JSON)
PHP
JS
Java
Node.js
1var 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"]}});
2
3var xhr = new XMLHttpRequest();
4xhr.withCredentials = false;
5
6xhr.addEventListener("readystatechange", function() {
7 if(this.readyState === 4) {
8 console.log(this.responseText);
9 }
10});
11
12xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
13xhr.setRequestHeader("Content-Type", "application/json");
14
15xhr.send(data);
Responses
200
1{
2 "meta": {
3 "qTime": 33,
4 "responseCode": 200
5 },
6 "queryResults": [
7 {
8 "id": "productSearch",
9 "meta": {
10 "qTime": 31,
11 "noOfResults": 1,
12 "totalResultsFound": 0,
13 "typeOfSearch": "FUZZY_OR",
14 "offset": 0,
15 "debuggingInformation": {},
16 "notificationCode": 1,
17 "searchedTerm": "short",
18 "apiKey": "klevu-156925593843210765",
19 "isPersonalised": false
20 },
21 "records": [],
22 "filters": []
23 }
24 ]
25}
1<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload="
2 style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
3 title="klevu_api sendbox"
4 allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
5 sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
6
7 ></iframe>
Updated 15 Aug 2024
Did this page help you?