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 record (e.g. a product, category, cms page etc.) sent to Klevu is maintained in a dedicated index for the respective store. The Indexing API is used for adding, updating or deleting records from this index.

The Indexing API requires that you first authenticate yourself to the Klevu servers. As a result of this authentication you are provided a Session ID, which you can use for subsequent requests to the Klevu servers.

What is a Record?

Record Example

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <sessionId>Your-Session-ID</sessionId>
    <records>
        <record>
            <pairs>
                <!-- IDs -->
                <pair>
                    <key>id</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>itemGroupId</key>
                    <value>123</value>
                </pair>

                <!-- Product Information -->
                <pair>
                    <key>sku</key>
                    <value>SKU-123-ABC</value>
                </pair>
                <pair>
                    <key>name</key>
                    <value>My Product Name</value>
                </pair>
                <pair>
                    <key>inStock</key>
                    <value>yes</value>
                </pair>
                <pair>
                    <key>url</key>
                    <value>https://your-website.com/products/123.html</value>
                </pair>
                <pair>
                    <key>image</key>
                    <value>https://your-website.com/images/products/123-abc.jpg</value>
                </pair>
                <pair>
                    <key>imageHover</key>
                    <value>https://your-website.com/images/products/hover/123-abc.jpg</value>
                </pair>

                <!-- Product Descriptions -->
                <pair>
                    <key>shortDesc</key>
                    <value>My Short Description</value>
                </pair>
                <pair>
                    <key>desc</key>
                    <value>My Longer Description</value>
                </pair>

                <!-- Prices -->
                <pair>
                    <key>currency</key>
                    <value>GBP</value>
                </pair>
                <pair>
                    <key>price</key>
                    <value>150.00</value>
                </pair>
                <pair>
                    <key>salePrice</key>
                    <value>100.00</value>
                </pair>
                <pair>
                    <key>startPrice</key>
                    <value>50.00</value>
                </pair>
                <pair>
                    <key>toPrice</key>
                    <value>200.00</value>
                </pair>
                <pair>
                    <key>otherPrices</key>
                    <value>price_GBP:150.00;price_USD:200.00;salePrice_GBP:100.00;salePrice_USD:150.00;startPrice_GBP:50.00;startPrice_USD:100.00;toPrice_GBP:200.00;toPrice_USD:300.00;price_GBP-test_group_1:100.00;price_USD-test_group_1:150.00;salePrice_GBP-test_group_1:80.00;salePrice_USD-test_group_1:100.00;startPrice_GBP-test_group_1:30.00;startPrice_USD-test_group_1:50.00;toPrice_GBP-test_group_1:180.00;toPrice_USD-test_group_1:200.00;price_GBP-test_group_2:90.00;price_USD-test_group_2:140.00;salePrice_GBP-test_group_2:70.00;salePrice_USD-test_group_2:90.00;startPrice_GBP-test_group_2:20.00;startPrice_USD-test_group_2:40.00;toPrice_GBP-test_group_2:170.00;toPrice_USD-test_group_2:190.00</value>
                </pair>
                <pair>
                    <key>groupPrices</key>
                    <value>test_group_1:Test Group 1:80.00;test_group_2:Test Group 2:70.00</value>
                </pair>

                <!-- Categorisation -->
                <pair>
                    <key>category</key>
                    <value>Sub Category A-2;Sub Category B-2</value>
                </pair>
                <pair>
                    <key>listCategory</key>
                    <value>KLEVU_PRODUCT;;Category A;Sub Category A-1;Sub Category A-2;;Category B;Sub Category B-1;Sub Category B-2;;test_group_1;;test_group_2</value>
                </pair>

                <!-- Attributes -->
                <pair>
                    <key>other</key>
                    <value>color:Colour:red;occasion:Occasion:Christmas,Evening Wear</value>
                </pair>
                <pair>
                    <key>otherAttributeToIndex</key>
                    <value>brand:Brand Name:Nike,Adidas;gtin:GTIN:123456789</value>
                </pair>
                <pair>
                    <key>rating</key>
                    <value>3.5</value>
                </pair>
                <pair>
                    <key>tags</key>
                    <value>keyword 1,keyword 2</value>
                </pair>

                <!-- Swatches -->
                <pair>
                    <key>variantId1</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>variantColor1</key>
                    <value>Red</value>
                </pair>
                <pair>
                    <key>variantSwatchImage1</key>
                    <value>#ff0000</value>
                </pair>
                <pair>
                    <key>variantImage1</key>
                    <value>https://your-website.com/images/products/123-abc.jpg</value>
                </pair>

                <pair>
                    <key>variantId2</key>
                    <value>123-BCD</value>
                </pair>
                <pair>
                    <key>variantColor2</key>
                    <value>White</value>
                </pair>
                <pair>
                    <key>variantSwatchImage2</key>
                    <value>https://your-website.com/images/swatches/white.jpg</value>
                </pair>
                <pair>
                    <key>variantImage2</key>
                    <value>https://your-website.com/images/products/123-def.jpg</value>
                </pair>

                <!-- Miscellaneous -->
                <pair>
                    <key>boostingAttribute</key>
                    <value>5</value>
                </pair>
                <pair>
                    <key>additionalDataToReturn</key>
                    <value>{"some_arbitrary": "data to return"}</value>
                </pair>
            </pairs>
        </record>
    </records>
</request>
"JSON not applicable, please use XML."

With Klevu a record can be a Product, a Category page or a CMS page that you want to index and make available in search results. It can also be a custom record type such as a Store or Recipe or something like that.

When you submit a record for addition or update, you must submit the record with all of its details provided. A list of mandatory and optional fields is provided below. When you submit a record for deletion, however, you only need to submit its unique ID.

You can see a complete XML example of a record to the right.

Field Description
id REQUIRED. This is the unique identifier of a record. Klevu will use this ID for indexing, analytics and merchandising.
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, specify a common value in this itemGroupId element.
name REQUIRED. This is the name or title of your record.
sku REQUIRED. This is the unique SKU of the record, or Stock Keeping Unit.
url REQUIRED. This is the URL where shoppers will be taken to when the record is clicked in the Klevu Search results. This must be a fully qualified URL, beginning http:// or https://. Note that you may receive a 400: Bad Request if you submit a base URL that has not been configured in your Klevu Merchant Centre.
currency REQUIRED. The currency code of the prices specified below, e.g. EUR, USD, etc.
price REQUIRED. The original price of your product, before any discounts. This can be used as 'was price' when used in conjunction with salePrice. In the 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 the separate currency element.
salePrice REQUIRED. This is the final price of your product, after all applicable discounts. This can be used as 'now price' when used in conjunction with price. The format of this field is the same as price.
startPrice OPTIONAL. If your record has multiple variants, this field can be used to show the lowest price across all variants, for displaying "as low as £100".
toPrice OPTIONAL. If your record has multiple variants, this field can be used to show the highest price across all variants, for use in conjunction with startPrice to display "from £100 to £200".
groupPrices OPTIONAL. This field is mostly commonly used in Magento integrations for the customer group prices to be rendered on the frontend. The format of this field is: 1:General:100.00. There are three colon : separated values in each price grouping. The first value represents the ID of the group, the second is the label, and the third is the price for that group.

Please see the XML to the right for a full example.
otherPrices OPTIONAL. This is an improvement over groupPrices, in that the values specified here can also be used in conjunction with priceFieldSuffix to retrieve dynamic prices based on currencies and customer groups.

The format of this field is: price_USD-group_1:100.00. There are two colon : separated values in each price grouping. The first value represents the ID of the group and the second is the price for that group.

The ID is made up of the following format: price type_currency code-group_id, with the group ID being optional if you are not using currencies.

Please see the XML to the right for a full example of the possible variations.
inStock OPTIONAL. This attribute indicates if your record is in stock or not. Provide a value of yes if in stock, and no otherwise.
category REQUIRED. This attribute indicates the most specific category of the record being submitted. For example, if your product belongs to the following categories:
  • Mobiles & Accessories
    • Tablets
  • Promotions
    • New In
It is only Tablets and New In that should be specified here, separated by a semicolon ;, for example: Tablets;New In.
listCategory REQUIRED. This field contains up to three pieces of data, depending on your use case. Each section of the field must be separated by a double semicolon ;;.

Record Type: The first part is always required, a record type. You MUST provide one of the following values, whichever is most appropriate for your record:
  • KLEVU_PRODUCT for Product records
  • KLEVU_CATEGORY for Category records
  • KLEVU_CMS for CMS Pages or Blog Articles
  • YOUR_TYPE for your own custom entity, eg: ACME_RECIPE
Category Hierarchy: The second part is made up of the entire hierarchies of applicable categories the record belongs to, with each category within the hierarchy separated by a single semicolon ;. Using the same example as in category above, the following would be submitted for this section: Mobiles & Accessories;Tablets;;Promotions;New In.

Group ID: The third part is optional, and only needed if you plan to use the visibilityGroupID feature in API requests to control which customer groups can see which records. This is made up of a double semicolon ;; separated list of all applicable customer groups for this record, eg: customer_group_1;;wholesale_group.

See the XML to the right for a full example.
image OPTIONAL. This is the URL of an associated image for your record. This must be a fully qualified URL, beginning http:// or https://.
imageHover OPTIONAL. This field can be used to specify an additional image for your record to be used on mouse hover. The format is the same as for image.
shortDesc OPTIONAL. The short description for your record. This field can be used to display a smaller description of a record in the search results.
desc OPTIONAL. The long description for your record. This can also be configured to be considered in search results, in which case both this value and shortDesc will become searchable.
other OPTIONAL. Use this field to specify filterable attributes for your product, to be used as facets. The value is made up of three values separated by colon :, then each attribute is separated by a semicolon ;:
  • Attribute Code
  • Caption or Label
  • Value(s)
For example: occassion:Occassion:Christmas,Evening Wear.

The attribute code here is a unique identifier of your attribute. The attribute caption is used as the heading of your filter when displaying search results. If the attribute code, caption or values contain a comma, colon or semi-colon, they must be replaced with a space.
otherAttributeToIndex OPTIONAL. The format of this element is the same as the format of the other element above. The difference between the two is that other is used for displaying facets whereas otherAttributeToIndex is used for indexing and searching only. Populate this field with any attributes you want to be searchable, but not used as a facet.
boostingAttribute OPTIONAL. The score provided here is multiplied with the relevancy score to boost records at search time. Any decimal value between the range of 0.1 to 999 can be provided here. Provide a value greater than 1 to boost a record up the rankings. To de-boost or demote a record, provide a number that is greater than 0 and less than 1.
rating OPTIONAL. A score between 0 and 5. This can be used for displaying a star rating with each record, and can also be used to apply a sort order of the highest rated items.
tags OPTIONAL. Use this field to specify any important keywords applicable for your records.
swatches OPTIONAL. If your record has many variants, you can specify swatch data to be used across them. You must specify the same swatch data for all variants, and the format is made up of four elements, which is repeated with a suffix of 1, 2, 3, etc. for each variant:
  • variantId1: The Klevu ID of the variant, eg. 123-ABC.
  • variantColor1: The colour of the variant, eg. Red.
  • variantSwatchImage1: The hex colour or URL of the image to be displayed as the swatch itself.
  • variantImage1: The product image which this swatch represents.
See the XML to the right for a full example.
additionalDataToReturn OPTIONAL. If you have some data that you would like to be returned with the search response, populate that data in this field. The structure can be anything you like, but we recommend JSON. If you do not see this in your response data, please contact Klevu Support.

Requesting a Session ID

Response (Success)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <sessionId>Some-Session-ID</sessionId>
</message>
"JSON not applicable, please use XML."

Response (Failure)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>ERROR</status>
  <msg>error message</msg>
</message>
"JSON not applicable, please use XML."

Use this call to authenticate yourself to the Klevu Indexing servers. In the response you will be provided a Session ID which you should use for all subsequent requests to the Klevu servers.

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

Request Format

POST https://<productSynchronizationURL>/rest/service/startSession

HTTP Header Value
Authorization Your Klevu REST API Key, eg. abcdefoobar==

Adding New Records

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>Your-Session-ID</sessionId>
  <records>
    <record>
      <pairs>
        <pair>
          <key>name</key>
          <value>Product A</value>
        </pair>
        <pair>
           ... etc ...
        </pair>
      </pairs>
    </record>
    <record>
      <pairs>
        <pair>
          <key>name</key>
          <value>Product B</value>
        </pair>
      </pairs>
    </record>
    ... etc ...
  </records>
</request>
"JSON not applicable, please use XML."

Response (Success)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg>3 records are marked for ADDITION</msg>
</message>
"JSON not applicable, please use XML."

Response (Failure)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>ERROR</status>
  <msg>error message</msg>
</message>
"JSON not applicable, please use XML."

You must provide each record in full, including all 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. You will also need a Session ID, please see the section above on Requesting a Session ID.

Request Format

POST https://<productSynchronizationURL>/rest/service/addRecords

Tip: You can also submit new records to the updateRecords endpoint URL, which will still ADD your records.

The body of the request is a set of records, as defined in What is a Record.

Updating Existing Records

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>Your-Session-ID</sessionId>
  <records>
    <record>
      <pairs>
        <pair>
          <key>name</key>
          <value>Product A</value>
        </pair>
        <pair>
           ... etc ...
        </pair>
      </pairs>
    </record>
    <record>
      <pairs>
        <pair>
          <key>name</key>
          <value>Product B</value>
        </pair>
      </pairs>
    </record>
    ... etc ...
  </records>
</request>
"JSON not applicable, please use XML."

Response (Success)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg>5 records are marked for UPDATING</msg>
</message>
"JSON not applicable, please use XML."

Response (Failure)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>ERROR</status>
  <msg>error message</msg>
</message>
"JSON not applicable, please use XML."

You must provide each record in full, including all 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. You will also need a Session ID, please see the section above on Requesting a Session ID.

Request Format

POST https://<productSynchronizationURL>/rest/service/updateRecords

Tip: You can also submit existing records to the addRecords endpoint URL, which will still UPDATE your records.

The body of the request is a set of records, as defined in What is a Record.

Deleting Existing Records

Request

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <sessionId>Your-Session-ID</sessionId>
  <records>
    <record>
      <pairs>
        <pair>
          <key>id</key>
          <value>12345</value>
        </pair>
      </pairs>
    </record>
    <record>
      <pairs>
        <pair>
          <key>id</key>
          <value>54321</value>
        </pair>
      </pairs>
    </record>
    ... etc ...
  </records>
</request>
"JSON not applicable, please use XML."

Response (Success)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>SUCCESS</status>
  <msg>2 records are marked for DELETION</msg>
</message>
"JSON not applicable, please use XML."

Response (Failure)

<?xml version="1.0" encoding="UTF-8" ?>
<message>
  <status>ERROR</status>
  <msg>error message</msg>
</message>
"JSON not applicable, please use XML."

You must provide the unique IDs of the records you wish to delete.

Prerequisites:

You will need your REST API Key and Product Synchronization URL. Please refer to the Prerequisites section for more information. You will also need a Session ID, please see the section above on Requesting a Session ID.

Request Format

POST https://<productSynchronizationURL>/rest/service/deleteRecords

Only the IDs of the records you wish to delete are required.

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.

Search As You Type

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"
    }
  ]
}

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.

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

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

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/>
    <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"
  }
}

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.

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

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.


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"
  }
}

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

Query Parameters

The Query parameters for ID Search are the same as those for Record Search, above.

Category Navigation

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"
  }
}

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.

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 trends on your website, to understand your customers' behaviour and to improve the overall search and recommendation experience of your customers.

We are always improving the way our customers can interact with Klevu, including how analytics data is submitted. Please see below for the correct resources.

Reporting Search Activities

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

Searched Terms

URL

GET https://stats.ksearchnet.com/analytics/n-search/search

Request

https://stats.ksearchnet.com/analytics/n-search/search
  ?apiKey=klevu-1234567890
  &term=red%20shoes
  &klevu_totalResults=35
  &klevu_typeOfQuery=WILDCARD_AND

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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

GET https://stats.ksearchnet.com/analytics/productTracking

Request

https://stats.ksearchnet.com/analytics/productTracking
  ?klevu_apiKey=klevu-1234567890
  &klevu_keywords=red%20shoe
  &klevu_type=clicked
  &klevu_productId=54321-12345
  &klevu_productGroupId=54321
  &klevu_productVariantId=12345
  &klevu_productName=Smart%20Trainers
  &klevu_productUrl=https%3A%2F%2Fyour.website.com%2Fproduct-url

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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 Klevu ID of the clicked product. eg. 54321-12345.
klevu_productGroupId This is the parent ID of the clicked product. eg. 54321. For compound products with a parent and multiple child/variant products, this is the common ID which ties the products together. For simple products, please specify the same as klevu_productId.
klevu_productVariantId This is the child/variant ID of the clicked product. eg. 12345. For compound products with a parent and multiple child/variant products, this is the ID of the specific variant. For simple products, please specify the same as klevu_productId.
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

GET https://stats.ksearchnet.com/analytics/productTracking

Request

https://stats.ksearchnet.com/analytics/productTracking
  ?klevu_apiKey=klevu-1234567890
  &klevu_type=checkout
  &klevu_productId=54321-12345
  &klevu_productGroupId=54321
  &klevu_productVariantId=12345
  &klevu_unit=2
  &klevu_salePrice=123.45
  &klevu_currency=GBP
"JSON not applicable, please use XML."

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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 Klevu ID of the purchased product. eg. 54321-12345. Please note that the value of the klevu_productId must be the same in both the click and checkout calls.
klevu_productGroupId This is the parent ID of the purchased product. eg. 54321. For compound products with a parent and multiple child/variant products, this is the common ID which ties the products together. For simple products, please specify the same as klevu_productId.
klevu_productVariantId This is the child/variant ID of the purchased product. eg. 12345. For compound products with a parent and multiple child/variant products, this is the ID of the specific variant. For simple products, please specify the same as klevu_productId.
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

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

Request

https://stats.ksearchnet.com/analytics/categoryProductViewTracking
  ?klevu_apiKey=klevu-1234567890
  &klevu_categoryName=Sneakers
  &klevu_categoryPath=Mens%3BShoes%20and%20Trainers%3BSneakers
  &klevu_productIds=54321-12345%2C345
  &klevu_pageStartsFrom=0

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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

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

Request

https://stats.ksearchnet.com/analytics/categoryProductClickTracking
  ?klevu_apiKey=klevu-1234567890
  &klevu_categoryName=Sneakers
  &klevu_categoryPath=Mens%3BShoes%20and%20Trainers%3BSneakers
  &klevu_productId=54321-12345
  &klevu_productGroupId=54321
  &klevu_productVariantId=12345
  &klevu_productName=Smart%20Trainers
  &klevu_productUrl=https%3A%2F%2Fyour.website.com%2Fproduct-url
  &klevu_productSku=ABC-123
  &klevu_salePrice=123.45
  &klevu_productRatings=3
  &klevu_productPosition=7

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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* This is the Klevu ID of the clicked product. eg. 54321-12345.
klevu_productGroupId* This is the parent ID of the clicked product. eg. 54321. For compound products with a parent and multiple child/variant products, this is the common ID which ties the products together. For simple products, please specify the same as klevu_productId.
klevu_productVariantId* This is the child/variant ID of the clicked product. eg. 12345. For compound products with a parent and multiple child/variant products, this is the ID of the specific variant. For simple products, please specify the same as klevu_productId.
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

GET https://stats.ksearchnet.com/analytics/productTracking

Request

https://stats.ksearchnet.com/analytics/productTracking
  ?klevu_apiKey=klevu-1234567890
  &klevu_type=checkout
  &klevu_productId=54321-12345
  &klevu_productGroupId=54321
  &klevu_productVariantId=12345
  &klevu_unit=2
  &klevu_salePrice=123.45
  &klevu_currency=GBP

Response

<?xml version="1.0" encoding="UTF-8" ?>
<data>
  <response>SUCCESS</response>
</data>
"JSON not applicable, please use XML."

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 Klevu ID of the purchased product. eg. 54321-12345. Please note that the value of klevu_productId must be the same in both the click and checkout calls.
klevu_productGroupId* This is the parent ID of the purchased product. eg. 54321. For compound products with a parent and multiple child/variant products, this is the common ID which ties the products together. For simple products, please specify the same as klevu_productId.
klevu_productVariantId* This is the child/variant ID of the purchased product. eg. 12345. For compound products with a parent and multiple child/variant products, this is the ID of the specific variant. For simple products, please specify the same as klevu_productId.
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.