NAV Navbar
API version 1 | API version 2
Try this API yourself

API Version 2 (current)

Welcome to the Klevu API documentation. Use this documentation to integrate Klevu Search and/or Category Navigation into your applications.

Prerequisites:

Indexing

Every single record (e.g. a product, cms page etc.) sent to Klevu servers is managed in a dedicated index of the respective store. The Indexing API is useful for adding, updating and/or deleting records from this index.

The Indexing API requires that you first authenticate yourself to the Klevu servers. As a result, you are provided a sessionId, that you can use for all your subsequent requests to the Klevu servers.

Notes:

Requesting a sessionId

Use this call to authenticate yourself to the Klevu Indexing servers. As a result, you will be provided a sessionId, that you should use for all your subsequent requests to the Klevu servers.

Response

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <sessionId>some-session-id</sessionId>
</message>

Request

POST http://rest.klevu.com/rest/service/startSession

HTTP Header Value
Authorization Klevu_REST_API_Key

What is a Record?

From the Klevu Search's perspective, a record can be a product, a CMS page or a category page that you want to index and make available in search results.

When you submit a record for deletion, you are expected to submit only its unique ID. However, when you submit a record for addition or updating, you must submit the record with all its details provided. A list of mandatory and optional fields is provided below.

This is the unique ID of a record.

This is the name or title of your record.

This is the URL where we send shoppers to when the record is clicked in the Klevu Search results.

Price of a product. In case of a non-product record, 0.0 must be provided as the value. Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 12999.00 is a valid value. However, $12999 or 12,999.00 are not. Please specify the currency information in a separate currency element.

This is the final price (after all applicable discounts) of your product. In case of a non-product record, 0.0 must be provided as the value Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 12999.00 is a valid value. However, $12999 or 12,999.00 are not. Please specify currency information in a separate currency element.

This attribute indicates the most specific category of the record being submitted. For example, Samsung Galaxy Note is a type of Mobiles & Accessories and also Tablets. But Tablets is the most specific category applicable in this case.

This is the entire hierarchy of categories applicable for a product. For example, Samsung Galaxy Note is a type of a Tablet. Here, Tablet is a category. Tablet is type of Mobiles & Accessories and Mobile & Accessories are types of Electronics. Thus the value provided here should be: Tablet;Mobiles & Accessories;Electronics, with each part of the category separated by a ; semicolon.

In addition to the entire hierarchies of applicable categories, you MUST provide one of the following values (whichever is more appropriate) in the listCategory element.

If your data contains a shirt in 2 different colours and 3 different sizes, you must submit 6 product variants. To indicate which group each variant belongs to, use the itemGroupId element.

This is the URL of an associated image for your record.

Currency code e.g. EUR, USD etc.

Discount in percentages. Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 30 is a valid value.

Short description for your record. This field will be used to display a short description of a record in search results.

Long description for your record.

attribute1_code:caption for attribute1. Comma separated values of attribute1 for that record.

attribute2_code:caption for attribute2. Comma separated values of attribute2 for that record.

and so on...

All the attributes that you like to display as filters should be provided here. The attribute code here is a unique identifier of your attribute. It must be a single term. The attribute caption is used as a heading of your filter when displaying search results.

Note the use of “:” (colon) as a separator between the attribute code, attribute caption and values. Note the use of “,” (comma) as a separator for attribute values. Note the use of “;” (semicolon) as a separator for the attributes. If the attribute caption or value contains one of these three characters (comma, colon or semi-colon), these must be replaced with a space.

The format of this element is the same as the format of the other element above. Difference between the two is that the other is used for displaying facets whereas the otherAttributesToIndex is used for indexing and searching only.

Any decimal value between the range of 0.1 to 999 can be provided here. The score provided here is multiplied with the relevancy score to boost records at search time. If you want to deboost a record, provide a number that is greater than 0 and less than 1.

This attribute indicates if your record is in stock or not. Use yes if in stock, no otherwise.

A score between 0 and 5.

Use this field to specify important keywords applicable for your records.

Adding New Records

You must provide a record in full along with all the mandatory parameters for every record you submit.

URL

POST http://rest.klevu.com/rest/service/addRecords

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>sessionId</sessionId>
    <records>
      <record>
        <pairs>
          <pair>
            <key>id</key>
            <value>product ID</value>
          </pair>
          <pair>
             <key>name</key>
             <value>name of your product</value>
          </pair>
          <pair>
              <key>price</key>
              <value>price of your product</value>
          </pair>
          ...
          </pair>
       </pairs>
      </record>
      ...
      </record>
    </records>
</request>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg> <N> records are marked for ADDITION</msg>
</message>

Query Parameters

Field Name Description
id (Mandatory) This is the unique ID of a record.
name (Mandatory) This is the name or title of your record.
url (Mandatory) This is the URL where we send shoppers to when the record is clicked in the Klevu Search results.
price (Mandatory) Price of a product. In case of a non-product record, 0.0 must be provided as the value. Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 12999.00 is a valid value. However, $12999 or 12,999.00 are not. Please specify the currency information in a separate currency element.
salePrice (Mandatory) This is the final price (after all applicable discounts) of your product. In case of a non-product record, 0.0 must be provided as the value Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 12999.00 is a valid value. However, $12999 or 12,999.00 are not. Please specify currency information in a separate currency element.
category (Mandatory) This attribute indicates the most specific category of the record being submitted. For example, Samsung Galaxy Note is a type of Mobiles & Accessories and also Tablets. But Tablets is the most specific category applicable in this case.
listCategory (Mandatory) This is the entire hierarchy of categories applicable for a product. For example, Samsung Galaxy Note is a type of Tablet. Here, Tablet is a category. Tablet is a type of Mobiles & Accessories and Mobile & Accessories are types of Electronics. Thus the value provided here should be: Tablets;Mobiles & Accessories; Electronics.

In addition to the entire hierarchies of applicable categories, you MUST provide one of the following values (whichever is more appropriate) in the listCategory element.
- KLEVU_PRODUCT
- KLEVU_CMS
- KLEVU_CATEGORY
itemGroupId (Optional) If your data contains a shirt in 2 different colours and 3 different sizes, you must submit 6 product variants. To indicate which group each variant belongs to, use the itemGroupId element.
image (Optional) This is the URL of an associated image for your record.
currency (Optional) Currency code e.g. EUR, USD etc.
discount (Optional) Discount in percentages. Permitted characters in this field are 0 to 9 (digits) and . (dot) for adding a decimal point. For example, 30 is a valid value.
shortDesc (Optional) Short description for your record. This field will be used to display a short description of a record in search results.
desc (Optional) Long description for your record.
other (Optional) attribute1_code:caption for the attribute 1:comma separated values of attribute1 for that record;attribute2_code:caption of the attribute 2:comma separated values of attribute2 for that record; and so on.

All the attributes that you like to display as filters should be provided here.
The attribute code here is a unique identifier of your attribute. It must be a single term.
The attribute caption is used as a heading of your filter when displaying search results.

Note the use of “:” (colon) as a separator between the attribute code, attribute caption and values. Note the use of “,” (comma) as a separator for attribute values. Note the use of “;” (semicolon) as a separator for the attributes. If the attribute caption or value contains one of these three characters (comma, colon or semi-colon), these must be replaced with a space.
otherAttributesToIndex (Optional) The format of this element is the same as the format of the other element above. Difference between the two is that the other is used for displaying facets whereas the otherAttributesToIndex is used for indexing and searching only.
boostingAttribute (Optional) Any decimal value between the range of 0.1 to 999 can be provided here. The score provided here is multiplied with the relevancy score to boost records at search time. If you want to deboost a record, provide a number that is greater than 0 and less than 1.
inStock (Optional) This attribute indicates if your record is in stock or not. Use yes if in stock, no otherwise.
rating (Optional) A score between 0 and 5.
tags (Optional) Use this field to specify important keywords applicable for your records.

Updating Existing Records

You must provide a record in full along with all the mandatory parameters for every record you submit.

URL

POST http://rest.klevu.com/rest/service/updateRecords

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>sessionId</sessionId>
    <records>
      <record>
        <pairs>
          <pair>
            <key>id</key>
            <value>product ID</value>
          </pair>
          <pair>
            <key>name</key>
            <value>product name</value>
          </pair>
          <pair>
            <key>price</key>
            <value>product price</value>
          </pair>
        </pairs>
      </record>
      ...
     </record>
    </records>
</request>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg><N> records are marked for UPDATING</msg>
</message>

Query Parameters

Same as given in Adding New Records

Deleting Existing Records

You must provide record IDs to delete.

URL

POST http://rest.klevu.com/rest/service/deleteRecords

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>sessionId</sessionId>
    <records>
      <record>
        <pairs>
          <pair>
            <key>id</key>
            <value>product ID</value>
          </pair>
        </pairs>
      </record>
      ...
      </record>
    </records>
</request>

Response

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg><N> records are marked for DELETION</msg>
</message>

Query Parameters

Same as given in Adding New Records

Searching

Overview

The Klevu Search API v2 offers a single endpoint for retrieving a variety of data types from the Klevu Search backend. The API endpoint accepts JSON as input and responds in the same format.

The JSON input can be provided either using a simple query string as a parameter or using the request body.

Some of the functional capabilities offered by the Search API v2 include:

Prerequisites

Klevu API Key

It has the prefix klevu- which is followed by a sequence of numbers unique to your search index e.g: klevu-14666680139423664

If you have signed up for multiple stores, you should have a unique API key for each of your stores. Unless you have explicitly confirmed with the Klevu Search team, no two stores will ever have the same Search API key.

Klevu Search Endpoint

The search endpoint looks like the following:

https://<subdomain>v2.ksearchnet.com/cs/v2/search

A subdomain is assigned to your store depending on the plan of your account and the country of your store. The inclusion of 'v2' is important. Omitting this will cause degraded performance as it will not utilise our Content Delivery Network (CDN).

For example:

https://eucs18v2.ksearchnet.com/cs/v2/search

Please note: As we maintain a separate index for each of your stores, it is possible that you have totally different sub-domains assigned to your other stores.

It is important to take a note of these parameters and use the relevant values when firing search queries to the Klevu Search engine.

Klevu Category Navigation Endpoint

If you have opted in to power your category pages with Klevu Search, you should have also received an endpoint where you can query to retrieve data for your category / collection pages.

The endpoint may remain the same as the Klevu Search endpoint. When in doubt, please get in touch with the Klevu support team.

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, but we recommend POST.

To use GET you can provide a parameter q with an urlencoded JSON value:

Our preferred approach is with POST, which the examples on this page are using:

JSON Templates

The Klevu Search API endpoint accepts JSON as an input and responds in the same format.

The request object is a top level object that comprises of a mandatory context and one or both of the suggestion and recordQuery objects. Skeleton of the request object looks like the following:

The Request Object

Here, the context object is used for specifying a Search API key to which the queries are fired.

The 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 for each of these query types. The skeleton of the response object looks like the following:

Here, the response object comprises of three types of objects:

In the sections below, we dive deep into suggestion and record query objects and also discuss their responses.

The suggestions Object (Autosuggestions)

Request URL:

Request payload:

Response data:

The suggestions object is used for fetching autocomplete suggestions. When a query is fired, the Klevu Search engine produces suggestions based on various scenarios. The following use cases are taken into consideration.

Below, we provide a template for the suggestions queries.

REQUEST

Parameter Description
id Every suggestion request must have a unique id associated with it. When a result is retrieved, ids of respective queries are associated with their respective responses
query This is the query term or phrase for which the suggestions are retrieved from the Klevu Search backend
limit This is the maximum number of suggestions to be retrieved
includeFilters If set to true (and only if the filtering feature is enabled for your store in the Klevu Search backend), any filters associated with the first suggestion in the response are retrieved. If, for example, a query is ip, and the first suggestion in the response is iphone, filters such as mobile phones and mobile phone accessories may be retrieved for the suggestion iphone.
filterLimit This is the maximum number of filters to return for the suggestion in the response.
applyFilters Should you wish to restrict suggestions to the ones with one or more specific filters, you can specify the filter constraints here. For example, a filter constraint could be a string mobile accessories. In this case, for the query term iphone, the suggestions expected could be iphone cases and iphone covers. In case of multiple filters provided as constraints, the suggestions retrieved must have all the filters applied. Before one can use any filter constraints, it is important to note that the relevant filters must be indexed in the Klevu Search backend. Please, get in touch with the Klevu Support team to enable this feature for your store.

RESPONSE

When a suggestion request is fired, its response looks like the following:

Here, one suggestionsResults object is returned for every suggestion query requested.

The recordQuery Object (Searching for Records)

Request URL:

Request payload:

Response data:

It is possible to fire one or more record queries using the recordQuery object. A skeleton of the record query object is given below:

REQUEST

Parameter Description
id For each query, you must specify a unique id. This id is included in the response for that query.
typeOfRequest This parameter defines the type of request it is. The permitted values are either SEARCH (default) or CATNAV. Every customer who has signed up for a Klevu Search account gets access to the Klevu Merchant Center (KMC), where he or she can set up various parameters, for example, promotions, redirects, preferences for both search and category navigation requests. Depending on the type of a request specified here, the respective settings are applied.
settings This object contains a query object and other related elements for setting up a search query. More details on the same are provided later in this documentation.
CategoryPath This object can be used to specify either a single or nested set of categories when using the Klevu Smart Category Navigation feature. Nested categories should be separated using the ';' character.
filters The filters object is useful when you wish to retrieve aggregations or use them as filters to narrow down the search results. More details on the same are provided later in this documentation.
boost The boost object is useful when you wish to apply manual boosts to query results. More details on the same are provided later in this documentation.

RESPONSE

When a record query is fired, the matching records are returned in an object of type queryResult. Skeleton of the queryResult object is explained below:

Parameter Description
id Id is the id of the record query for which the results are being returned
meta The meta object contains information on the query related parameters. For example, the time taken by the query, the actual number of results requested and the total number of results found etc.
records The records matching the query are included here. More details on the same are provided later in this documentation.
filters If the filters are requested, they are included in the response here. More details on the same are provided later in this documentation.

The settings Object

Request URL:

Request payload:

Response data:

The settings object contains various query related settings.

Parameter Description
term This is the phrase to be searched. It can be any free text up-to 128 characters long. If a longer string is provided it is automatically truncated after the first 128 characters.
CategoryPath This object can be used to specify either a single category or a nested set of categories. Nested categories should be separated using the ';' character. For example, for Stationery > Notebooks you should use Stationery;Notebooks.
typeOfRecords Here, you can specify the types of records (e.g. KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY etc.) you like to search. In case more than one type of records are specified, the results fetched from the Klevu Search engine may be a mix of all the different types of records specified here. In any case, the maximum number of results retrieved from the Klevu Search backend will never be more than the limit specified (see below). Should you wish to retrieve records of each type separately, a query for each type must be submitted as a separate record query.
limit The maximum number of records to retrieve from the Klevu Search backend. Also see typesOfRecords parameter above.
offset The index at which to start counting the number of results from. Please note that the index of the very first record in the result set is 0. Thus, if you want to start from the 10th result, use an offset of 9.
groupBy This parameter takes the name of a field indexed in the Klevu Search backend and ensures that there is only one record for each unique value of this field in the search results. By default, the groupBy operation is performed on the itemGroupId field. In case of querying for KLEVU_CATEGORY or KLEVU_CMS records, it is recommended to use name as the groupBy parameter value.
fields By default, a variety of fields per record are retrieved from the Klevu Search backend. Should you wish to retrieve only a specific set of fields, please specify them here. The fields that are available (out of the box) to be retrieved are the following:
- Id itemGroupId (i.e. id of a record or a parent record (e.g. a configurable product))
- sku (sku code)
- url
- name
- startPrice (i.e. price of the lowest variant)
- toPrice (i.e. price of the most expensive variant)
- salePrice (the price at which the product is available to purchase)
- groupPrices (group wise prices in the format of :)
- discount
- currency
-category (a list of most specific categories)
- listCategory (a list of hierarchies of applicable categories)
-shortDesc
-rating (a number between 0 and 5)
-image (url of the image)
-imageHover (url of the image to show on mouse-hover)
-swatchesInfo (what swatches are available, image to show on a swatch hover etc.)
- inStock
-klevu_manual_boosting (a manual score assigned by a merchant)
-klevu_bulk_boosting (a manual score assigned by the manual boosting rules)
-klevu_selflearning_boosting (a machine learning score assigned by the Klevu Search engine)
-brand
-tags
-typeOfRecord (e.g. KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY etc)
typeOfSearch This parameter defines the type of a query that should be fired to retrieve results. The supported values and their execution behaviour are explained below:

-AND: All words of a query must be found in a record for it to be included in the result set

-WILDCARD_AND: All words of a query must be found in a record for it to be included in the result set. Here, the last word of a query can be a prefix to any of the words associated with the record.

-FUZZY_AND: All words of a query must be found in a record for it to be included in the result set. Here, up-to a certain level of fuzziness is allowed when matching words. OR At least one word of a query must be found in a record for it to be included in a result set.

-WILRDCARD_OR: At least one word of a query must be found in a record for it to be included in the result set. Here, the last word of a query can be a prefix to any of the words associated with the record.

-FUZZY_OR: At least one word of a query must be found in a record for it be included in the result set. Here, up-to a certain level of fuzziness is allowed when matching words.

-DEFAULT: With this type, the first preference is given to the AND query type. If there aren't any results found, the Klevu Search engine tries to find products with the WILDCARD_AND query type. It will continue to fire different query types (in order of AND, WILDCARD_AND, FUZZY_AND, OR, WILDCARD_OR and FUZZY_OR) until it has found at least one result.
searchPrefs This is the array of search preferences. The supported values and their execution behaviour are explained below:

- excludeDescription: including this option excludes description from search queries

- partialMatch: enables partial match for the last word of a query (i.e. the last word can be a substring of any other word found in a record)

-partialMatchForAllWords: enables partial match (i.e. words of a query can be substrings of another word)

-disableFuzzyMatch: disables matching words with similar spellings

-includeStopwords: functional words such as prepositions, pronouns, articles etc. are also considered for matching. By default, such functional words are automatically excluded from search.

-disableWildcard: disables the wild card search

-enableBoostingOriginalTermsInSynonyms: Synonyms of a word or phrase are, by default, treated equally to their query term. Should you wish to give higher priority to the terms mentioned in the query over their synonyms, please include this flag in your search preferences.

-showOutOfStockProducts: by default, the out of stock products are excluded from search. Should you wish to include out of stock products in search, please include this flag in your search preferences.

-disableStockSorting: Out of the box, records are sorted by their instock status. The ordering within the same instock status records is performed by the reverse order of records’ relevancy score. Should you wish to disable sorting by their instock status, please include this flag in your search preferences.

-disableGrouping: Out of the box, all products are grouped by their itemGroupId values, ensuring only one variant per group is included in the result set. Including this flag in your search preferences will disable automated grouping.

-disableSearchOnProductIds: Should you wish to disable searching on product IDs, please include this flag in your search preferences.

-disableWordShingles: For a query longer than one word, all the possible bigrams and trigrams (i.e. formed out of query terms) are looked up in records and the ones having one or more of them are boosted higher up in the search results. If you like to disable this behaviour, please include this flag in your search preferences.

-disableORSearch: When there is no or DEFAULT value provided for the typeOfSearch parameter, and if no record is found with all the terms of a query in them, the backend engine attempts to find records which have at least one of the query terms found in them. Should you wish to disable this behaviour, please include this flag in search preferences.

- searchCompoundsAsAndQuery: Out of the box when a compound word (i.e. two or more individual words joined together as one word) is searched, the Klevu Search engine may automatically disjoint them (i.e. if the decompounding feature is enabled for your store) and search them within the close proximity of one-other (i.e. words appearing within the proximity of 5 words from one other). If you like to remove the proximity constraints and allow them to be searched across different fields (e.g. one of the disjoint words may be found in one field and the others may be found in other field(s)), please include this flag in search preferences.

- debugQuery: When this flag is included in the search preferences, additional information on the query execution (e.g. an internal query after considering synonyms and decompounding, words) are included in the meta object of the response.
Please note that it is not recommended to enable this flag in the production environment for performance reasons.

-sort: By default, the search results are sorted as per their relevance score to the search query. Should you like to change the sorting order, you can use one of the following values: PRICE_ASC, PRICE_DESC, RELEVANCE, NAME_ASC and NAME_DESC
topIds These are record IDs that are displayed at the top of a result set in the order specified here.
visibility Here, you can specify products of which visibility should be included (e.g. search, catalog)
customANDQuery Given various query parameters, Klevu automatically forms an appropriate query internally to be fired to its index. If you want to add an additional constraint to the query that Klevu builds internally, you can use this parameter to do so.
priceFieldSuffix If you have multiple currency support enabled for your store, this parameter can be used to retrieve price for a specific currency. For example, a value such as GBP for this parameter, fetches product prices in GBP. Similarly, if you have indexed different prices for different groups and should you wish you fetch prices that are specific to a specific group, this parameter can be used to specify the group you're interested in.
personalisation Klevu Search has an inbuilt personalisation engine that depending on a consumer's activity automatically identifies parameters that the consumer may be after and boosts records that may be of most interest to the consumer. Should you wish to enable personalisation, it is important that you enable this feature by setting the enablePersonalisation parameter to true.

When identifying parameters of interest for a consumer, analysis of all the fields, including identification of important keywords is conducted. Here, the parameter fields can be used to restrict personalisation analysis to specific fields.

Similarly, should you wish to disable automated boosting of any keywords, the parameter disableKeywords should be set to true.
context the context object is used for providing the Klevu Search engine the needed information on consumers’ recent activities. The information provided here is used by the Klevu Search algorithm to decide, for example, its personalisation strategy when retrieving search results.

- recentTerms: This array of strings should have the search terms recently searched by the respective customer. The first element in the array should be the most recently searched term. Upto 5 search terms can be provided here.

- recentObjects:This array of objects has the records (e.g. products, CMS pages, category pages etc) that were recently visited by a consumer. We are expecting one recentObject object per different record type (e.g. KLEVU_PRODUCT, KLEVU_CMS). Each recentObject object may contain multiple record objects (e.g. 5 recently viewed products). Similar to the order of recentTerms, here too, we expect the most recently clicked record to be the first element in the array of records.
includeIds if there are any products that must be included in the result set, their Ids should be specified here. Please note that for compound products, the ID may be a combination of its parent ID and the variant ID (e.g. 1234-1235).
excludeIds if there are any products that must NOT be included in the result set, their Ids should be specified here.
fallbackQueryId In case of a no result found for a query, the Klevu Search engine returns the most popular records that it has learnt to be displayed to a shopper. The suggestions in this case may be influenced by the values provided in the context object as explained earlier. However, should you wish to fire another query when there is no result found, the id of such a recordQuery should be specified here.
fallbackWhenCountLessThan A fallback query is executed automatically when there is no result found. However, should you wish to put a condition (i.e. when exactly the fallback query should be fired), use this parameter with a positive number. In this case, if the number of results is less than the number specified here, the fallback query with the specified id is invoked.

RESPONSE

Here, we've explained the response template for a record query.

Parameter Description
id id is the id of the record query for which the results are returned.
meta the meta object contains information on the query related parameters.

- qTime: qTime is the time taken by the Klevu Search engine to fetch the response

- noOfResults: noOfResults is the number of results requested to be returned for this query

- typeOfSearch: typeOfSearch is the query type that was executed by the Klevu Search backend to retrieve these results. Please refer to the typeOfSearch parameter explained above in the query object explanation.

- totalResultsFound: totalResultsFound is the total number of results found in the Klevu Search backend for this query

- offset: offset is the index of the first result returned in this response.

- debuggingInformation: debuggingInformation object is used for providing 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.
records 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 a value of that field stored in the Klevu Search backend. Unless any specific fields are requested, by default, the following fields are included for each record.

- Id itemGroupId (i.e. id of a record or a parent record (e.g. a configurable product))

- sku (sku code)

- url

- name

- price (i.e. the retail or the original price)

- startPrice (i.e. price of the lowest variant)

- toPrice (i.e. price of the most expensive variant)

- salePrice (the price at which the product is available to purchase)

- groupPrices (group wise prices in the format of :)

- discount

- currency

- category (a list of most specific categories)

- listCategory (a list of hierarchies of applicable categories)

- shortDesc

- rating (a number between 0 and 5)

- image (url of the image)

- imageHover (url of the image to show on mouse-hover)

- swatchesInfo (what swatches are available, image to show on a swatch hover etc.)

- inStock

- klevu_manual_boosting (a manual score assigned by a merchant)

- klevu_bulk_boosting (a manual score assigned by the manual boosting rules)

- klevu_selflearning_boosting (a machine learning score assigned by the Klevu Search engine)

- brand

- tags

- typeOfRecord (e.g. KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY etc)
filters If the filters were requested, they too are included in the response. More information on the filters object is provided later in this documentation.

The filters Object (Obtaining Filters and Applying them)

Request URL:

Request payload:

Response data:

When a query is fired, you may want to see aggregations of attributes that are all relevant to the current set of records. If the search query was tops, you may be interested to know all the colors, the sizes and the materials these tops are available in. You may also want to filter these results to specific attribute values (e.g. small and red coloured tops).

In Klevu Search terminology, we call these aggregations filters. The two new objects, filtersToReturn and applyFilters, are respectively used for obtaining aggregations and to apply attribute conditions on search results.

The filtersToReturn object

Request URL:

Request payload:

Response data:

The filtersToReturn object should be used for obtaining filters from the Klevu Search engine. The process of aggregating data for each filter requires that the Klevu Search engine finds out all possible options of a filter and counts how many records for each of these options are present in the current search results.

You may ask Klevu Search engine to return all possible filters or only a set of specific filters matching certain conditions.

Parameter Description
enabled Filters are returned only when this flag is set to true. In the absence of any other parameter or setting provided, by default, all the filters applicable to the current result set are returned.
include This is the list of filters (i.e. attribute ids) that you like to retrieve as filters. Please note that a filter may not be returned in the response if there isn't any record in the result set where the specified filter is applicable.
exclude This is the list of filters (i.e. attribute ids) that you do not want Klevu Search to include in the response. Please note that if a filter is present in both the include and exclude lists, such a filter will not be included in the response.
options Use the options object to specify how the filters' options are included in the response.

order:The parameter order can take either FREQ or INDEX as possible values. Whilst the former sorts options based on the number of records each option has in the result set (with the option with the highest records in the result set being at the top), the latter option sorts the options alphabetically.

limit:The parameter limit limits the maximum number of options to be included per filter.

minCount:If the parameter minCount is present with a positive number, only the options with count equal to or higher than the minCount are included.
rangeFilterSettings Unless explicitly requested, all the submitted attributes to Klevu Search engine are indexed as string attributes. The salePrice field is the only exception to this rule. If, during the process of configuring Klevu Search on your store, you had requested a certain attribute or attributes to be indexed as numerical attributes, you can query and/or retrieve them as range filters. As shown above, the rangeFilterSettings object allows you to specify which range filters you like to retrieve and configure them for how they should be retrieved.
key The key parameter is the id of your numerical attribute.
minMax If the minMax parameter is set to true, the Klevu Search engine calculates the minimum and maximum values for this filter.
rangeInterval If a positive value is provided for the parameter rangeInterval, the Klevu Search engine will calculate ranges (i.e. from X to Y, from Y to Z and so on).

RESPONSE

Each filter in the array of filters represents one attribute and a set of options depending on its type (i.e. OPTIONS or SLIDER).

Parameter Description
key Unless it is a virtual attribute that was created by the Klevu Search engine (following your request), this is usually an attribute id.
label This is the caption or a friendly name given to an attribute.
type This parameter defines the type of a filter. It is either OPTIONS or SLIDER. For an OPTIONS filter (e.g. color), its different options (e.g. red, blue, black etc.) are provided as options. For a SLIDER filter, values such as minimum, maximum, start and end are provided in the response.
options This is an array of different options of a filter. For each filter option, four parameters are provided.

name: name (or a caption) of an option (e.g. if the filter is color, option names could be red, blue, black etc.)

value: Each filter option has a unique identifier in Klevu Search backend. When applying a filter on search results, it is this value that should be used (see the applyFilters object below) .

count: This is the number of records found with the current option in the current search results (e.g. the number of products that are red in color).

isSelected: If true, it indicates that the current option is already applied as a filtering condition on the search results.

min, max, start and end: These values are provided only for the SLIDER filters (e.g. price). The min and max values are the minimum and maximum values as seen in the current result set whereas the start and the end values are the filtering conditions already applied on the result set for this filter.

It is important to note that retrieving filters is an expensive operation. You may be limiting the number of records you want to retrieve for a query (e.g. for pagination), however the filters that the Klevu Search returns are always for the entire set of records for that query. For this reason, unless there is an absolute need, you may want to fetch filters once per every unique query and cache them locally.

If you're firing a subsequent query, for example, only to fetch a next set of results for the subsequent pages or applying a different set of boosting parameters, which doesn't really change what products are included in the result set, you may want to reuse the cached filters.

The applyFilters object

Request URL:

Request payload:

Response data:

The applyFilters object should be used for applying filter conditions on a result set. Before we explain how it is done, it is important to understand how filtering works, especially when multiple filters are applied on a result set.

Each filter (e.g. a color) may have different options (e.g. red, blue, black etc). To apply a filter, you need to know the key of the relevant filter and the value of the relevant option. You are requested to look at the filter response (as mentioned above) where, for each option, the Klevu Search engine returns its name, value and a count. Here, it is the value field that should be used when applying a filter.

If there is only one filter applied with one option only, the backend engine ensures that all the records it returns have the relevant attribute with the specified value. In case two or more values for the same filter are provided, the execution of such a constraint is dependent on the value of the singleSelect parameter. If it is set to true, the backend engine will ensure the products it returns have both the values. If it is set to false, it will ensure the products it returns have at least one of the values.
If constraints are added for multiple filters and the value of the singleSelect filter is false, the backend engine will ensure the products it returns have at least one value from each of the filter conditions provided.

The boost Object (Personalisation)

Request URL:

Request payload:

Response data:

Klevu Search has an in-built personalisation engine that depending on a consumer's activity identifies his or her shopping preferences and boosts relevant products in search results. However, in case a merchant likes to boost certain records (e.g. by using individual customer profiles), the boost object, explained below, allows taking full control.

There are three ways products can be boosted: one or more filter conditions with some weights (i.e. between 1 and 99) one or more keywords or phrases with some weight one or more product Ids with some weight

It is important to note that any boosts applied using the boost object may result in products being ranked differently, however, it does not change the overall result set itself.

Query Examples

Autocomplete Query

Request URL:

Request payload:

Response data:

POST https://.ksearchnet.com/cs/v2/search

EXAMPLE REQUEST

EXAMPLE RESPONSE

Simple Product Search Query

Request URL:

Request payload:

Response data:

POST https://.ksearchnet.com/cs/v2/search

EXAMPLE REQUEST

EXAMPLE RESPONSE

Complex Search Query

A complex search query

Request URL:

Request payload:

Response data:

POST https://.ksearchnet.com/cs/v2/search

EXAMPLE REQUEST

EXAMPLE RESPONSE

Query with Personalisation

A query with Personalisation

Request URL:

Request payload:

Response data:

POST https://.ksearchnet.com/cs/v2/search

EXAMPLE REQUEST

Category Navigation

Category Navigation Query

A query with Category Navigation

Request URL:

Request payload:

Response data:

POST https://.ksearchnet.com/cs/v2/search

EXAMPLE REQUEST

Analytics

Analytics details are used by the Klevu search algorithms to capture the trend on your website, to understand your customers' behaviour and to improve the overall search and recommendation experience of your customers.

You can use the following API methods to submit and retrieve the information.

Reporting Search Activities

As part of Klevu Search integration, we need to know the following three things:

Searched Terms

URL

POST http://stats.klevu.com/analytics/n-search/search

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey This is your Klevu JS API Key.
klevu_term This is the term being searched. For example iphone 5s.
klevu_totalResults This is the total number of results returned for the searched term. It must be an integer (e.g. 5)
klevu_shopperIP IP address of the shopper who searched a term. If calling from javascript (i.e. an ajax call), this is an optional parameter.
klevu_typeOfQuery When you receive a response for a search query, look at the value of the typeOfQuery element under the metaData section (e.g. WILDCARD_AND, FUZZY_AND). You need to pass this value to this parameter.

Clicked Records

URL

POST http://stats.klevu.com/analytics/productTracking

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey This is your Klevu JS API Key.
klevu_keywords This is the term being searched. For example iphone 5s.
klevu_type Here, the value must be clicked.
klevu_productId This is the product code of the clicked product.
klevu_productName This is the product name of the clicked product.
klevu_productUrl This is the product URL of the clicked product.
klevu_shopperIP IP address of the shopper who clicked on a product. If calling from javascript (i.e. an ajax call), this is an optional parameter.

Checked Out Products

URL

POST http://stats.klevu.com/analytics/productTracking

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey This is your Klevu JS API Key.
klevu_type Here, the value must be checkout.
klevu_productId This is the product code of the clicked product. Please note that the value of the klevu_productId must be the same in both the click and checkout calls (for the same product).
klevu_unit This is the total quantity purchased. It must be an integer (e.g. 5).
klevu_salePrice Product's sale price for one unit. This must be a double Value.
klevu_currency e.g GBP, USD, EUR.
klevu_shopperIP IP address of the shopper who bought the product(s).
If calling the checkout HTTP call from javascript, this is an optional parameter.

Reporting Category Navigation Activities

As part of Klevu's Category Navigation add-on integration, we need to know the following details:

Category Page Views

URL

POST https://stats.ksearchnet.com/analytics/categoryProductViewTracking

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey* This is your Klevu JS API Key.
klevu_categoryName* This is the name of the category being visited. For example, Stackable Rings. The name should not include parent categories.
klevu_categoryPath* This is the complete hierarchy of the category being visited. For example, Jewellery;Rings;Stackable Rings. Please note the use of a semicolon as the separator between a parent and a child category.
klevu_productIds* Comma separated list of product IDs being shown on the current page of the category page. For example, P1,P2,P3,P4,P5…
All the product IDs listed here are treated as impressions for these products.
klevu_pageStartsFrom Offset of the first product being shown on this page. For example, if you are displaying 30 products per page and if a customer is on the 2nd page, the value here should be 30. If on the 3rd page, it will be 60.

Product Clicks

URL

POST https://stats.ksearchnet.com/analytics/categoryProductClickTracking

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey* This is your Klevu JS API Key.
klevu_categoryName* This is the name of the category being visited. For example, Stackable Rings. The name should not include parent categories.
klevu_categoryPath* This is the complete hierarchy of the category being visited. For example, Jewellery;Rings;Stackable Rings. Please note the use of a semicolon as the separator between a parent and a child category.
klevu_productId* Id of the product that was clicked.
klevu_productName Name of the product that was clicked.
klevu_productUrl URL of the product that was clicked.
klevu_productSku SKU code of the product that was clicked.
klevu_salePrice Decimal sale price of the product that was clicked.
klevu_productRatings A decimal rating value between 0 and 5 of the product that was clicked.
klevu_productPosition Position of the product on the category page when it was clicked. For example, the value would be 0 if it is the first product on the first page. The value will be 30, if it is the first product on the 2nd page with 30 products being displayed per page.

Checked Out Products

URL

POST http://stats.klevu.com/analytics/productTracking

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>

Query Parameters

Parameter Name Description
klevu_apiKey* This is your Klevu JS API Key.
klevu_type* Here, the value must be checkout.
klevu_productId* This is the product code of the clicked product. Please note that the value of the klevu_productId must be the same in both the click and checkout calls (for the same product).
klevu_unit* This is the total quantity purchased. It must be an integer (e.g. 5).
klevu_salePrice* Product’s sale price for one unit. This must be a double Value.
klevu_currency* e.g GBP, USD, EUR.
klevu_shopperIP IP address of the shopper who bought the product(s).
If calling the checkout HTTP call from javascript, this is an optional parameter.