Search & Listing
This API returns a list of products (in a paginated structure) given a search query and/or list of filters.
#
AuthenticationYou 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#
Request TypePOST
#
Request HeadersContent-Type: application/jsonx-api-key: <api_key>
Note:
You can skip sending x-api-key if you choose authentication via Requesting URL.
#
EndpointThe base URL will be provided to you at the time of onboarding.
POST <base_url>/widgets
#
Request ParametersParam | Type | Required | Description | |
---|---|---|---|---|
search_query | string | no | Term(s) for which search operation has to be performed. To be passed for text search case alone. | |
module_name | string | yes | A string that indicates which module has to be invoked. | |
mad_uuid | string | yes | Unique 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_num | integer | yes | Indicates which page results to be retrieved. | |
num_results | integer | no | Indicates the number of results to be returned in the response per page. Defaults to [50] | |
order_by | JSON object | no | Indicates the sorting order in which results has to be returned. Sort section describes this in detail. | |
user_id | string | no | Unique ID associated by the merchant to the user in the site. | |
fields | array of string | no | List of fields to be fetched for every product in the response. Fields section describes this in detail. | |
facets | array of string | no | Indicates the list of facets to be returned in the response. Example: brand, size, color, category, sub_cat, etc, | |
facet_limit | integer | no | Number of facet values to be returned per facet field. Defaults to 100. | |
filters | array of JSON objects | no | List 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. |
#
Sortorder_by is a JSON object that indicates the sorting order applied to the results.
Sort Object Parameters
Param | Type | Description |
---|---|---|
field | string | The name of the field to apply sort on. For example: price, trending, created_date, relevance. |
order | string | The order of sort. Allowed values: asc - Ascending, desc - Descending. |
when the field is not specified, defaults to relevance sort in descending order.
#
FieldsFields 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.
#
FiltersFilters 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
Param | Type | Description |
---|---|---|
field | Mandatory type: string | The name of the field to apply filter on. For example, brand, category etc. |
type | Mandatory type: string | The type of operation. |
value | Mandatory type: string | The value for the condition. |
The different values the type parameter supports is described below:
Values | Description | Applicable to | Value parameter format |
---|---|---|---|
exact | Used for 'equals to' condition | any field | a single value or list of values |
not-exact | Used for 'not equals' condition | any field | a single value or list of values |
lte | Used for 'less than or equals to' condition | number | single value |
lt | Used for 'less than' condition | number | single value |
gte | Used for 'greater than or equals to' condition. | number | single value |
gt | Used for 'greater than' condition | number | single value |
range | Used to indicate a range. | number | list of two values of format [lower-bound, higher-bound] |
contains | Used to match the specified words or phrases within a particular string | string | single 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 }]
#
ResponseThe response will have the list of products with the metadata based on search query and/or filters applied.
#
Response ParametersBody of the response is a JSON object with the following structure:
Field | Type | Description |
---|---|---|
status | string | Indicates the status of the response |
message | string | Indicates details about failure or null response |
data | list of json objects | Explanation below |
Data Object Parameters:
Field | Type | Description |
---|---|---|
query_params | dictionary | Contains the request body payload. |
data | list of dictionaries | JSON object which contains results matching the input params along with the fields requested. |
facets | dictionary | Returns the facet value with count for the results matching the input params. |
num_of_pages | integer | Total number of pages available. |
total_count | integer | Total number of results matching the query passed in the request payload. |
page_num | integer | Current page number of the results. |
page_size | integer | Number of results returned per page. |
module_name | string | A string that indicates which module returned the results. |
#
Response Status CodeStatus codes indicate if the response was successful or not.For the different response codes we return, please refer the table below:
Status Code | Description |
---|---|
200 | Successful. |
401 | Authorization has been denied for this request. |
500 | Unhandled application errors. |
#
ExampleNote: If Allowed hosts authentication mode is used, you can skip sending x-api-key in headers.
Request:
- JavaScript
- Python
- Ruby
- cURL
- PHP
- Java
- C#
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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5};var xhr = new XMLHttpRequest();xhr.withCredentials = true;xhr.addEventListener("readystatechange", function() {if(this.readyState === 4) {console.log(this.responseText);}});xhr.open("POST", "{{base_url}}/widgets");xhr.setRequestHeader("x-api-key", "9ed6bd6a23db7dd422893e1e0");xhr.send(data);
import requestsurl = "{{base_url}}/widgets"payload = {"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}headers = {"x-api-key": "9ed6bd6a23db7dd422893e1e0"}response = requests.request("POST", url, headers=headers, data=payload)print(response.text)
require "uri"require "net/http"url = URI("{{base_url}}/widgets")http = Net::HTTP.new(url.host, url.port);request = Net::HTTP::Post.new(url)request["x-api-key"] = "9ed6bd6a23db7dd422893e1e0"request.body = '{"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}'response = http.request(request)puts response.read_body
curl --location -g --request POST '{{base_url}}/widgets'--header 'x-api-key: 9ed6bd6a23db7dd422893e1e0'--data-raw '{"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}'
<?phprequire_once 'HTTP/Request2.php';$request = new HTTP_Request2();$request->setUrl('{{base_url}}/widgets');$request->setMethod(HTTP_Request2::METHOD_POST);$request->setConfig(array('follow_redirects' => TRUE));$request->setHeader(array('x-api-key' => '9ed6bd6a23db7dd422893e1e0'));$request->setBody('{"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}');try {$response = $request->send();if ($response->getStatus() == 200) {echo $response->getBody();}else {echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .$response->getReasonPhrase();}}catch(HTTP_Request2_Exception $e) {echo 'Error: ' . $e->getMessage();}
OkHttpClient client = new OkHttpClient().newBuilder().build();MediaType mediaType = MediaType.parse("text/plain");RequestBody body = RequestBody.create(mediaType, "{"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}");Request request = new Request.Builder().url("{{base_url}}/widgets").method("POST", body).addHeader("x-api-key", "9ed6bd6a23db7dd422893e1e0").build();Response response = client.newCall(request).execute();
var client = new RestClient("{{base_url}}/widgets");client.Timeout = -1;var request = new RestRequest(Method.POST);request.AddHeader("x-api-key", "9ed6bd6a23db7dd422893e1e0")request.AddParameter("text/plain", '{"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": ["brand","category","ontology"],"fields": ["brand","title","product_id","image_link","link","price"],"page_num": 1,"facet_limit": 100,"num_results": 5}', ParameterType.RequestBody);IRestResponse response = client.Execute(request);Console.WriteLine(response.Content);
Response:
{ "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" } ]}