NAV Navbar
API version 1 | API version 2

API Version 2

Request URL:

Request payload:

Response data:

Klevu APIv2 is the latest version of our API for integrating Klevu Search and Smart Category Navigation into your applications for lightning fast quick search, search results and category pages.

Some highlights of Klevu APIv2 are:

Try it yourself, hit the 'Execute' button in the side panel --->


Need help?
Find support in our Community Forum.

Building a headless frontend?
Klevu JavaScript Library provides a fast, flexible frontend for APIv2.

Prerequisites

If you don't have a Klevu account yet, you can still try Search using the demo credentials below.

If you already have a Klevu account, please access the 'Shop Info' tab of your Klevu Merchant Centre to retrieve:

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.

JS API Key

The Klevu JS API Key is the public identifier of your store. It is used in API search requests to identify which store to retrieve data from. The JS API Key does not need to be kept a secret, as it is used in public API requests.

It is made up of the prefix klevu- followed by a sequence of numbers unique to your store, for example:

klevu-156925593843210765

If you have signed up for multiple stores, you should have a unique JS 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 JS API key.

Search URL

For retrieving data, Klevu APIv2 utilises a single endpoint:

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

Please replace the subdomain with your own, which you can find in the Prerequisites above. For example, if your URL Subdomain is 'eucs15' 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 search will not be using our Content Delivery Network (CDN).

CatNav URL

In addition to search results, Klevu can also power your category pages. We call this feature 'Smart Category Navigation', or CatNav for short.

With APIv2 the Endpoint URL for Category Navigation is the same as for Search. Within the request body you will be able to specify whether it is a Search or Category query.

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.

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:

Search API

This section explores how to build Search and CatNav queries to retrieve your store data from Klevu. Within each topic you will find an example to the right, which you can try for yourself.

JSON Structure

Request URL:

Request payload:

Response data:

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.

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:

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:

Typeahead Suggestions

Request URL:

Request payload:

Response data:

The suggestions object is used for fetching autocomplete suggestions. This allows you to try and predict what the customer might be looking for and propose relevant search queries applicable to your catalog.

For example when the customer starts typing "a", Klevu can start making suggestions. For example it may suggest some terms starting with the letter "a" like "arris desk". It may also suggest terms not starting with "a" such as "black arris desk".

The Klevu suggestions are error tolerant, e.g. "fairry lights" would find suggestions for "fairy lights", and also order tolerant, e.g. "lights fairy" would find suggestions for "fairy lights".


Request Format

Parameter Description
id Every suggestion request must have a unique identifier associated with it. When a result is retrieved, the ID of each query is associated with it's respective response.
typeOfQuery The type of suggestion query. Specify 'AUTO_SUGGESTIONS' for typeahead autosuggestion predictions.
query The search term or phrase for which the suggestions are retrieved from Klevu Search.
limit The maximum number of suggestions to be retrieved.
hlStartElem, hlEndElem By default, the section of an autosuggestion matching what the customer has typed is highlighted in bold using values of '<b>' and </b>'. If you prefer something else, you can override these values with your own HTML.


Response Format

Since you can make multiple suggestion queries within the same HTTP request, one object is returned for every suggestion query requested. The id in each result is the one provided for the respective query.

The characters matching those in the query are highlighted in 'bold', unless you have specified otherwise using hlStartElem and hlEndElem.

Searching for Records

Request URL:

Request payload:

Response data:

The recordQuery object is used for searching for records. Use this for retrieving Products, Categories or CMS Pages when your customer has submitted a search query.


Request Format

Parameter Description
id Every record search request must have a unique identifier associated with it. When a result is retrieved, the ID of each query is associated with it's respective response.
typeOfRequest This parameter defines the type of request it is, which should be 'SEARCH' for search queries. There are other values available, detailed elsewhere in the documentation.
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.
limit The maximum number of records to retrieve.
typeOfRecords Here you can specify the types of records to be retrieved, for example KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY, etc.

In the case where more than one type of record is specified, the results fetched may be a mixture of all the different types of records specified.

The maximum number of results retrieved will never be more than the limit specified. Should you wish to retrieve records of each type separately, for example 5 Products + 5 Categories, a separate query must be submitted for each data type required.


Response Format

Parameter 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.

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.

Category Navigation

Request URL:

Request payload:

Response data:

Klevu can also power your category pages using Smart Category Navigation. This is quite similar to a record search, however instead of providing the search term your customer has entered you will specify the category they are vising.

There are two main differences between a record search query and a category navigation query:

Any of the request parameters available for a record search can also be used for category navigation.


Request Format

Parameter Description
typeOfRequest This parameter defines the type of request it is, which should be 'CATNAV' for category navigation queries. There are other values available, detailed elsewhere in the documentation.
categoryPath Specify the name of the category to retrieve results from, in the same case and format as it is indexed with Klevu.

For nested categories, use the ; character to separate the hierarchy. For example, for 'Mens > Shoes > Trainers and Sneakers' you would specify: Mens;Shoes;Trainers and Sneakers.

Filtering Results

While searching for records, you can also request aggregations of the attribute values within the search results, so you can allow your customers to filter the results further.

For example, if the search query was "tops", you may also be interested to know all of the colors, sizes and materials that these tops are available in to display them as selectable facets or filters.

There are two separate methods of working with filters with the Klevu search API:

To apply a filter, you need to know the key of the relevant filter and the value of the relevant option, which should be submitted using the same format and case sensitivity as is returned by Klevu.

Retrieving Filters

Request URL:

Request payload:

Response data:

The filtersToReturn object can be used for obtaining filters from the Klevu Search engine. You can request all possible filters or only those matching certain criteria.

Request Format

Parameter Description
enabled Whether or not to return any filters with this query. This defaults to false so no filters are returned unless requested.
include This is the list of filter keys that you would like to retrieve as filters. A filter may also not be returned if there aren't enough applicable records in the result set.
exclude This is the list of filter keys that you do not want Klevu Search to include in the response. If a filter is specified in both include and exclude lists, include will take precedence.
options Specify how the filters' options are included in the response.

order: A value of 'FREQ' will sort options based on the number of records each option has in the result set. 'INDEX' will sort the options alphabetically.

limit: Specify 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 an option count equal to or higher than the minCount are included.
rangeFilterSettings When minMax is false, this setting allows you to retrieve range filters for use with numeric values such as price, so you can display bands of 0-99, 100-199, etc. or a price slider.

key: This is the identifier of your numerical attribute, eg. 'klevu_price'.

minMax: If set to true, the Klevu Search engine calculates the minimum and maximum values for this filter for use with a slider.

rangeInterval: If a positive value is provided, the Klevu Search engine will calculate ranges for this value. For example a value of 100 would give ranges from 0 to 99, 100 to 299, etc.

By default all attributes submitted to Klevu are indexed as STRING attributes, which means they cannot be used as range filters. The product sale price field is the only exception to this rule, which is filtered using the key klevu_price. If you have explicitly requested and Klevu has approved that certain attributes be indexed as numerical attributes, you can also retrieve those as range filters.

There are also some Search Preferences which you can utilise to further control your filters.


Response Format

Each filter object within filters represents one attribute and a set of options, which will vary depending on the whether it is type OPTIONS or SLIDER. OPTIONS filters include multiple results whereas SLIDER filters include range data.

Parameter Description
key This is the unique identifier of the attribute for which options are being provided.
label This is the label or caption which you have associated with the attribute in the Klevu Merchant Centre.
type The type of the filter will be either OPTIONS or SLIDER. For an OPTIONS filter, its different options, eg. red, blue, black, are provided. For a SLIDER filter, values such as minimum, maximum, start and end are provided in the response.
options For type OPTIONS this will contain an array of different options available.

name: The label or caption of the option, eg. Red, Blue, Black, etc.

value: This is the unique identifier which should be used when applying a filter to search results.

count: The number of records found with the current option in the current search results.

selected: Whether ot not the current option is already applied as a filtering condition on the search results.
min, max, start, end These values are provided only for the SLIDER or range filters.

min, max: These values are the minimum and maximum values found in the current result set. This can be used to set the upper and lower limits of your slider.

start, end: The start and end values are the filtering conditions already applied on the result set for this filter, or NULL if no filter has been applied.


Applying Filters

Request URL:

Request payload:

Response data:

The applyFilters object can be used for applying filter conditions so your customers can fine-tune their results based on relevant attributes.

Request Format

Parameter Description
key The ID of the attribute to filter by, eg. color
values An array of values to filter by, eg. Red, Blue.

When using range filters, specify the first value as the minimum value and the second as the max value. For example to retrieve records with prices between 60 to 80, use: "key": "klevu_price", "values": [60, 80].

To retrieve steps of prices, for example those with values between 0-50 or 150-200, use: "key": "klevu_price", "values": ["0-50", "150-200"].

To retrieve exact values, for example records with exact values 100 or 200, use: "key": "klevu_price", "values": ["100-100", "200-200"].

By default all attributes submitted to Klevu are indexed as STRING attributes, which means they cannot be used as range filters. The product sale price field is the only exception to this rule, which is filtered using the key klevu_price. If you have explicitly requested and Klevu has approved that certain attributes be indexed as numerical attributes, you can also retrieve those as range filters.
singleSelect The behaviour when specifying multiple filters or values. See the notes below for more information on how to use this field.

There are also some Search Preferences which you can utilise to further control filters.


Response Format

If only one filter is applied with only value, Klevu search ensures that all the records returned contain the relevant attribute with the specified value.

In the case where two or more values for the same filter are provided, the execution is dependent on the value of the singleSelect parameter.

If constraints are added for multiple filters and the value of the singleSelect filter is false, the products returned must have at least one value from each of the filter conditions provided.

Performance with Filters

It is important to note that retrieving filters is an expensive operation which can slow down your search experience. For this reason you may want to fetch filters once per unique query and cache them locally.

For example when using pagination to retrieve records from subsequent pages, there is actually no need to fetch the filters again since these will not change from page to page. The filters from Klevu are always for the entire set of records for that query.

Settings

There are numerous settings, preferences and configurations available with APIv2 to fine-tune your search and category navigation queries. This section explores them in more detail.

Sorting

Request URL:

Request payload:

Response data:

The default sorting of results is RELEVANCE, which uses Klevu A.I. to determine the order. There are various other options available which you can provide to your customers as required.

Parameter Description
RELEVANCE This is the default sort order, which uses a combination of Klevu A.I. and your own merchandising configuration to determine the order of the results. Please read this article for more information about how Klevu ranks and orders the results.
PRICE_ASC, PRICE_DESC Sort the results by the salePrice value of each record.
NAME_ASC, NAME_DESC Sort the results by the name of each record, in alphabetical order.
RATING_ASC, RATING_DESC Sort the results by each record's average rating, if this data has been indexed in your store.
NEW_ARRIVAL_ASC, NEW_ARRIVAL_DESC Sort your records based on their published date. Please see this support article for important information about sorting by newness.

Pagination

Request URL:

Request payload:

Response data:

You may wish to split larger result sets over multiple pages. You can do this using pagination. Simply specify a page size for how many results each page should include, and an offset of which record to start each result set from.


Request Format

Parameter Description
limit Specify the number of record you would like to display per page.
offset Specify the index at which to start counting the number of results from.

The index of the first record in a result set is 0. Thus, if you want to start from the 6th result, use an offset of 5.
typeOfSearch After the first has been retrieved, for subsequent pagination requests it is recommended to include the typeOfSearch value using the same value that came back in the meta data with the results of the first result. This will give a performance benefit since Klevu does not need to try different search types, and will also assure consistency of results across pages.


Response Format

In order to understand how many more pages are available for your result set, you can use the meta data returned with each query result.

Parameter Description
noOfResults The number of results requested to be returned for this query.
totalResultsFound The total number of results found for this query.
offset The index of the first result returned in this response.
typeOfSearch The query type that was executed by Klevu to retrieve the results.

Limiting Fields

Request URL:

Request payload:

Response data:

By default, Klevu will return most of the data available in a record. If you only need certain elements and want to keep the response size small for performance reasons, you can specify only the fields you are interested in.

Parameter Description
fields An array of the attribute IDs that you wish to retrieve, eg. "id", "name", "salePrice", etc. Please refer to Searching for Records to see all of the available fields.

Grouping Results

Request URL:

Request payload:

Response data:

The groupBy parameter takes the name of a field indexed in the Klevu Search backend and ensures that there is only one record for each unique value of this field in the search results.

By default, the groupBy operation is performed on the itemGroupId field. When querying for KLEVU_CATEGORY or KLEVU_CMS records, it is recommended to use name as the groupBy parameter value.

Parameter Description
groupBy The key of the attribute to group by, for example 'name'.

Request URL:

Request payload:

Response data:

The typeOfSearch parameter defines the behaviour when identifying matches for a searched term. For example, whether all or just one of the entered words must be matched, whether to allow spelling mistakes, etc.

Request Format

Parameter Description
DEFAULT When this value is specified, Klevu will go through a number of attempts to find matching records. The first type attempted is WILDCARD_AND. If there aren't any results found, Klevu tries to find products with the FUZZY_AND query type.

As long as no matches are found, Klevu will continue to fire different query types in the following order:
  1. WILDCARD_AND
  2. FUZZY_AND
  3. WILDCARD_OR
  4. FUZZY_OR
Note that when a search term only contains a single word, or more than six words, the 'OR' query types will be skipped.
WILDCARD_AND This is an 'AND' query so all words of the query must be found somewhere in a record for it to be included in the results. The last word of the query will have a wildcard suffix appended.

For example, if the searched query is "hooded jacket", this will become "hooded jacket*", ie. Klevu will try to find records containing the word "hooded" AND any words beginning with "jacket".
FUZZY_AND This is the same as a WILDCARD_AND query, however a certain amount of 'fuzziness' is allowed to account for spelling mistakes.

For example, if the searched query contains spelling mistakes like "hooder jakcet", Klevu will still be able to match any records containing the words "hooded" AND "jacket".
WILDCARD_OR This is an 'OR' query so at least one of the words in the query must be found somewhere in a record for it to be included in the results. The last word of the query will have a wildcard suffix appended.

For example, if the searched query is "hooded jacket", this will become "hooded jacket*", ie. Klevu will try to find records containing the word "hooded" OR any words beginning with "jacket".
FUZZY_OR This is the same as a WILDCARD_OR query, however a certain amount of 'fuzziness' is allowed to account for spelling mistakes.

For example, if the searched query contains spelling mistakes like "hooder jakcet", Klevu will still be able to match any records containing the words "hooded" OR "jacket".
AND All of the exact words of a query must be found in a record for it to be included in the results. No fuzziness or wildcards are included.

For example a search for "hooded jacket" will only return records which contain the exact terms "hooded" AND "jacket".
OR At least one exact word of a query must be found in a record for it to be included in a results. No fuzziness or wildcards are included.

For example a search for "hooded jacket" will only return records which contain one of the exact terms "hooded" OR "jacket".

There are also Search Preferences you can specify to control this logic further.

Search Preferences

Request URL:

Request payload:

Response data:

There are a number of preferences available for fine-tuning your queries. For example you can control whether or not to allow fuzzy search for spelling mistakes on a query by query basis. The available searchPrefs are detailed below.

Parameter Description
showOutOfStockProducts, hideOutOfStockProducts Whether or not your store should include 'Out of Stock' products in search results by default can be configured within the Klevu Merchant Centre. However, if you would like to override this for a particular query, please include one of these flags.
disableStockSorting This can be used in conjunction with showOutOfStockProducts. If your store is configured to display out of stock products, they will be displayed at the very end of the search results after all in stock products have been displayed. By using this flag you can disable this logic, and cause all products to be ranked in an order that disregards their stock status.
includeStopwords By default, functional words such as prepositions, pronouns, articles, etc. are excluded from searches. Add this flag to include these stopwords in your search.
excludeIds Use this flag to disable the searching of record IDs.
includeDescription, excludeDescription Whether or not a record's 'description' is considered for search results can be configured by Klevu Support on a store by store basis, however if you would like to override this for a particular query, please include one of these flags.
disableFuzzyMatch This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the FUZZY_AND and FUZZY_OR search types from being attempted.
disableWildcard This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the WILDCARD_AND and WILDCARD_OR search types from being attempted.
disableORSearch This flag can be used in conjunction with the typeOfSearch 'DEFAULT' to disable the WILDCARD_OR and FUZZY_OR search types from being attempted.
partialMatch Enable partial match for the last word of a query, where the last word searched can be a substring of any other word found in a record. This can be useful for non-English languages.

For example let's say a product has the name "rödvinsglas" (red wine glass). If searching for "högt glas" (tall glass) it may not match since the record has no words starting with 'glas'. By providing this flag, the search would become "högt *glas*" meaning it would match the record since it contains a word which ends with 'glas'.
partialMatchForAllWords Similar to partialMatch, but for all words rather than just the last. In the same "rödvinsglas" example, a search for "högt glas" would become "*högt* *glas*", so any records containing words containing 'högt' or 'glas' would result in a match.
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. You can use this flag to disable such boosting.
searchCompoundsAsAndQuery When a compound word is searched for, i.e. two or more individual words joined together as one word, Klevu automatically disjoints them if the de-compounding feature is enabled for your store.

For example, a search for "fairylights" would be treated as "fairy lights", but with the added condition that those words must appear within 5 words of each other in a matching record.

If you would prefer that the words "fairy" and "light" could be found anywhere within the record, not necessarily near one another, then please include this flag.
enableBoostingOriginalTermsInSynonyms By default, synonyms are treated equally to their query term. Should you wish to give higher priority to the actual terms your customer entered in the query over their synonyms, please include this flag in your search preferences.
showDisabledFacets It is possible to configure which facets or filters should be enabled or disabled within the Klevu Merchant Centre. By including this flag, all facets will be returned regardless of whether they have been disabled in the KMC.
showFiltersWithSmallCount By default some filters are excluded from the results if they only have a small number of results. Please use this flag to override this logic and include all filters in the response.
includeCategoryFilterInCatNav When the typeOfRequest is 'CATNAV', the filter for 'Category' is automatically excluded since you are already within the context of a category. Use this flag to override this logic and return the category filters even for CatNav requests.
enableScores Include the score information with the response fields: score, klevu_manual_boosting, klevu_bulk_boosting and klevu_selflearning_boosting.
debugQuery Use this flag to include additional information about the query execution. This information is populated in the meta object of the response.

Please note that it is not recommended to enable this flag in your Production environment, as performance will be impacted.

Features

Multiple Queries

Request URL:

Request payload:

Response data:

Klevu APIv2 allows you to request multiple Product, Category and CMS Page 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:

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.

Fallback Queries

Request URL:

Request payload:

Response data:

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.

Request Format

Parameter Description
fallbackQueryId The ID of another query which should be fired if the current query yields too few results.
fallbackWhenCountLessThan 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 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.

Hand-Picked Products

Request URL:

Request payload:

Response data:

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.


Request Format

Parameter Description
topIds 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 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 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.

Custom Queries

Request URL:

Request payload:

Response data:

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 belong to the brand "KKE."

Parameter Description
customANDQuery The custom query you would like to fire, which Klevu automatically converts into an appropriate query to be fired on its index. 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.

Multi-Currency

Request URL:

Request payload:

Response data:

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:

Parameter Description
priceFieldSuffix 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.

Customer Groups

Request URL:

Request payload:

Response data:

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:

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'.

Parameter Description
priceFieldSuffix 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}, with any dashes - in your group ID escaped by doubling them to --. For example if your indexed group ID is 'my-group-1', your query should include my--group--1
visibilityGroupID 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}, with any dashes - in your group ID escaped by doubling them to --. For example if your indexed group ID is 'my-group-1', your query should include my--group--1

Personalisation

When a customer enters a physical shop, they may express their preferences to an in-store assistant by highlighting the colours they like, the brands they prefer and what they have purchased before.

The in-store assistant would then use this information to show the customer products they are most likely interested in first, before showing them any others that still may be suitable.

Klevu A.I. is your online assistant.

This personalisation can be provided in two ways:

  1. including some information about the customer's browsing history with each request
  2. defining your own boosting rules based on information you already know about the customer

You can read more about how this works in our Personalisation PDF Document.

The personalisation add-on must be enabled for your store to utilise these features.

Browsing History

Request URL:

Request payload:

Response data:

If you provide the IDs of products which the customer has recently interacted with, the Klevu A.I. will figure out the common aspects of those products and influence the search results.

The easiest way to highlight this is with an example:

Note that the impact of the personalisation is not always apparent. Klevu is clever. If the customer has recently been looking at 'shoes' but now they are searching for 'washing machines', Klevu will know to disregard any interactions that are not relevant to the current search query.

Request Format

Parameter Description
enablePersonalisation This must be set to 'true' for enabling personalisation on a particular request. If set to 'false', the recent objects within the context object will be ignored
fields This is an optional field. By default, Klevu will analyse all attributes of the records the customer has interacted with, in order to determine the common patterns. If you prefer to focus on particular aspects, for example brand or price, specify those attributes within this object.
recentObjects Use this object to specify the records (e.g. products, categories, etc.) that were recently interacted with by a customer.

Please only specify one recentObject object per record type, one for all KLEVU_PRODUCT entries, another for all KLEVU_CMS pages visited, etc.

Each recentObject object may contain multiple record objects (e.g. 5 recently viewed products). The most recently clicked record should be the first element in the array.


Known Preferences

Request URL:

Request payload:

Response data:

If you have already built up a profile of your customer and would like to use what you know about them to promote certain results, you can use the boost object within each record query.

There are three ways the records can be boosted:

For example let's say you have an online store with an area where customers can log in.

As a merchant with all of this information available, you can build up a profile about this customer. The sample to the right shows how you would convey this information to Klevu during a search.

To find out more about how boosting works with your existing merchandising rules, please read this article on How Personalisation Works.

Request Format

Parameter Description
filters Specify filter values to apply a boosting score to. They key is the unique identifier of the attribute, eg. Color. Each of the values represents the value of that filter to boost, eg. red or blue.
keywords Specify keywords or phrases to apply a boosting score to, for example "comfortable".
records Specify the Klevu ID of any records to apply a boosting score to.
weight The boosting value to be applied, a decimal between 0 - 999. Please specify values above 1 for boosting the records up the rankings, and a value of 0 to 1 to de-boost records down the rankings.

Indexing

Every record in your store which you would like to be searchable, for example Products, Categories or CMS Pages, must be sent to Klevu to be enriched and stored in a dedicated index. This process is called indexing.

Please refer to the APIv1 Indexing documentation for how to submit and retrieve the required information.

Analytics

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

Please refer to the APIv1 Analytics documentation for how to submit the required information.