Guide
Smart Search
V1 (deprecated)
4min
The v1 APIs are now deprecated! If you are building a new implementation, we strongly recommend using API version 2 by going through V2 Overview
Depending on what details you want Klevu Search servers to return in response, you can use one of the following API methods to search in your index.
- For the “search as you type” sort of interface where you need query suggestions, matching categories, CMS pages and product suggestions, please use the “Search As You Type” method.
- For the search results landing page, if you only need a list of IDs of records relevant to your query, use the ID Search method.
- In addition to record IDs, if you want Klevu Search to return other details such as name, description, price, etc., use the Record Search method.
Both the ID Search and the Record Search methods have parameters that allow you to fetch filters/facets as well.
Use this API endpoint to build a search as you type solution. It produces query suggestions, category suggestions, CMS page suggestions and products matching the customer query.
GET
Request
Query Parameters
ticket
required
String
This is your Klevu JS API Key.
term
required
String
The actual term or a phrase searched by the shopper.
sv
required
String
The sv parameter is used for indicating which version of the Klevu Magento plugin you are using (e.g. 1.2.5). In case of a non-magento store, please use the constant value 20.0.0.
autoComplete
optional
Boolean
If true, the autosuggestions matching the submitted query terms are returned.
Default value is false.
typeOfSuggestions
optional
String
Used for specifying the kind of non-product suggestions (e.g. cms, category etc.) needed to be fetched. Use ":" as a separator. Possible values: cms, category
noOfResults
optional
Integer
Indicates the number of records to be fetched for each type of suggestions. For example, if set to 3, then 3 products, 3 categories and 3 cms pages will be returned.
noOfResultsAC
optional
Integer
Number of autocomplete suggestions to return.
enablePartialSearch
optional
Boolean
If true, the partial search is enabled. For example, searching for let may fetch both letter as well as tablet.
sortOrder
optional
String
If you want to sort results in certain order. please use one of the following values:
- rel for Relevance,
- lth for Price: Low to High,
- htl for Price: High to Low.
showOutOfStockProducts
optional
Boolean
True to include out of stock products in the search result set, false otherwise.
priceFieldSuffix
optional
String
If you are a shopify plus customer with the multicurrency feature enabled, you can now provide a currency (other than the base currency of your store), to fetch prices in that currency. If in case the prices are not available in the supplied currency, Klevu will return prices in the base currency of the store. e.g. priceFieldSuffix=USD
visibility
optional
String
Always set this parameter to search to include products with the visibility of search to be included in the result set.
resultForZero
optional
Number
In case the original query does not produce any result, setting this parameter to value 1, will bring products that are most popular on the site or are popular in the recentCategory as below.
recentCategory
optional
String
Name of a category whose product was clicked most recently. this parameter is used in conjuction with resultForZero parameter to produce suggestions in case no result is found for the query.
noOfResultsZero
optional
Integer
If the fallback results are enabled for when there is no result found for a query, this parameter tells how many results should be retrieved.
optionalFilters
optional
String
A parameter to enable personalisation. It instructs Klevu to boost products with the filter values specified here. In case of multiple filters, please use the double semicolon (;;) as a delimiter
With each filter value, one can assign a boost score.
For example, if in past a user was seen preferring green color products over any other color and brand to be nike, one can specify the optionalFilters as the following:
e.g. color:green^10;;brand:nike^3.0
Here, use ;; as a delimiter between two filter values and a score between 1 and 100 to boost filter options.
Values provided here should be the strings taken from the value attribute of the option element under the filters.
responseType
optional
String
Type of response to be returned. Possible values are xml or json
Use this API method if you want not only the record IDs but also other details associated with the matching records. The method allows you to retrieve facets and autosuggestions as well.
GET
Request
Query Parameters
ticket
required
String
This is your Klevu JS API Key.
term
required
String
The actual term or a phrase searched by the shopper.
sv
required
String
The sv parameter is used for indicating which version of the Klevu Magento plugin you are using (e.g. 1.2.5). In case of a non-magento store, please use the constant 20.0.0
paginationStartsFrom
optional
Integer
Index of the first record to be fetched. If for example showing 12 results per page, use the index 12 for the second page and 24 for the third page and so on. Default value is 0.
noOfResults
optional
Number
Indicates the number of records to be fetched. If for example, paginationStartsFrom is set to 0, it will obtain results from 0. Default value is 12.
enablePartialSearch
optional
Boolean
If true, the partial search is enabled. For example, searching for let may fetch letter as well as tablet. Default value is false.
category
optional
String
To filter results by specific category.
To fetch only products use KLEVU_PRODUCT as a value.
To fetch only Category pages, use KLEVU_CATEGORY as a value.
To fetch only CMS pages, use KLEVU_CMS as a value.
Use ~.~ as a delimiter when supplying more than one values.
e.g. KLEVU_PRODUCT~.~electronics~.~furniture
This will search for “products” where the category is either electronics or furniture.
enableFilters
optional
Boolean
If set to true, filters relevant to the search results are retrieved and included in the response. The default value is false.
enableMultiSelectFilters
optional
Boolean
If set to true, we treat different values of a filter as checkboxes. Otherwise, if set to false, they are treated as radio buttons.
e.g. color:green;;color:white;;brand:nike
When set to true, it finds products with either green OR white color with the brand nike. When set to false, it finds products with both green AND white color AND brand nike. Default value is false.
applyFilters
optional
String
Tells Klevu which filters to apply on the search results. In case of multiple filters, please use the double semicolon (;;) as the delimiter.
Values provided here should be the strings taken from the value attribute of the option element under the filters.
e.g. color:green;;color:white;;brand:nike
maxNoOfValuesInAFilter
optional
Integer
Number of values to return for each filter. The default is 50.
sortOrder
optional
String
If you want to sort results in certain order, please use one of the following values:
- rel for Relevance,
- lth for Price: Low to High,
- htl for Price: High to Low.
The default value is rel.
showOutOfStockProducts
optional
Boolean
True to include out of stock products in the search result set, false otherwise. The default value is false.
fetchMinMaxPrice
optional
Boolean
If set to true, it returns the minimum and maximum prices found for the obtained search results. This can be used, for example, for displaying price slider. If set to false, Klevu will return price ranges (e.g. 0-500, 500-1000 etc.). The price range intervals are dynamically generated by Klevu. The default value is false.
priceFieldSuffix
optional
String
If you are a shopify plus customer with the multicurrency feature enabled, you can now provide a currency (other than the base currency of your store), to fetch prices in that currency. If in case the prices are not available in the supplied currency, Klevu will return prices in the base currency of the store. e.g. priceFieldSuffix=USD
visibility
optional
String
Always set this parameter to search to include products with the visibility of search to be included in the result set. The default value is search.
resultForZero
optional
Integer
In case the original query does not produce any result, setting this parameter to value 1, will bring products that are most popular on the site or are popular in the recentCategory as below. The default value is 0.
recentCategory
optional
String
Name of a category whose product was clicked most recently. this parameter is used in conjuction with resultForZero parameter to produce suggestions in case no result is found for the query.
noOfResultsZero
optional
Integer
If the fallback results are enabled for when there is no result found for a query, this parameter tells how many results should be retrieved. The default value is 5.
optionalFilters
optional
String
A parameter to enable personalisation. It instructs Klevu to boost products with the filter values specified here. In case of multiple filters, please use the double semicolon (;;) as a delimiter
With each filter value, one can assign a boost score.
For example, if in past a user was seen preferring green color products over any other color and brand to be nike, one can specify the optionalFilters as the following:
e.g. color:green^10;;brand:nike^3.0
Here, use ;; as a delimiter between two filter values and a score between 1 and 100 to boost filter options.
Values provided here should be the strings taken from the value attribute of the option element under the filters.
responseType
optional
String
Type of response to be returned. Possible values are xml or json. The default value is xml.
lsqt
optional
String
When you receive a response for a search query, look at the value of the typeOfQuery element under the metaData section. When you fire a subsequent query (e.g. to apply additional filters, or to obtain results for the next page), pass this value as the value of the lsqt (last search query type) parameter. Possible values are WILDCARD_AND, FUZZY_AND, OR, FUZZY_OR.
fl
optional
String
When Klevu returns search results, the response has certain fields for each record included. If you like to retrieve only a set of selected filters, use a list of comma separated field names.
Use this API method if you require only the IDs of the records matching your query. The method also allows you to retrieve facets associated with the search results.
GET
Request
Query Parameters
ticket
required
String
This is your Klevu JS API Key.
term
required
String
The actual term or a phrase searched by the shopper.
sv
required
String
The sv parameter is used for indicating which version of the Klevu Magento plugin you are using (e.g. 1.2.5). In case of a non-magento store, please use the constant 20.0.0
paginationStartsFrom
optional
Integer
Index of the first record to be fetched. If for example showing 12 results per page, use the index 12 for the second page and 24 for the third page and so on. Default value is 0.
noOfResults
optional
Number
Indicates the number of records to be fetched. If for example, paginationStartsFrom is set to 0, it will obtain results from 0. Default value is 12.
enablePartialSearch
optional
Boolean
If true, the partial search is enabled. For example, searching for let may fetch letter as well as tablet. Default value is false.
category
optional
String
To filter results by specific category.
To fetch only products use KLEVU_PRODUCT as a value.
To fetch only Category pages, use KLEVU_CATEGORY as a value.
To fetch only CMS pages, use KLEVU_CMS as a value.
Use ~.~ as a delimiter when supplying more than one values.
e.g. KLEVU_PRODUCT~.~electronics~.~furniture
This will search for “products” where the category is either electronics or furniture.
enableFilters
optional
Boolean
If set to true, filters relevant to the search results are retrieved and included in the response. The default value is false.
enableMultiSelectFilters
optional
Boolean
If set to true, we treat different values of a filter as checkboxes. Otherwise, if set to false, they are treated as radio buttons.
e.g. color:green;;color:white;;brand:nike
When set to true, it finds products with either green OR white color with the brand nike. When set to false, it finds products with both green AND white color AND brand nike. Default value is false.
applyFilters
optional
String
Tells Klevu which filters to apply on the search results. In case of multiple filters, please use the double semicolon (;;) as the delimiter.
Values provided here should be the strings taken from the value attribute of the option element under the filters.
e.g. color:green;;color:white;;brand:nike
maxNoOfValuesInAFilter
optional
Integer
Number of values to return for each filter. The default is 50.
sortOrder
optional
String
If you want to sort results in certain order, please use one of the following values:
- rel for Relevance,
- lth for Price: Low to High,
- htl for Price: High to Low.
The default value is rel.
showOutOfStockProducts
optional
Boolean
True to include out of stock products in the search result set, false otherwise. The default value is false.
fetchMinMaxPrice
optional
Boolean
If set to true, it returns the minimum and maximum prices found for the obtained search results. This can be used, for example, for displaying price slider. If set to false, Klevu will return price ranges (e.g. 0-500, 500-1000 etc.). The price range intervals are dynamically generated by Klevu. The default value is false.
priceFieldSuffix
optional
String
If you are a shopify plus customer with the multicurrency feature enabled, you can now provide a currency (other than the base currency of your store), to fetch prices in that currency. If in case the prices are not available in the supplied currency, Klevu will return prices in the base currency of the store. e.g. priceFieldSuffix=USD
visibility
optional
String
Always set this parameter to search to include products with the visibility of search to be included in the result set. The default value is search.
resultForZero
optional
Integer
In case the original query does not produce any result, setting this parameter to value 1, will bring products that are most popular on the site or are popular in the recentCategory as below. The default value is 0.
recentCategory
optional
String
Name of a category whose product was clicked most recently. this parameter is used in conjuction with resultForZero parameter to produce suggestions in case no result is found for the query.
noOfResultsZero
optional
Integer
If the fallback results are enabled for when there is no result found for a query, this parameter tells how many results should be retrieved. The default value is 5.
optionalFilters
optional
String
A parameter to enable personalisation. It instructs Klevu to boost products with the filter values specified here. In case of multiple filters, please use the double semicolon (;;) as a delimiter
With each filter value, one can assign a boost score.
For example, if in past a user was seen preferring green color products over any other color and brand to be nike, one can specify the optionalFilters as the following:
e.g. color:green^10;;brand:nike^3.0
Here, use ;; as a delimiter between two filter values and a score between 1 and 100 to boost filter options.
Values provided here should be the strings taken from the value attribute of the option element under the filters.
responseType
optional
String
Type of response to be returned. Possible values are xml or json. The default value is xml.
lsqt
optional
String
When you receive a response for a search query, look at the value of the typeOfQuery element under the metaData section. When you fire a subsequent query (e.g. to apply additional filters, or to obtain results for the next page), pass this value as the value of the lsqt (last search query type) parameter. Possible values are WILDCARD_AND, FUZZY_AND, OR, FUZZY_OR.
fl
optional
String
When Klevu returns search results, the response has certain fields for each record included. If you like to retrieve only a set of selected filters, use a list of comma separated field names.
Updated 30 Oct 2023
Did this page help you?