NAV Navbar
API version 1 | API version 2
xml json

API Version 1 (legacy)

For frontend integration of Search or Smart Category Navigation, please consider using the newest version of our API, Klevu APIv2. For submission of data for indexing, please use this APIv1 documentation.

Prerequisites

You must have a Klevu Search account to use the Klevu API. Please access the 'Shop Info' tab of your Klevu Merchant Centre to retrieve the following credentials.

Please write to us at support@klevu.com if you have trouble finding any of this information.

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>

Prerequisites:

You will need your REST API Key and Product Synchronization URL. Please refer to the Prerequisites section for more information.

URL

POST https://<productSynchronizationURL>/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: Electronics;Mobiles & Accessories;Tablet, with each part of the hierarchy separated by a ; semicolon and the higher level categories coming before the more specific ones.

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.

Prerequisites:

You will need your REST API Key and Product Synchronization URL. Please refer to the Prerequisites section for more information.

URL

POST https://<productSynchronizationURL>/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 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: Electronics;Mobiles & Accessories;Tablet, with each part of the hierarchy separated by a ; semicolon and the higher level categories coming before the more specific ones.

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 an element is the same as the format of the 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.

Prerequisites:

You will need your REST API Key and Product Synchronization URL. Please refer to the Prerequisites section for more information.

URL

POST https://<productSynchronizationURL>/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.

Prerequisites:

You will need your REST API Key and Product Synchronization URL. Please refer to the Prerequisites section for more information.

URL

POST https://<productSynchronizationURL>/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

Depending on what details you want Klevu Search servers to return in a response, you can use one of the following API methods to search in your index.

Both, the ID Search and the Record Search methods, have parameters that allow you to fetch filters/facets as well.

See the individual API methods for more details.

Search As You Type

Use this API endpoint to build search as you type solutions. It produces query suggestions, category suggestions, CMS page suggestions and products matching the customer query.

Prerequisites:

You will need your JS API Key and Cloud Search URL. Please refer to the Prerequisites section for more information.

URL

POST https://<cloudSearchURL>/cloud-search/n-search/search

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <meta>
    <totalResultsFound>554</totalResultsFound>
    <typeOfQuery>WILDCARD_AND</typeOfQuery>
    <paginationStartFrom>0</paginationStartFrom>
    <noOfResults>2</noOfResults>
  </meta>
  <result>
    <itemGroupId>96</itemGroupId>
    <klevu_product_boosting>1.0</klevu_product_boosting>
    <image>https://www.myshop.com/media/klevu_images/c/-/c-134-image-copy-8179_1_2.jpg</image>
    <shortDesc/>
    <sku>C-134D-C-134D06</sku>
    <startPrice>30</startPrice>
    <url>https://www.myshop.com/c-134d</url>
    <storeBaseCurrency>USD</storeBaseCurrency>
    <currency>$</currency>
    <id>96-95</id>
    <groupPrices/>
    <category>prier c-134/234 freezeless wall hydrants</category>
    <price>30</price>
    <name>Prier C-134D Freezeless Wall Hydrant with 1/2" MIP x 1/2" SWT Connection</name>
    <brand>Complete Plumbing Source</brand>
    <salePrice>30</salePrice>
    <totalVariants>11</totalVariants>
    <rating>4.0<rating/>
    <inStock>yes</inStock>
  </result>
  <result>
    <itemGroupId/>
    <klevu_product_boosting>1.0</klevu_product_boosting>
    <image>https://www.myshop.com/media/klevu_images/r/o/royerlkc_2.jpg</image>
    <shortDesc/>
    <sku>658LKCC1</sku>
    <url>https://www.myshop.com/royer-6-5-8lkcc1-aluminum-locking-conduit-well-cap-for-6-5-8-o-d-well-casings</url>
    <storeBaseCurrency>USD</storeBaseCurrency>
    <currency>$</currency>
    <id>88</id>
    <groupPrices/>
    <category>royer aluminum locking conduit well caps</category>
    <price>47.5</price>
    <name>Royer 6-5/8LKCC1 Aluminum Locking Conduit Well Cap for 6-5/8" O.D. Well Casings</name>
    <brand>Royer</brand>
    <salePrice>47.5</salePrice>
    <totalVariants>0</totalVariants>
    <rating>2.0</rating>
    <inStock>yes</inStock>
  </result>
  <!-- the following came out because of the typeOfSuggestions=category -->
  <categories>
    <name>Plumbing</name>
    <url>https://www.myshop.com/plumbing-supplies</url>
    <shortDesc>Complete Plumbing Source offers a wide range of quality
               plumbing supplies at competitive rates. We have everything
               you need to complete your residential or commercial
               plumbing project, from sump pumps</shortDesc>
   </categories>
   <categories>
     <name>Plumbing Valves</name>
     <url>https://www.myshop.com/plumbing-valves</url>
     <shortDesc>Complete Plumbing Source stocks a wide variety of plumbing
                valves and check valves in a variety of sizes and materials.
                If you don’t see the valve you require, please contact our
                plumbing experts. W...</shortDesc>
   </categories>
   <!-- autosuggestions coming out because autoComplete=true -->
   <autoComplete>
     <term>kohler <b>plumb</b>ing parts</term>
     <term><b>plumb</b>er's torches, solder & flux</term>
     <term><b>plumb</b>ing</term>
     <term>complete <b>plumb</b>ing source</term>
     <term><b>plumb</b>ing:_all:br_a.y mcdonald</term>
  </autoComplete>
</data>
{
  "meta": {
    "noOfResults": 3,
    "paginationStartFrom": 0,
    "totalResultsFound": 268,
    "typeOfQuery": "WILDCARD_AND"
  },
  "result": [
    {
      "itemGroupId": "96",
      "klevu_product_boosting": "1.0",
      "image": "https://www.myshop.com/media/klevu_images/c/-/c-134-image-copy-8179_1_2.jpg",
      "shortDesc": "",
      "sku": "C-134D-C-134D06",
      "startPrice": "30",
      "url": "https://www.myshop.com/c-134d",
      "storeBaseCurrency": "USD",
      "currency": "$",
      "id": "96-95",
      "groupPrices": "",
      "category": "prier c-134/234 freezeless wall hydrants",
      "price": "30",
      "name": "Prier C-134D Freezeless Wall Hydrant with 1/2\" MIP x 1/2\" SWT Connection",
      "brand": "Complete Plumbing Source",
      "salePrice": "30",
      "totalVariants": "11",
      "rating": "4.0",
      "inStock": "yes",
    },
    {
      "itemGroupId": "",
      "klevu_product_boosting": "1.0",
      "image": "https://www.myshop.com/media/klevu_images/r/o/royerlkc_2.jpg",
      "shortDesc": "",
      "sku": "658LKCC1",
      "url": "https://www.myshop.com/royer-6-5-8lkcc1-aluminum-locking-conduit-well-cap-for-6-5-8-o-d-well-casings",
      "storeBaseCurrency": "USD",
      "currency": "$",
      "id": "88",
      "groupPrices": "",
      "category": "royer aluminum locking conduit well caps",
      "price": "47.5",
      "name": "Royer 6-5/8LKCC1 Aluminum Locking Conduit Well Cap for 6-5/8\" O.D. Well Casings",
      "brand": "Royer",
      "salePrice": "47.5",
      "totalVariants": "0",
      "rating": "2.0",
      "inStock": "yes",
    }
  ],

  "autoComplete": [
    "kohler <b>plumb</b>ing parts",
    "<b>plumb</b>er's torches, solder & flux",
    "<b>plumb</b>ing",
    "complete <b>plumb</b>ing source",
    "<b>plumb</b>ing:_all:br_a.y mcdonald"
  ],

  "pages": [],
  "categories": [
    {
      "name": "Plumbing",
      "url": "https://www.myshop.com/plumbing-supplies",
      "shortDesc": "Complete Plumbing Source offers a wide range of quality plumbing supplies at competitive rates. We have everything you need to complete your residential or commercial plumbing project, from sump pumps"
    },
    {
      "name": "Plumbing Valves",
      "url": "https://www.myshop.com/plumbing-valves",
      "shortDesc": "Complete Plumbing Source stocks a wide variety of plumbing valves and check valves in a variety of sizes and materials. If you don’t see the valve you require, please contact our plumbing experts. W"
    }
  ]
}


Query Parameters

Parameter Name Description Default Values Supported Values
ticket* This is your Klevu JS API Key. - -
term* The actual term or a phrase searched by the shopper. - -
sv* 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 If true, the autosuggestions matching the submitted query terms are returned. false false, true
typeOfSuggestions Used for specifying the kind of non-product suggestions (e.g. cms, category etc.) needed to be fetched. Use ":" as a separator. - cms, category
noOfResults 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. 12 -
noOfResultsAC Number of autocomplete suggestions to return. 5 -
enablePartialSearch If true, the partial search is enabled. For example, searching for let may fetch both letter as well as tablet. false false, true
sortOrder 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.
rel rel,lth,htl
showOutOfStockProducts true to include out of stock products in the search result set, false otherwise. false false, true
priceFieldSuffix 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 always set this parameter to search to include products with the visibility of search to be included in the result set. search search, catalog
resultForZero 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. 0 0, 1
recentCategory 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 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. 5 -
optionalFilters 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 Type of response to be returned. xml xml, json

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.

Prerequisites:

You will need your JS API Key and Cloud Search URL. Please refer to the Prerequisites section for more information.

URL

POST https://<cloudSearchURL>/cloud-search/n-search/idsearch

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <meta>
    <totalResultsFound>998</totalResultsFound>
    <!-- use the following value with the lsqt parameter -->
    <typeOfQuery>WILDCARD_AND</typeOfQuery>
    <paginationStartFrom>0</paginationStartFrom>
    <noOfResults>2</noOfResults>
  </meta>
  <result>
    <itemGroupId/>
    <id>69</id>
  </result>
  <result>
    <itemGroupId/>
    <id>40</id>
  </result>
  <!-- filters as a result of enableFilters=true -->
  <filters>
    <!-- number of values restricted to 3 when maxNoOfValuesInAFilter=3.
         Use the value of the value attribute with apply Filters -->
    <filter type="other" label="CATEGORY" key="category">
      <option name="Categories" value="category:categories" count="96" selected="false"/>
      <option name="Plastic Insert Fittings" value="category:plastic insert fittings" count="43" selected="false"/>
      <option name="Pvc Plastic Insert Fittings" value="category:pvc plastic insert fittings" count="43" selected="false"/>
    </filter>
    <filter type="other" label="BRAND" key="brand">
      <option name="Dole" value="brand:dole" count="142" selected="false"/>
      <option name="Complete Plumbing Source" value="brand:complete plumbing source" count="131" selected="false"/>
      <option name="American Granby" value="brand:american granby" count="108" selected="false"/>
    </filter>
  </filters>
  <!-- fetching min and max values when fetchMinMaxPrice=true -->
  <price>
    <min>0.0</min>
    <max>10236.0</max>
  </price>
</data>
{
  "meta": {
    "noOfResults": 3,
    "paginationStartFrom": 0,
    "totalResultsFound": 998,
    "typeOfQuery": "WILDCARD_AND"
  },
  "result": [
    {
      "itemGroupId": "",
      "id": "69"
    },
    {
      "itemGroupId": "",
      "id": "40"
    }
  ],
  "filters": [
    {
      "key": "category",
      "label": "CATEGORY",
      "type": "other",
      "options": [
        {
          "count": 96,
          "isSelected": "false",
          "name": "Categories",
          "value": "category:categories"
        },
        {
          "count": 43,
          "isSelected": "false",
          "name": "Plastic Insert Fittings",
          "value": "category:plastic insert fittings"
        },
        {
          "count": 43,
          "isSelected": "false",
          "name": "Pvc Plastic Insert Fittings",
          "value": "category:pvc plastic insert fittings"
        }
      ]
    },
    {
      "key": "brand",
      "label": "BRAND",
      "type": "other",
      "options": [
        {
          "count": 142,
          "isSelected": "false",
          "name": "Dole",
          "value": "brand:dole"
        },
        {
          "count": 131,
          "isSelected": "false",
          "name": "Complete Plumbing Source",
          "value": "brand:complete plumbing source"
        },
        {
          "count": 108,
          "isSelected": "false",
          "name": "American Granby",
          "value": "brand:american granby"
        }
      ]
    }
  ],
  "price": {
    "min": "0.0",
    "max": "10236.0"
  }
}


Query Parameters

Parameter Name Description Default Values Supported Values
ticket* This is your Klevu JS API Key. - -
term* The actual term or a phrase searched by the shopper. - -
sv* 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 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. 0 -
noOfResults Indicates the number of records to be fetched. If for example, paginationStartsFrom is set to 0, it will obtain results from 0. 12 -
enablePartialSearch If true, the partial search is enabled. For example, searching for let may fetch letter as well as tablet. false false, true
category 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
KLEVU_PRODUCT -
enableFilters If set to true, filters relevant to the search results are retrieved and included in the response. false false, true
enableMultiSelectFilters 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.
false false, true
applyFilters 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 Number of values to return for each filter. - -
sortOrder 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.
rel rel, lth, htl
showOutOfStockProducts true to include out of stock products in the search result set, false otherwise. false false, true
fetchMinMaxPrice 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. false false, true
priceFieldSuffix 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 always set this parameter to search to include products with the visibility of search to be included in the result set. search search, catalog
resultForZero 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. 0 0, 1
recentCategory 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 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. 5 -
optionalFilters 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 Type of response to be returned. xml xml, json
lsqt 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. - WILDCARD_AND, FUZZY_AND, OR, FUZZY_OR
fl 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. - id,itemGroupId,url,name, price,sale_price,sku, shortDesc,currency, inStock, etc.

Category Navigation

Using Klevu’s category navigation API, you can now retrieve products for your individual categories, where the order of products is decided by Klevu’s trend-driven intelligent algorithms. If you have setup merchandising rules in the Klevu Merchant Center, all your settings are respected and the order of products decided accordingly. The continuous learning in the Klevu’s backend ensures regular updates on individual category pages reflecting the changing trends of your website.

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <meta>
    <totalResultsFound>998</totalResultsFound>
    <!-- use the following value with the lsqt parameter -->
    <typeOfQuery>WILDCARD_AND</typeOfQuery>
    <paginationStartFrom>0</paginationStartFrom>
    <noOfResults>100</noOfResults>
  </meta>
  <result>
    <itemGroupId/>
    <klevu_product_boosting>1.0</klevu_product_boosting>
    <image>https://www.myshop.com/media/catalog/product/r/o/royerwatertight.jpg</image>
    <shortDesc/>
    <sku>412WT</sku>
    <url>https://www.myshop.com/royer-4-1-2wt-aluminum-watertight-well-cap-for-4-1-2-o-d-well-casings</url>
    <storeBaseCurrency>USD</storeBaseCurrency>
    <currency>$</currency>
    <id>69</id>
    <groupPrices/>
    <category>royer aluminum watertight well caps</category>
    <price>42</price>
    <name>Royer 4-1/2WT Aluminum Watertight Well Cap for 4-1/2" O.D. Well Casings</name>
    <brand>Royer</brand>
    <salePrice>42</salePrice>
    <totalVariants>0</totalVariants>
    <rating>4.0</rating>
    <inStock>yes</inStock>
    <oldPrice>42</oldPrice>
  </result>
  <result>
    <itemGroupId/>
    <klevu_product_boosting>1.0</klevu_product_boosting>
    <image>https://www.myshop.com/media/klevu_images/r/o/royerroundwellcap_1_11.jpg</image>
    <shortDesc/>
    <sku>5WC</sku>
    <url>https://www.myshop.com/royer-5wc-aluminum-round-well-cap-for-5-o-d-well-casings</url>
    <storeBaseCurrency>USD</storeBaseCurrency>
    <currency>$</currency>
    <id>40</id>
    <groupPrices/>
    <category>royer aluminum round well caps</category>
    <price>16.5</price>
    <name>Royer 5WC Aluminum Round Well Cap for 5" O.D. Well Casings</name>
    <brand>Royer</brand>
    <salePrice>16.5</salePrice>
    <totalVariants>0</totalVariants>
    <rating>2.0</rating>
    <inStock>yes</inStock>
    <oldPrice>16.5</oldPrice>
  </result>
  <!-- filters as a result of enableFilters=true -->
  <filters>
    <!-- number of values restricted to 3 when maxNoOfValuesInAFilter=3.
         Use the value of the value attribute with apply Filters -->
    <filter type="other" label="CATEGORY" key="category">
      <option name="Categories" value="category:categories" count="96" selected="false"/>
      <option name="Plastic Insert Fittings" value="category:plastic insert fittings" count="43" selected="false"/>
      <option name="Pvc Plastic Insert Fittings" value="category:pvc plastic insert fittings" count="43" selected="false"/>
    </filter>
    <filter type="other" label="BRAND" key="brand">
      <option name="Dole" value="brand:dole" count="142" selected="false"/>
      <option name="Complete Plumbing Source" value="brand:complete plumbing source" count="131" selected="false"/>
      <option name="American Granby" value="brand:american granby" count="108" selected="false"/>
    </filter>
  </filters>
  <!-- fetching min and max values when fetchMinMaxPrice=true -->
  <price>
    <min>0.0</min>
    <max>10236.0</max>
  </price>
</data>
{
  "meta": {
    "noOfResults": 3,
    "paginationStartFrom": 0,
    "totalResultsFound": 998,
    "typeOfQuery": "WILDCARD_AND"
  },
  "result": [
    {
      "itemGroupId": "",
      "klevu_product_boosting": "1.0",
      "image": "https://www.myshop.com/media/catalog/product/r/o/royerwatertight.jpg",
      "shortDesc": "",
      "sku": "412WT",
      "url": "https://www.myshop.com/royer-4-1-2wt-aluminum-watertight-well-cap-for-4-1-2-o-d-well-casings",
      "storeBaseCurrency": "USD",
      "currency": "$",
      "id": "69",
      "groupPrices": "",
      "category": "royer aluminum watertight well caps",
      "price": "42",
      "name": "Royer 4-1/2WT Aluminum Watertight Well Cap for 4-1/2\" O.D. Well Casings",
      "brand": "Royer",
      "salePrice": "42",
      "totalVariants": "0",
      "rating": "4.0",
      "inStock": "yes",
      "oldPrice": "42"
    },
    {
      "itemGroupId": "",
      "klevu_product_boosting": "1.0",
      "image": "https://www.myshop.com/media/klevu_images/r/o/royerroundwellcap_1_11.jpg",
      "shortDesc": "",
      "sku": "5WC",
      "url": "https://www.myshop.com/royer-5wc-aluminum-round-well-cap-for-5-o-d-well-casings",
      "storeBaseCurrency": "USD",
      "currency": "$",
      "id": "40",
      "groupPrices": "",
      "category": "royer aluminum round well caps",
      "price": "16.5",
      "name": "Royer 5WC Aluminum Round Well Cap for 5\" O.D. Well Casings",
      "brand": "Royer",
      "salePrice": "16.5",
      "totalVariants": "0",
      "rating": "2.0",
      "inStock": "yes",
      "oldPrice": "16.5"
    }
  ],
  "filters": [
    {
      "key": "category",
      "label": "CATEGORY",
      "type": "other",
      "options": [
        {
          "count": 96,
          "isSelected": "false",
          "name": "Categories",
          "value": "category:categories"
        },
        {
          "count": 43,
          "isSelected": "false",
          "name": "Plastic Insert Fittings",
          "value": "category:plastic insert fittings"
        },
        {
          "count": 43,
          "isSelected": "false",
          "name": "Pvc Plastic Insert Fittings",
          "value": "category:pvc plastic insert fittings"
        }
      ]
    },
    {
      "key": "brand",
      "label": "BRAND",
      "type": "other",
      "options": [
        {
          "count": 142,
          "isSelected": "false",
          "name": "Dole",
          "value": "brand:dole"
        },
        {
          "count": 131,
          "isSelected": "false",
          "name": "Complete Plumbing Source",
          "value": "brand:complete plumbing source"
        },
        {
          "count": 108,
          "isSelected": "false",
          "name": "American Granby",
          "value": "brand:american granby"
        }
      ]
    }
  ],
  "price": {
    "min": "0.0",
    "max": "10236.0"
  }
}


Prerequisites:

You will need your JS API Key and Category Navigation URL. Please refer to the Prerequisites section for more information.

URL

POST https://<categoryNavigationURL>/cloud-search/n-search/search


Query Parameters

Parameter Name Description Default Values Supported Values
ticket* This is your Klevu JS API Key. - -
term* This should always be set to " * " . - -
isCategoryNavigationRequest* This should always be set to true. false true, false
category* Hierarchy of the category for which the query is being issued.

e.g. Gifts;Gifts For;Gifts for Him
Use ";" as a separator between a parent and its child category.

It is important that the complete hierarchy of a category is supplied. This is to make sure the results from the correct heirarchy are retrieved.
- -
sv* 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 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. 0 -
noOfResults Indicates the number of records to be fetched. If for example, paginationStartsFrom is set to 0, it will obtain results from 0. 12 -
enableFilters If set to true, filters relevant to the search results are retrieved and included in the response. false false, true
enableMultiSelectFilters 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.
false false, true
applyFilters Instructs Klevu which filters to apply when retrieving products. In case of applying multiple filters, please use the double semicolon (;;) as the delimiter.

e.g. color:green;;color:white;;brand:nike

Here, values provided should be the strings taken from the value attribute of the “option” element under the filters.
- -
maxNoOfValuesInAFilter Number of values to return for each filter. - -
sortOrder 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.
rel rel, lth, htl
showOutOfStockProducts true to include out of stock products in the result set, false otherwise. false false, true
fetchMinMaxPrice If set to true, it returns the minimum and maximum prices found for the obtained 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. false false, true
priceFieldSuffix 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 always set this parameter to catalog to include products with the visibility set to catalog. search search, catalog
optionalFilters 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 Type of response to be returned. xml xml, json
lsqt When you receive a response for a search/catnav 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. - WILDCARD_AND, FUZZY_AND, OR, FUZZY_OR
fl 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. - id,itemGroupId,url,name, price,sale_price,sku, shortDesc,currency, inStock, etc.

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.