Overview

klevu apiv2 is the latest version of our api for integrating smart search into your applications for lightning fast search as , record search results js api key & endpoint you must have a klevu search account to use the klevu api please access the 'shop info' tab of your klevu merchant centre to retrieve the following credentials js api key (readonly key) for querying indexed data e g klevu 156925593843210765 apiv2 cloud search url for end point e g eucs15v2 ksearchnet com if you have multiple stores with klevu, please note it is likely that each of them will have totally different js api keys and subdomains assigned search url when retrieving data for search, category merchandising or recommendations, klevu apiv2 utilizes a single endpoint https //{{apiv2 cloud search url}}/cs/v2/search please replace apiv2 cloud search url with your own value, which you can find in the prerequisites above for example, if your url is 'eucs15v2 ksearchnet com' then the correct value is https //eucs15v2 ksearchnet com/cs/v2/search the inclusion of 'v2' is important without it you will experience degraded performance since your api requests will not be utilizing our content delivery network (cdn) get vs post the apiv2 endpoint url accepts requests in json format and also responds with json requests can be made using either get or post, however we recommend post because our requests are routed through cloudflare cdn, which has a limit on the size of the payload, we are accepting request payloads up to 8kb request object every request to apiv2 comprises a structured json payload a request object the request object is a top level object that comprises a mandatory context and one or both of the suggestions and recordqueries objects each http request can contain multiple search queries the context object is for specifying your js api key the suggestions object is for requesting suggestions or typeahead results the recordqueries object is for requesting entities such as products or cms pages please note that despite apikeys being an array, currently we only support a single api key per request a skeleton of the request object looks like this json request { "request" { "context" { "apikeys" \[" "] }, "suggestions" \[ { suggestions query 1 }, { suggestions query 2 } ], "recordqueries" \[ { record query 1 }, { record query 2 } ] } } response object when a query is fired, depending on the query objects included in the request, i e suggestions and/or record queries, the klevu search engine returns a response object containing data for each of these query types, suggestionresults and queryresults the meta object contains information on the query related parameters, for example the time taken, the total number of results found, etc the skeleton of the response object looks like this json response { "meta" { }, "suggestionresults" \[ { result of suggestions query 1 }, { result of suggestions query 2 } ], "queryresults" \[ { result of record query 1 }, { result of record query 2 } ], } understanding the response parameters parameters description id the id of the record query for which the results are being returned meta the meta object contains information on the query related parameters qtime the time taken by the klevu search engine to fetch the response noofresults the number of results requested to be returned for this query totalresultsfound the total number of results found for this query offset the index of the first result returned in this response typeofsearch the query type that was executed by klevu to retrieve the results debugginginformation information that can be useful for debugging the query for example, the actual query that was fired by the klevu search engine, inclusive of any synonyms or de compounded words taken into consideration notificationcode this may be populated with a code if any actions were taken on the record possible values are 1 nothing to report 2 the price of the record is using the base currency searchedterm the search term submitted for this query records the records matching the query each record object is a map of key value pairs, where the key is the name of a field (e g id, name, price) and the value of that field stored in the klevu index the following fields are included for each record id the unique identifier of the record within klevu itemgroupid the identifier used to group compound products together, eg the id of the parent in the case of a configurable product name the name of your record, eg the product name or category title url the fully qualified url used to access the record in your store sku the stock keeping unit of the record instock whether or not your record is in stock, 'yes' or 'no' price the original price of your product, before any discounts this can be used as 'was price' when used in conjunction with saleprice saleprice the actual selling price of your product, or 'now' price when used in conjunction with price note that when using filters, the sale price is represented by klevu price startprice the saleprice of the lowest variant within all those indexed with the same itemgroupid this can be used if you would like to show 'as low as' price toprice the saleprice of the highest variant within all those indexed with the same itemgroupid this can be used if you would like to show 'from x to y' price range groupprices this field is not always populated and is mostly used in older integrations it includes the prices of your record in format groupid\ price so you can use your own frontend logic to display prices in realtime if you are using the b2b group price search parameters described in this documentation, the price and saleprice are automatically calculated so there is no need to use this field in most cases currency the currency code applicable to the price values being displayed category a double semicolon ;; separated list of the most specific categories, not including their full path for example if a record was in 'mens > shoes' and 'mens > tees', the value would be shoes;;tees klevu category this is mostly for internal purposes, but includes the categorisation of the record within klevu for example klevu product;;shop all;;bath;;;groupid 1 @ku\@kucategory\@ku\@ shortdesc the short description of your record rating the rating of your product, between 0 and 5 ratingcount the number of ratings given by customers for your product image the fully qualified url to the main image of your record imagehover the fully qualified url to the secondary image of your record swatches if your indexed data includes variants with swatch information, this will be provided here as a nested object with the following elements id the klevu record id of the variant the swatch represents color the label to be displayed for the swatch, eg red \ swatchimage the hex colour or image url to be displayed as the swatch pattern, eg #ff0000 image the image of the product which corresponds to this swatch, eg a picture of the tshirt in red \ numberofadditionalvariants if there are additional variants which have not been included, the number will be included here, so you can display something like "also available in 4 other colours" totalvariants how many additional variants are available for this product for example when searching for 'small tshirt', if a product has 3 colours available in small then the value here will be 2 if the search was 'tshirt' then the same record would return a value of 8 if there are 3 colours and 3 sizes of each available score the score the record has achieved, ie how relevant it is, which is used for sorting by relevance this value must be either explicitly requested in fields or using search preference enablescores klevu manual boosting any manual score assigned by the merchant this value must be either explicitly requested in fields or using search preference enablescores klevu bulk boosting any manual score assigned by the manual boosting rules this value must be either explicitly requested in fields or using search preference enablescores klevu selflearning boosting the machine learning score assigned by the klevu search engine this value must be either explicitly requested in fields or using search preference enablescores brand the brand of the product, eg 'nike' tags any tags or keywords klevu has saved for the record typeofrecord the type of record, e g klevu product, klevu cms, klevu category, etc other fields there will also be various other fields returned according to the data you have indexed, which will vary from store to store