Overview

8min

Klevu APIv2 is the latest version of our API for integrating Smart search into your applications for lightning-fast search as , record search results. 
JS API Key & Endpoint
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.
JS API Key (readonly key) for querying indexed data e.g. klevu-156925593843210765
APIv2 Cloud Search URL for end-point e.g. eucs15v2.ksearchnet.com
If you have multiple stores with Klevu, please note it is likely that each of them will have totally different JS API Keys and subdomains assigned.
Search URL
When retrieving data for Search, Category Merchandising or Recommendations, Klevu APIv2 utilizes a single endpoint:
https://{{APIv2_Cloud_Search_URL}}/cs/v2/search
Please replace APIv2_Cloud_Search_URL with your own value, which you can find in the Prerequisites above. For example, if your URL is 'eucs15v2.ksearchnet.com' then the correct value is:
https://eucs15v2.ksearchnet.com/cs/v2/search
The inclusion of 'v2' is important. Without it you will experience degraded performance since your API requests will not be utilizing our Content Delivery Network (CDN). 
GET vs POST
The APIv2 Endpoint URL accepts requests in JSON format and also responds with JSON. Requests can be made using either GET or POST, however we recommend POST.
Because our requests are routed through cloudflare CDN, which has a limit on the size of the payload, we are accepting request payloads up to 8KB.
Request Object
Every request to APIv2 comprises a structured JSON payload: a request object. The request object is a top level object that comprises a mandatory context and one or both of the suggestions and recordQueries objects. Each HTTP request can contain multiple search queries.
The context object is for specifying your JS API Key.
The suggestions object is for requesting suggestions or typeahead results.
The recordQueries object is for requesting entities such as products or CMS pages.
Please note that despite apiKeys being an array, currently we only support a single API Key per request.
A skeleton of the request object looks like this:
JSON Request
{
  "request": {
    "context": {
      "apiKeys": ["..."]
    },
    "suggestions": [
      {
        ... suggestions query 1 ...
      },
      {
        ... suggestions query 2 ...
      }
    ],
    "recordQueries":[
      {
        ... record query 1 ...
      },
      {
        ... record query 2 ...
      }
    ]
  }
}

{
  "request": {
    "context": {
      "apiKeys": ["..."]
    },
    "suggestions": [
      {
        ... suggestions query 1 ...
      },
      {
        ... suggestions query 2 ...
      }
    ],
    "recordQueries":[
      {
        ... record query 1 ...
      },
      {
        ... record query 2 ...
      }
    ]
  }
}
﻿
Response Object
When a query is fired, depending on the query objects included in the request, i.e. suggestions and/or record queries, the Klevu Search engine returns a response object containing data for each of these query types, suggestionResults and queryResults.
The meta object contains information on the query related parameters, for example the time taken, the total number of results found, etc.
The skeleton of the response object looks like this:
JSON Response
{
  "meta": {
    ...
  },
  "suggestionResults": [
    {
      ... result of suggestions query 1 ...
    },
    {
      ... result of suggestions query 2 ...
    }
  ],
  "queryResults": [
    {
      ... result of record query 1 ...
    },
    {
      ... result of record query 2 ...
    }
  ],
}

{
  "meta": {
    ...
  },
  "suggestionResults": [
    {
      ... result of suggestions query 1 ...
    },
    {
      ... result of suggestions query 2 ...
    }
  ],
  "queryResults": [
    {
      ... result of record query 1 ...
    },
    {
      ... result of record query 2 ...
    }
  ],
}
﻿
POST
Request
Header Parameters
Content-type
required
String
application/json
JSON Request
Curl
Node.js
JS
Python
Ruby
{
  "context": {
    "apiKeys": [
      "klevu-156925593843210765"
    ]
  },
  "suggestions": [
    {
      "id": "mySuggestionsQuery1",
      "typeOfQuery": "AUTO_SUGGESTIONS",
      "query": "w",
      "limit": 2
    },
    {
      "id": "mySuggestionsQuery2",
      "typeOfQuery": "AUTO_SUGGESTIONS",
      "query": "whi",
      "limit": 3
    }
  ],
  "recordQueries": [
    {
      "id": "productSearch",
      "settings": {
        "query": {
          "term": "jackets"
        },
        "limit": 5,
        "fields": [
          "id",
          "name"
        ],
        "typeOfRecords": [
          "KLEVU_PRODUCT"
        ]
      }
    },
    {
      "id": "categorySearch",
      "settings": {
        "query": {
          "term": "accessories"
        },
        "limit": 1,
        "fields": [
          "id",
          "name"
        ],
        "typeOfRecords": [
          "KLEVU_CATEGORY"
        ]
      }
    }
  ]
}
{
  "context": {
    "apiKeys": [
      "klevu-156925593843210765"
    ]
  },
  "suggestions": [
    {
      "id": "mySuggestionsQuery1",
      "typeOfQuery": "AUTO_SUGGESTIONS",
      "query": "w",
      "limit": 2
    },
    {
      "id": "mySuggestionsQuery2",
      "typeOfQuery": "AUTO_SUGGESTIONS",
      "query": "whi",
      "limit": 3
    }
  ],
  "recordQueries": [
    {
      "id": "productSearch",
      "settings": {
        "query": {
          "term": "jackets"
        },
        "limit": 5,
        "fields": [
          "id",
          "name"
        ],
        "typeOfRecords": [
          "KLEVU_PRODUCT"
        ]
      }
    },
    {
      "id": "categorySearch",
      "settings": {
        "query": {
          "term": "accessories"
        },
        "limit": 1,
        "fields": [
          "id",
          "name"
        ],
        "typeOfRecords": [
          "KLEVU_CATEGORY"
        ]
      }
    }
  ]
}
Responses
200
{
  "meta": {
    "qTime": 17,
    "responseCode": 200
  },
  "suggestionResults": [
    {
      "id": "mySuggestionsQuery1",
      "suggestions": [
        {
          "suggest": "workout"
        },
        {
          "suggest": "wheelset"
        }
      ]
    },
    {
      "id": "mySuggestionsQuery2",
      "suggestions": [
        {
          "suggest": "whiskey"
        },
        {
          "suggest": "tee-xl-white"
        },
        {
          "suggest": "tee-m-white"
        }
      ]
    }
  ],
  "queryResults": [
    {
      "id": "productSearch",
      "meta": {
        "qTime": 8,
        "noOfResults": 5,
        "totalResultsFound": 77,
        "typeOfSearch": "WILDCARD_AND",
        "offset": 0,
        "debuggingInformation": {},
        "notificationCode": 1,
        "searchedTerm": "jackets",
        "apiKey": "klevu-156925593843210765",
        "isPersonalised": false
      },
      "records": [
        {
          "name": "Stellar Solar Jacket",
          "id": "31366456541246"
        },
        {
          "name": "Lando Gym Jacket",
          "id": "31366487441470"
        },
        {
          "name": "Ingrid Running Jacket",
          "id": "31366455590974"
        },
        {
          "name": "Juno Jacket",
          "id": "31366453067838"
        },
        {
          "name": "Josie Yoga Jacket",
          "id": "31366456279102"
        }
      ],
      "filters": []
    },
    {
      "id": "categorySearch",
      "meta": {
        "qTime": 7,
        "noOfResults": 1,
        "totalResultsFound": 1,
        "typeOfSearch": "WILDCARD_AND",
        "offset": 0,
        "debuggingInformation": {},
        "notificationCode": 1,
        "searchedTerm": "accessories",
        "apiKey": "klevu-156925593843210765",
        "isPersonalised": false
      },
      "records": [
        {
          "name": "Accessories",
          "id": "category_156704342078"
        }
      ],
      "filters": []
    }
  ]
}
{
  "meta": {
    "qTime": 17,
    "responseCode": 200
  },
  "suggestionResults": [
    {
      "id": "mySuggestionsQuery1",
      "suggestions": [
        {
          "suggest": "workout"
        },
        {
          "suggest": "wheelset"
        }
      ]
    },
    {
      "id": "mySuggestionsQuery2",
      "suggestions": [
        {
          "suggest": "whiskey"
        },
        {
          "suggest": "tee-xl-white"
        },
        {
          "suggest": "tee-m-white"
        }
      ]
    }
  ],
  "queryResults": [
    {
      "id": "productSearch",
      "meta": {
        "qTime": 8,
        "noOfResults": 5,
        "totalResultsFound": 77,
        "typeOfSearch": "WILDCARD_AND",
        "offset": 0,
        "debuggingInformation": {},
        "notificationCode": 1,
        "searchedTerm": "jackets",
        "apiKey": "klevu-156925593843210765",
        "isPersonalised": false
      },
      "records": [
        {
          "name": "Stellar Solar Jacket",
          "id": "31366456541246"
        },
        {
          "name": "Lando Gym Jacket",
          "id": "31366487441470"
        },
        {
          "name": "Ingrid Running Jacket",
          "id": "31366455590974"
        },
        {
          "name": "Juno Jacket",
          "id": "31366453067838"
        },
        {
          "name": "Josie Yoga Jacket",
          "id": "31366456279102"
        }
      ],
      "filters": []
    },
    {
      "id": "categorySearch",
      "meta": {
        "qTime": 7,
        "noOfResults": 1,
        "totalResultsFound": 1,
        "typeOfSearch": "WILDCARD_AND",
        "offset": 0,
        "debuggingInformation": {},
        "notificationCode": 1,
        "searchedTerm": "accessories",
        "apiKey": "klevu-156925593843210765",
        "isPersonalised": false
      },
      "records": [
        {
          "name": "Accessories",
          "id": "category_156704342078"
        }
      ],
      "filters": []
    }
  ]
}
﻿
Understanding the response parameters:
Parameters
Description
id
The ID of the record query for which the results are being returned.
meta
The meta object contains information on the query related parameters.

qTime: The time taken by the Klevu Search engine to fetch the response.

noOfResults: The number of results requested to be returned for this query.

totalResultsFound: The total number of results found for this query.

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

typeOfSearch: The query type that was executed by Klevu to retrieve the results.

debuggingInformation: Information that can be useful for debugging the query. For example, the actual query that was fired by the Klevu Search engine, inclusive of any synonyms or de-compounded words taken into consideration.

notificationCode: This may be populated with a code if any actions were taken on the record. Possible values are:
1: Nothing to report.
2: The price of the record is using the base currency.
searchedTerm: The search term submitted for this query.
records
The records matching the query. Each record object is a map of key-value pairs, where the key is the name of a field (e.g. id, name, price) and the value of that field stored in the Klevu index. The following fields are included for each record.
﻿
id: The unique identifier of the record within Klevu.
﻿
itemGroupId: The identifier used to group compound products together, eg. the ID of the parent in the case of a configurable product.
﻿
name: The name of your record, eg. the product name or category title.
﻿
url: The fully qualified URL used to access the record in your store.
﻿
sku: The Stock Keeping Unit of the record.
﻿
inStock: Whether or not your record is in stock, 'yes' or 'no'.
﻿
price: The original price of your product, before any discounts. This can be used as 'was price' when used in conjunction with salePrice.
salePrice: The actual selling price of your product, or 'now' price when used in conjunction with price. Note that when using filters, the sale price is represented by klevu_price.
﻿
startPrice: The salePrice of the lowest variant within all those indexed with the same itemGroupId. This can be used if you would like to show 'as low as' price.
﻿
toPrice: The salePrice of the highest variant within all those indexed with the same itemGroupId. This can be used if you would like to show 'from X to Y' price range.
﻿
groupPrices: This field is not always populated and is mostly used in older integrations. It includes the prices of your record in format groupId:price so you can use your own frontend logic to display prices in realtime. If you are using the B2B group price search parameters described in this documentation, the price and salePrice are automatically calculated so there is no need to use this field in most cases.
﻿
currency: The currency code applicable to the price values being displayed.
﻿
category: A double semicolon ;; separated list of the most specific categories, not including their full path. For example if a record was in 'Mens > Shoes' and 'Mens > Tees', the value would be Shoes;;Tees.
klevu_category: This is mostly for internal purposes, but includes the categorisation of the record within Klevu. For example KLEVU_PRODUCT;;Shop All;;Bath;;;groupid_1 @ku@kuCategory@ku@.
﻿
shortDesc: The short description of your record.
﻿
rating: The rating of your product, between 0 and 5.
﻿
ratingCount: The number of ratings given by customers for your product.
﻿
image: The fully qualified URL to the main image of your record.
﻿
imageHover: The fully qualified URL to the secondary image of your record.
﻿
swatches: If your indexed data includes variants with swatch information, this will be provided here as a nested object with the following elements:
          --id: The Klevu record ID of the variant the swatch represents.
          --color: The label to be displayed for the swatch, eg. Red
          --swatchImage: The hex colour or image URL to be displayed as the swatch pattern, eg. #FF0000
          --image: The image of the product which corresponds to this swatch, eg. a picture of the tshirt in red.
          --numberOfAdditionalVariants: If there are additional variants which have not been included, the number will be included here, so you can display something like "Also available in 4 other colours"

totalVariants: How many additional variants are available for this product. For example when searching for 'small tshirt', if a product has 3 colours available in small then the value here will be 2. If the search was 'tshirt' then the same record would return a value of 8 if there are 3 colours and 3 sizes of each available.
﻿
score: The score the record has achieved, ie. how relevant it is, which is used for sorting by relevance. This value must be either explicitly requested in fields or using Search Preference enableScores.
﻿
klevu_manual_boosting: Any manual score assigned by the merchant. This value must be either explicitly requested in fields or using Search Preference enableScores.
﻿
klevu_bulk_boosting: Any manual score assigned by the manual boosting rules. This value must be either explicitly requested in fields or using Search Preference enableScores.
﻿
klevu_selflearning_boosting: The machine learning score assigned by the Klevu Search engine. This value must be either explicitly requested in fields or using Search Preference enableScores.
brand: The brand of the product, eg. 'Nike'.
﻿
tags: Any tags or keywords Klevu has saved for the record.
﻿
typeOfRecord: The type of record, e.g. KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY, etc.
﻿
other fields: There will also be various other fields returned according to the data you have indexed, which will vary from store to store.
﻿
﻿

Parameters	Description
id	The ID of the record query for which the results are being returned.
meta	The meta object contains information on the query related parameters. qTime: The time taken by the Klevu Search engine to fetch the response. noOfResults: The number of results requested to be returned for this query. totalResultsFound: The total number of results found for this query. offset: The index of the first result returned in this response. typeOfSearch: The query type that was executed by Klevu to retrieve the results. debuggingInformation: Information that can be useful for debugging the query. For example, the actual query that was fired by the Klevu Search engine, inclusive of any synonyms or de-compounded words taken into consideration. notificationCode: This may be populated with a code if any actions were taken on the record. Possible values are: 1: Nothing to report. 2: The price of the record is using the base currency. searchedTerm: The search term submitted for this query.
records	The records matching the query. Each record object is a map of key-value pairs, where the key is the name of a field (e.g. id, name, price) and the value of that field stored in the Klevu index. The following fields are included for each record. id: The unique identifier of the record within Klevu. itemGroupId: The identifier used to group compound products together, eg. the ID of the parent in the case of a configurable product. name: The name of your record, eg. the product name or category title. url: The fully qualified URL used to access the record in your store. sku: The Stock Keeping Unit of the record. inStock: Whether or not your record is in stock, 'yes' or 'no'. price: The original price of your product, before any discounts. This can be used as 'was price' when used in conjunction with salePrice. salePrice: The actual selling price of your product, or 'now' price when used in conjunction with price. Note that when using filters, the sale price is represented by klevu_price. startPrice: The salePrice of the lowest variant within all those indexed with the same itemGroupId. This can be used if you would like to show 'as low as' price. toPrice: The salePrice of the highest variant within all those indexed with the same itemGroupId. This can be used if you would like to show 'from X to Y' price range. groupPrices: This field is not always populated and is mostly used in older integrations. It includes the prices of your record in format groupId:price so you can use your own frontend logic to display prices in realtime. If you are using the B2B group price search parameters described in this documentation, the price and salePrice are automatically calculated so there is no need to use this field in most cases. currency: The currency code applicable to the price values being displayed. category: A double semicolon ;; separated list of the most specific categories, not including their full path. For example if a record was in 'Mens > Shoes' and 'Mens > Tees', the value would be Shoes;;Tees. klevu_category: This is mostly for internal purposes, but includes the categorisation of the record within Klevu. For example KLEVU_PRODUCT;;Shop All;;Bath;;;groupid_1 @ku@kuCategory@ku@. shortDesc: The short description of your record. rating: The rating of your product, between 0 and 5. ratingCount: The number of ratings given by customers for your product. image: The fully qualified URL to the main image of your record. imageHover: The fully qualified URL to the secondary image of your record. swatches: If your indexed data includes variants with swatch information, this will be provided here as a nested object with the following elements: --id: The Klevu record ID of the variant the swatch represents. --color: The label to be displayed for the swatch, eg. Red --swatchImage: The hex colour or image URL to be displayed as the swatch pattern, eg. #FF0000 --image: The image of the product which corresponds to this swatch, eg. a picture of the tshirt in red. --numberOfAdditionalVariants: If there are additional variants which have not been included, the number will be included here, so you can display something like "Also available in 4 other colours" totalVariants: How many additional variants are available for this product. For example when searching for 'small tshirt', if a product has 3 colours available in small then the value here will be 2. If the search was 'tshirt' then the same record would return a value of 8 if there are 3 colours and 3 sizes of each available. score: The score the record has achieved, ie. how relevant it is, which is used for sorting by relevance. This value must be either explicitly requested in fields or using Search Preference enableScores. klevu_manual_boosting: Any manual score assigned by the merchant. This value must be either explicitly requested in fields or using Search Preference enableScores. klevu_bulk_boosting: Any manual score assigned by the manual boosting rules. This value must be either explicitly requested in fields or using Search Preference enableScores. klevu_selflearning_boosting: The machine learning score assigned by the Klevu Search engine. This value must be either explicitly requested in fields or using Search Preference enableScores. brand: The brand of the product, eg. 'Nike'. tags: Any tags or keywords Klevu has saved for the record. typeOfRecord: The type of record, e.g. KLEVU_PRODUCT, KLEVU_CMS, KLEVU_CATEGORY, etc. other fields: There will also be various other fields returned according to the data you have indexed, which will vary from store to store.

Updated 30 Oct 2023

Did this page help you?

Smart Search

Search as you type