Skip to main content

Search & Listing

This API returns a list of products (in a paginated structure) given a search query and/or list of filters.


You can choose to use API keys or Requesting URLs based on your requirements & preference. Check here to choose one that suits you the best.


Request Type#


Request Headers#

Content-Type: application/jsonx-api-key: <api_key>

You can skip sending x-api-key if you choose authentication via Requesting URL.


The base URL will be provided to you at the time of onboarding.

POST <base_url>/widgets

Request Parameters#

search_querystringnoTerm(s) for which search operation has to be performed. To be passed for text search case alone.
module_namestringyesA string that indicates which module has to be invoked.
mad_uuidstringyesUnique ID to identify the shopper. This should be unique for a particular user session. If you are using the script for integration, fetch mad_uuid using this method. If you are only using APIs and not script: Set and get mad_uuid using this method. Note: The same mad uuid should be passed in recommendations, search and events API.
page_numintegeryesIndicates which page results to be retrieved.
num_resultsintegernoIndicates the number of results to be returned in the response per page. Defaults to [50]
order_byJSON objectnoIndicates the sorting order in which results has to be returned. Sort section describes this in detail.
user_idstringnoUnique ID associated by the merchant to the user in the site.
fieldsarray of stringnoList of fields to be fetched for every product in the response. Fields section describes this in detail.
facetsarray of stringnoIndicates the list of facets to be returned in the response. Example: brand, size, color, category, sub_cat, etc,
facet_limitintegernoNumber of facet values to be returned per facet field. Defaults to 100.
filtersarray of JSON objectsnoList of business rules to be applied to the recommendation results. This overrides the business rules configured in the tool. Filters section describes this in detail.

order_by is a JSON object that indicates the sorting order applied to the results.

Sort Object Parameters

fieldstringThe name of the field to apply sort on. For example: price, trending, created_date, relevance.
orderstringThe order of sort. Allowed values: asc - Ascending, desc - Descending.

when the field is not specified, defaults to relevance sort in descending order.


Fields is a list of string that indicates the metadata of the products that are returned in the recommendation response. Any field from your catalog can be used here.


Filters is a list of business rules that is applied to further refine recommendation results. Ensure that the fields that are defined in business rules are indexed for faster response. The filters applied via the API will always override the filters applied on the tool.

If you need the filters to be applied in addition to the business rules configured in the tool, please use filters_append key. A filter object represents one condition and if there are multiple conditions they are all applied using "AND" operation.

Filter Object Parameters

fieldMandatory type: stringThe name of the field to apply filter on. For example, brand, category etc.
typeMandatory type: stringThe type of operation.
valueMandatory type: stringThe value for the condition.

The different values the type parameter supports is described below:

ValuesDescriptionApplicable toValue parameter format
exactUsed for 'equals to' conditionany fielda single value or list of values
not-exactUsed for 'not equals' conditionany fielda single value or list of values
lteUsed for 'less than or equals to' conditionnumbersingle value
ltUsed for 'less than' conditionnumbersingle value
gteUsed for 'greater than or equals to' condition.numbersingle value
gtUsed for 'greater than' conditionnumbersingle value
rangeUsed to indicate a range.numberlist of two values of format [lower-bound, higher-bound]
containsUsed to match the specified words or phrases within a particular stringstringsingle value

The below examples show the different price filters that can be sent for search:

[  {    "field": "price",    "type": "range",    "value": [      0,      500    ]  }]
[  {    "field": "price",    "type": "lte",    "value": 500  }]
[  {    "field": "price",    "type": "gte",    "value": 500  }]

Category filters:

 [  {    "field": "category",    "type": "contains",    "value": [      "dresses",      "shirts"    ]  }]

Price & Availability filters:

[  {    "field": "available",    "type": "exact",    "value": "true"  },  {    "field": "price",    "type": "lte",    "value": 500  }]


The response will have the list of products with the metadata based on search query and/or filters applied.

Response Parameters#

Body of the response is a JSON object with the following structure:

statusstringIndicates the status of the response
messagestringIndicates details about failure or null response
datalist of json objectsExplanation below

Data Object Parameters:

query_paramsdictionaryContains the request body payload.
datalist of dictionariesJSON object which contains results matching the input params along with the fields requested.
facetsdictionaryReturns the facet value with count for the results matching the input params.
num_of_pagesintegerTotal number of pages available.
total_countintegerTotal number of results matching the query passed in the request payload.
page_numintegerCurrent page number of the results.
page_sizeintegerNumber of results returned per page.
module_namestringA string that indicates which module returned the results.

Response Status Code#

Status codes indicate if the response was successful or not.For the different response codes we return, please refer the table below:

Status CodeDescription
401Authorization has been denied for this request.
500Unhandled application errors.


Note: If Allowed hosts authentication mode is used, you can skip sending x-api-key in headers.


var data = {
"mad_uuid": "a06ca0ed-09ba-4c61-a532-a4ebc5e8a465",
"module_name": "default-textsearch",
"search_query": "red dress",
"filters": [
"field": "available",
"type": "exact",
"value": "true"
"order_by": [
"field": "relevance",
"order": "desc"
"facets": [
"fields": [
"page_num": 1,
"facet_limit": 100,
"num_results": 5
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
});"POST", "{{base_url}}/widgets");
xhr.setRequestHeader("x-api-key", "9ed6bd6a23db7dd422893e1e0");


{  "status": "ok",  "message": "",  "data": [    {      "query_params": {        "module_name": "default-textsearch",        "mad_uuid": "pixel_generated_anonymised_id",        "user_id": "anonymised_uniquer_user_id",        "search_query": "red dress",        "filters": [          {            "field": "available",            "type": "exact",            "value": "true"          }        ],        "order_by": [          {            "field": "relevance",            "order": "desc"          }        ],        "facets": [          "brand",          "category",          "ontology"        ],        "fields": [          "brand",          "title",          "product_id",          "image_link",          "link",          "price"        ],        "page_num": 1,        "facet_limit": 100,        "num_results": 5      },      "facets": {        "category": {          "Clothing": 750        },        "brand": {          "Brand 1": 400,          "Brand 2": 100,          "Brand 3": 100,          "Brand 4": 100,          "Brand 5": 50        },        "ontology": {          "women>clothing>dresses>day dresses": 400,          "women>clothing>dresses>cocktail dresses": 100,          "women>clothing>dresses>work dresses": 100,          "women>clothing>dresses>evening dresses": 100,          "women>clothing>knits>knit dresses": 50        }      },      "data": [        {          "title": "Red Dress 1",          "price": 39,          "image_link": "image_link",          "link": "pdp_link",          "brand": "Brand 1",          "product_id": "123456781"        },        {          "title": "Red Dress 2",          "price": 49,          "image_link": "image_link",          "link": "pdp_link",          "brand": "Brand 2",          "product_id": "123456782"        },        {          "title": "Red Dress 3",          "price": 59,          "image_link": "image_link",          "link": "pdp_link",          "brand": "Brand 3",          "product_id": "123456783"        },        {          "title": "Red Dress 4",          "price": 69,          "image_link": "image_link",          "link": "pdp_link",          "brand": "Brand 4",          "product_id": "123456784"        },        {          "title": "Red Dress 5",          "price": 79,          "image_link": "image_link",          "link": "pdp_link",          "brand": "Brand 5",          "product_id": "123456785"        }      ],      "total_count": 750,      "page_num": 1,      "page_size": 5,      "num_of_pages": 150,      "module_name": "default-textsearch"    }  ]}