Docs

Search API

Overview

The Search API lets you interact with the Unbxd platform and implement all search related functionality with ease.
You can use the JSON / XML response and customize your search experience by leveraging various built-in features of Search. This API can communicate over HTTP and HTTPS.

Authentication

Use the API_KEY and SITE_KEY to authenticate the Search API. These keys are generated at the time of account creation and can be accessed within Console at Manage -> Configure Site -> Keys.

Unbxd Search API format

The Search API allows you to query the search results list of products matching search criteria, the facets results and also add filters, sorts.

Request Parameters

The Search API call will have the following format:

https://search.unbxd.io/<API-KEY>/<SITE-KEY>/search?q=<query>&version=V2  
&format=<xml|json>&start=<start_no>&rows=<page_size>&filter-id=<filter_query>&sort=<sort field>asc|desc&uid=<uid>&<fields=comma separated list of fields>&selectedfacet=true

Note: Passing “version” parameter is mandatory in the API. However, V1 is deprecated, please ensure that every API call has “version=V2”.

ParameterDescriptionMandatoryDefault Value
qSearch query.Yesn/a
API KeyAPI key.Yesn/a
Site KeySite key.Yesn/a
versionVersion of the API.Yesn/a
formatFormat of the response. This value can be: "xml" or "json". Nojson
startOffset in the complete result set.No0
rowsNumber of products in a single page. Set value as 0, if you don’t want products in the response. No10
variantsEnables or disables variants in the API response.Nofalse
variants.countNumber of variants to be sent in the API response.No1
fieldsSet of fields to be returned.No* (all the product fields passed in the feed will be returned in the response)
facetEnables or disables displaying of facets in the UI. Note: All other parameters related to facet feature are mentioned in the detail below.Notrue
selectedfacetEnables or disables sending selected facets in the API response.Nofalse
filter-idRestrict the products based on criteria passed (using field-id).Non/a (no filter will be applied)
filterRestrict the products based on criteria passed (using field-name).Non/a (no filter will be applied)
sortRank products based on criteria passed.Non/a (default rank would be based on Unbxd relevancy)
redirectEnables or disables redirect response for the query. If you want to forcefully override redirect response with search response, set value to false.Notrue
spellcheckEnables or disables “Did You Mean” functionality for the query.Notrue
fallbackEnables or disables autocorrection and subsequent firing of the misspelled search queryNotrue
bannerEnables or disables displaying of banner set in the Console.Notrue
analyticsEnables or disables tracking of the request by Unbxd analytics.Notrue
statsSpecifies a field for which statistics should be generated.Non/a

Headers

To enable personalization, segmentation, and A/B testing of the merchandising campaigns, we recommend passing certain parameters as HTTP headers. The following parameters are available:

ParameterDescriptionMandatorySignificance
unbxd-user-idUnique identification for the visitors. Example: uid-1466015353887-20419. The Unbxd Analytics javascript sets the unbxd.userId in your browser cookie. NoIf not passed, personalisation, segmentation, and A/B testing of merchandising campaigns will not work
user-agentBrowser identification information passed to the web server with every HTTP request.NoIf not passed, device based merchandising campaigns will not work.
unbxd-device-typeThis header is an Unbxd custom header which is required to identify if the request is coming from an app.NoIf not passed, device based merchandising campaigns will not be able to differentiate between browser and apps.
Accept-EncodingThis header signifies the content encoding of the response. Currently, Unbxd supports only gzip compression. To enable this, ‘gzip’ needs to be passed NoIf not passed, the response will not be compressed.
X-Forwarded-ForThis header signifies the IP address of the end user. This is primarily required if the integration is backend as Unbxd doesnt get the IP of the end user from the browser in that case.NoIf not passed, segmentation, A/B testing and personalization will not work.

Response Components

Unbxd returns the list of products which match the search criteria. The response would be in application/json or application/xml content type format.

ComponentDescription
statusResponse status code.
queryTimeTime taken to process the request.
queryParamsParameters sent as part of the request.
numberOfProductsTotal number of products returned for the page.
startOffset in the complete result set of products for the page
productsAll products matched. Structure will be the same as passed in the feed.
relevantDocumentMentions if the parent or the variant for a particular product needs to be displayed in the UI. It can be either ”parent” or “variant”.
facetsFilters which are displayed in the UI to allow visitors to narrow down result set based on product fields.
breadcrumbPosition in the field hierarchy where the results lie.
selectedFilters which are selected in the UI.
redirectRedirect response for the query.
didYouMeanSpellcheck response with a query suggestion.
bannerRBanner response for the query.

A sample request and response is shown below:

Request

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&rows=1&version=V2  

Request parameters

q

The main query parameter passed in the request, the search term visitor enters in the search box. It is a mandatory query parameter.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&version=V2  

version

The version parameter specifies the version of the API. You should always pass “&version=V2” in every API call to get the latest features of the API. If you do not pass version = v2, then the default value v1 is applied.

format

The format parameter specifies the format of the response. Possible values are ‘json’ or ‘xml’. It is an optional parameter and the default value is ‘json’.

Sample JSON request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&format=json&version=V2  

Sample XML request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&format=xml&version=V2  

start

The start parameter is used to offset the results by a specific number. It indicates offset in the complete result set of the products. It is an optional parameter and the default value is 0.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&start=40&version=V2  

rows

The rows parameter is used to paginate the results of a query. It indicates number of products in a single page. It is an optional parameter and the default value is 10, maximum value is 100.

Note: If the products are not required in the response, the parameter needs to be set to 0.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&rows=20&version=V2  

variants

If the feed has variants, the variants parameter enables or disables variants in the API response. It can take two values: “true” or “false”. Default value is “false”.

  • If “variants” is set to to true, all the variants for a product are clubbed together.
  • If “variants” is set to false, all the variants are sent separately as different products.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&rows=20&variants=true&version=V2  

variants.count

A product may have multiple variants and by default, the most relevant variant is sent in the response when variants are enabled. If you want to get more than one variants in the API response, you can use this parameter. It can have any numerical value (eg, 1,2,3,etc) or “*” (to get all the variants).

API request to get top two variants per product:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&rows=20&variants.count=2&variants=true&version=V2  

API request to get all variants per product:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&rows=20&variants.count=*&variants=true&version=V2  

fields

The fields parameter is used to specify the set of fields to be returned. The set of fields to be returned can be specified as a comma separated list of field names. When returning the results, only fields in the list will be included. It is an optional parameter; however, it is recommended to pass only the fields required in the response to reduce the response size. If this parameter is not applied, all the fields will be returned in the response by default.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&fields=title,vPrice&version=V2  

Bucketing

Bucketing allows you to group products with a common field value into groups known as buckets, returning the top products per bucket, and the top buckets based on what documents are in the groups. It is necessary that every bucket field is also the facet field in your e-commerce store.

For example, a search at your site for a common term such as DVD, will show the top 3 results for each category (“TVs & Video”,”Movies”,”Computers”, etc).

This is how a bucket query looks like:

https://search.unbxdapi.io/<API-KEY>/<SITE-KEY>/search?q=Shirts&format=<xml|json>&&bucket.field=<bucket_field>&<rows=42><bucket.limit=5>&<&bucket.offset=5> &<sort>&bucket.sortByCount=desc&sort=<sort field>desc  

Note: You can also use https.

API Parameters

Query ParameterData TypeDescription
&bucket.fieldStringThe name of the field to be bucketed.
&bucket.limitStringDetermines the maximum number of buckets.
&bucket.offsetStringTo paginate to the next 5 products of each group.
&rowsIntegerDetermines the number of products shown in each group.

Note: By default, the first 10 bucket will be displayed.

A typical bucket query response looks like:

"buckets":{
                "totalProducts":22331,
                "numberOfBuckets":386,
                "<group value 1>":{"numberOfProducts":168,"start":0,"products":[
                                {
                                        product_1
                                },
                                .
                                .
                                .
                                {
                                        product_N
                                }]
                },
                "<group value 2>":{"numberOfProducts":4098,"start":0,"products":[
                                {
                                        product_1
                                },
                                .
                                .
                                .
                                {
                                        product_N
                                }]
                },
                "<group value 3>":{"numberOfProducts":1370,"start":0,"products":[
                                {
                                        product_1
                                },
                                .
                                .
                                .
                                {
                                        product_N
                                }]
                }
        }

sort

The sort parameter is used to rank the products based on specified fields in the specified order. It is an optional parameter. If not passed, products would be returned ordered on Unbxd relevancy algorithm.

Sorting on Single Field

You can sort your search API results using a sort function as shown below:

https://search.unbxd.io/<api-key>/<site-key>/search?q=<query>&version=V2&sort=fieldname sort_order  
  • fieldname: The field on which the sort is applied.
  • sort_order: The order in which the sort is applied. This value can be "asc" (for ascending) or "desc" (for descending)

For example, a visitor wants to sort results on price in ascending order, the API call below is made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&version=V2&sort=price%20asc  

Note: There is a space between the field name and the sort_order in the API call.

Sorting on Multiple Fields

To apply multiple sort rules, you need to make an API call as shown below:

https://search.unbxd.io/<api-key>/<site-key>/search?q=<query>&version=V2&sort=field1 sort_order,field2 sort_order,field3 sort_order  

Note: When multiple sort parameters are applied, the products will be sorted based on the first criteria passed in the request. Only in the case when multiple products have the same value for the first criteria, then the latter sorting criteria will be applied within those products.

For example, to show results sorted on price and title the API call below is made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?q=shirt&sort=price%20asc,title%20desc&version=V2  

redirect

The redirect feature allows merchandisers to redirect visitors to a web page for the search query. This helps visitors navigate to the category pages as well as non-catalog based information of the website such as, contact information, privacy policy, etc., right from your site's search box. In other words, if you do not want a particular query to be looked up in the search index, you can configure a redirect for such queries.

Redirects for a query can be configured from the Merchandizing section of your Console. By default, the redirect is enabled for the search query if set in the Console.

Note: If you want to forcefully override redirect response with search response, set value to false. Here is the sample:

https://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search? &q=iphone%20cases&redirect=false  

spellcheck

The spellcheck feature provides spelling suggestions or spell-check for misspelled search queries. In such cases, the context-aware algorithm of Unbxd understands your visitor’s intent and sends a “Did You Mean” response along with search result set for the query, if any. Our analytics tracks the frequency of similar misspelled queries and ranks spelling suggestions accordingly.

Note: Unbxd recommends to integrate “Did You Mean” as it prevents your visitors to run into a zero-results page, which might be an unpleasant experience for your visitors.

This parameter enables or disables the spellcheck suggestion generation. The default value of this parameter will be ‘true’. To disable the feature, the API call below needs to be made:

https://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphonr&spellcheck=false  
fallback

Visitors may misspell when searching for an item on your website. It is important that the site is able to autocorrect the misspelled words and display the most relevant search results without waiting for the customer to request results for the correctly spelled search query.

The fallback flag will spellcheck the search query and display results for the autocorrected search query.

fallback=true&fallback.method=spellcheck  


Note: By default, fallback is set to false.

When fallback is set to true, the fallback.method=spellcheck is enabled, by default. This indicates that only the spellcheck fallback method will be activated.

fallback.method
Multiple autocorrect strategies can be enabled using a fallback.method parameter with comma-separated values (CSVs). The sequence of the strategies will depend on the order in which they appear.

Currently, Unbxd system supports only fallback.method=spellcheck

Banners

Banners can be easily configured from your dashboard during campaign creation. Once you have correctly configured your banner, the search API call will return the banner information as a part of the catalog-based response.

This feature can be disabled from the HTTP request using the ‘banner’ parameter. The default value of this parameter would be true.

Sample request:

https://search.unbxd.io/<api-key>/<site-key>/search?q=<query>&banner=false&version=V2  

Banner response comes as a part of the catalog-based response. There are two types of banner response according to how you have configured it in the dashboard.

Sample response:

For Hosted Banners:

{
    "banner": {
        "banners": [{
            "imageUrl": "value",
            "landingUrl": "value",
            "bannerHtml": null
        }]
    }
}

For Custom Banners:

{
    "banner": {
        "banners": [{
            "imageUrl": null,
            "landingUrl": null,
            "bannerHtml": "value "
        }]
    }
}
  • imageUrl: The URL of the hosted banner image.
  • landingUrl: The URL of the page your visitors arrives after clicking the banner.
  • bannerHtml: The URL of the custom (HTML) banner image.

Note: The value of the response parameters will change to "null" according to the type of banner configuration.

For example, a visitor searched a query, the banner response below will help you set up a hosted banner in your eCommerce site:

{
    "banner": {
        "banners": [{
"imageUrl":"http://www.myecommercewebsite.com/images/iphone-cases-banner.jpg",
"landingUrl":"http://www.myecommercewebsite.com/search?q=iphone%20cases",
            "bannerHtml": null
        }]
    }
}

analytics

The analytics parameter enables or disables tracking the query hit for analytics. By default, tracking is enabled. To disable tracking, set value to false.

https://search.unbxd.io/<api-key>/<site-key>/search?q=<query>&analytics=false&version=V2  

stats

The stats parameter gives information about the products with highest and lowest field value. For example, to apply stats on the price field make the API call below:

https://search.unbxd.io/<api-key>/<site-key>/search?q=<query>&stats=price&version=V2  

Response Components

relevantDocument

This is a field within each product. It mentions if the parent or the variant for a particular product needs to be displayed in the UI for that particular request. It can have two possible values: ”parent” or “variant”.

"relevantDocument": "parent"

Integrating Autosuggest

The Autosuggest feature provides query suggestions which helps your visitors to search faster in your site. Unbxd supports autocompletion of search queries and showcasing products relevant to query as they type. Usually, this feature comes in-built with the Unbxd Search, but you can also employ Unbxd Autosuggest as a standalone feature in your site.

With Autosuggest, your visitors can easily search products directly from your site’s search bar.

To integrate Unbxd Autosuggest, you need to make the API call below to Unbxd servers:

https://search.unbxd.io/yourapikey/yoursitekey/autosuggest?q=value&inFields.count=value&popularProducts.count=value&keywordSuggestions.count=value&topQueries.count=value  

The table below describes the different API parameters for an autosuggest API call.

<response>  
 <lst name="searchMetaData">
   <int name="status">value</int>
   <int name="queryTime">value</int>
 <lst name="queryParams">
   <str name="q">value</str>
   <str name="topQueries.count">value</str>
   <str name="json.wrf">jQuery11515510874409456_145824823539   </str>
   <str name="keywordSuggestions.count">value</str>
   <str name="popularProducts.count">value</str>
   <str name="inFields.count">value</str>
   <str name="wt">value</str>
   <str name="_">value</str>
 </lst>
 </lst>
<result name="response" numberOfProducts="value" start="value">  
 <product>
   <str name="autosuggest">value</str>
   <str name="doctype">TOP_SEARCH_QUERIES</str>
   <double name="unbxdAutosuggestScore">value</double>
   <str name="uniqueId">Random value</str>
 </product>
 <product>
   <str name="autosuggest">value</str>
   <str name="doctype">IN_FIELD</str>
   <str name="unbxdAutosuggestSrc">value</str>
 <arr name="value_in">
   <str>value</str>
 </arr>
  <str name="uniqueId">Random value</str>
</product>  
<product>  
   <str name="autosuggest">value</str>
   <str name="doctype">POPULAR_PRODUCTS</str>
   <double name="price">value</double>
 <arr name="imageUrl">
   <str>
value  
   </str>
 </arr>
   <str name="name">value</str>
   <str name="url_path">
value  
   </str>
   <str name="sku">value</str>
   <str name="uniqueId">popularProduct_value</str>
   <double name="unbxdAutosuggestScore">value</double>
</product>  
<product>  
   <str name="autosuggest">value</str>
   <str name="doctype">KEYWORD_SUGGESTION</str>
   <str name="uniqueId">Random value</str>
</product>  

Response Keys

The table below describes the different response keys of an autosuggest call.

Example

A visitor typed for "i". The below autosuggest response will help you understand Unbxd autosuggest in your eCommerce site:

jQuery19104932622171413903_1463126000329({  
  "searchMetaData":{
    "status":0,
    "queryTime":6,
    "queryParams":{
      "q":"i",
      "topQueries.count":"2",
      "json.wrf":"jQuery19104932622171413903_1463126000329",
      "keywordSuggestions.count":"2",
      "popularProducts.count":"4",
      "inFields.count":"2",
      "_":"1463126000331"}},
  "response":{"numberOfProducts":503,"start":0,"products":[
      {
        "autosuggest":"Icebug",
        "doctype":"IN_FIELD",
        "unbxdAutosuggestSrc":"brand",
        "category_in":["women",
          "Boots"],
        "brand_in":["Icebug"],
        "uniqueId":"47c08913-29e9-4b01-804d-27856bd3dd79"},
      {
        "autosuggest":"Isola",
        "doctype":"IN_FIELD",
        "unbxdAutosuggestSrc":"brand",
        "category_in":["women"],
        "brand_in":["Isola"],
        "uniqueId":"55768796-8a28-4b32-8a14-612d1404fc2c"},
      {
        "autosuggest":"Izola",
        "doctype":"IN_FIELD",
        "unbxdAutosuggestSrc":"brand",
        "category_in":["Bath & Body"],
        "brand_in":["Izola"],
        "uniqueId":"f5448c66-e095-482c-b16f-a74b048510a9"},
      {
        "autosuggest":"'Intreccio' Hobo",
        "doctype":"POPULAR_PRODUCTS",
        "title":"'Intreccio' Hobo",
        "price":6542.0,
        "price_fq":6542.0,
        "imageUrl":["http://g.nordstromimage.com/imagegallery/store/product/Medium/1/_8536601.jpg"],
        "uniqueId":"popularProduct_5315b8555e4016e5737bdaf3",
        "unbxdAutosuggestScore":0.0},
      {
        "autosuggest":"'Iridia' Pump",
        "doctype":"POPULAR_PRODUCTS",
        "title":"'Iridia' Pump",
        "price":52908.0,
        "price_fq":52908.0,
        "imageUrl":["http://g.nordstromimage.com/imagegallery/store/product/Medium/7/_8784147.jpg"],
        "uniqueId":"popularProduct_5315b8555e4016e5737bdc0b",
        "unbxdAutosuggestScore":0.0},
      {
        "autosuggest":"'Isabel' Pump",
        "doctype":"POPULAR_PRODUCTS",
        "title":"'Isabel' Pump",
        "price":38267.0,
        "price_fq":38267.0,
        "imageUrl":["http://g.nordstromimage.com/imagegallery/store/product/Medium/19/_6273779.jpg"],
        "uniqueId":"popularProduct_5315b8555e4016e5737bdd67",
        "unbxdAutosuggestScore":0.0},
      {
        "autosuggest":"'Innsbruck' Slipper",
        "doctype":"POPULAR_PRODUCTS",
        "title":"'Innsbruck' Slipper",
        "price":9916.0,
        "price_fq":9916.0,
        "imageUrl":["http://g.nordstromimage.com/imagegallery/store/product/Medium/4/_6742544.jpg"],
        "uniqueId":"popularProduct_5315b8555e4016e5737bde71",
        "unbxdAutosuggestScore":0.0},
      {
        "autosuggest":"Jane Iredale",
        "doctype":"KEYWORD_SUGGESTION",
        "uniqueId":"f0d9b7ce-1f33-4815-9d88-03fa997755ad"},
      {
        "autosuggest":"Majestic International",
        "doctype":"KEYWORD_SUGGESTION",
        "uniqueId":"ec3cd616-c73a-4efd-acfd-25d69ed8d038"}]
{
"autosuggest": "TOMS Shoes",
"autosuggest_unstemmed": "TOMS Shoes",
"start_unbxdDate": 1500554580000,
"end_unbxdDate": 3867350400000,
"doctype": "PROMOTED_SUGGESTION",
"uniqueId": "f74b415d-142c-4ace-ae44-6916dadb2425",
"timeStamp_unbxd": 1644549494101257,
"_version_": 1581037326934474800,
"parent_unbxd": true
},
{
"autosuggest": "walking shoes",
"autosuggest_unstemmed": "walking shoes",
"start_unbxdDate": 1500554820000,
"end_unbxdDate": 3867350400000,
"doctype": "PROMOTED_SUGGESTION",
"uniqueId": "988d0038-2aec-47c7-80d0-b5af4c5813f5",
"timeStamp_unbxd": 1644549656981245,
"_version_": 1581037327106441200,
"parent_unbxd": true
}

  }})

Facet Overview

Faceting provides your visitors an interface to select desired field values (or product attributes) (or search listing page) in order to filter their search results.

Every time a user clicks a facet value, the set of results is reduced to only the items that have that value. Additional clicks continue to narrow down the search—the previous facet values are remembered and applied again. For example, the user might click "Cookbooks," and see a list of all 10 cookbook titles next to an updated navigation list like this:

If price is more important to the user than the reviews of fellow shoppers, the next click would be on a price range, say "$10-19.99." Now the list might look like this:

At this point, it is very easy for the user to choose the right cookbook.

Hence, faceted search results provide an easy-to-scan, browsable display that helps users quickly narrow down each search.

Facets can be easily configured from the Manage -> Configure Search -> Configure Facet section of the Console.Learn More

Example

Sample request:

https://search.unbxd.io/<api_key>/<site_key>/search?q=samsung&facet.multiselect=true  

Sample Response:

{
    "facets": {
        "multilevel": {
            "list": [{
                "filterField": "productType",
                "level": 2,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO001",
                        "name": "Decor",
                        "count": 15
                    },
                    {
                        "id": "Ho002",
                        "name": "Outdoors",
                        "count": 16
                    }
                ],
                "breadcrumb": {
                    "filterField": "productType",
                    "values": [{
                        "id": "HO",
                        "name": "Home"
                    }],
                    "level": 1
                }

            }]
        },
        "range": {
            "list": []
        },
        "text": {
            "list": []
        }
    }
}

Here, when a search API is fired, "facet" is received in response.

Facet response contains different types of facets (for example, Categories, Brand , Color, Price etc..) that are configured by client with respective values and count of those values. For example, if Brand is configured for faceting, response will look like:

{
  "facets": {
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Samsung",
            663
          ],
          "displayName": "brand",
          "position": 3
        }
      ]
    }
  }
}

Response contains Facet Name: Brand, Value: Samsung and Count of products with filter Samsung = 663.

If integrated, the website will look like:

Common Features across all types facets

1. Multiselect Facet

This feature enables or disables the option to select multiple values within a facet or across facets for visitors. For example, for a query “mobile”, facets on brand and color fields are displayed. If the value for facet.multiselect is set as true and if a visitor selects Apple in the brand facet, the search results will be refined according to the selection. However, all values in the brand facet will still be sent in the response as if the brand filter isn’t applied (and other filters are applied, if any). Multi-select faceting is based on filter operations, that is, AND and OR.

For example (facet.multiselect=true/false)
Search query: “mobile”
Facet configured for fields: Brand and Price only.

facet.multiselect =true (default =false)

Facet Selected : Brand → Apple and Price range → 35000 to 37500

This feature is disabled by default. To enable the feature, set the value as ‘true’.

Request

Adding parameter filter=brand_uFilter:%22Apple%22 and filter=product_min_price:[35000%20TO%2037500] in request suggests, in facet brand, Apple is selected, and in price range 35000 to 37500 is selected. Selected facet is sent as filter.

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&filter=categoryPath"Mobiles & Tablets"&filter=brand_uFilter:"Apple"&filter=product_min_price:[35000 TO 37500]&version=V2&facet.multiselect=true  

Response

{
  "facets": {
    "multilevel": {},
    "range": {
      "list": [
        {
          "facetName": "product_min_price",
          "values": {
            "counts": [
              "35000.0",
              1,
              "37500.0",
              3,
              "40000.0",
              5
            ],
            "gap": 2500,
            "start": 0,
            "end": 2635000
          },
          "displayName": "price",
          "position": 1
        }
      ]
    },
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Apple",
            1,
            "LG",
            4,
            "Samsung",
            9,
            "Sony Xperia",
            3
          ],
          "displayName": "brand",
          "position": 3
        }
      ]
    }
  }
}

2. Selected Facet in Response

Search query: “mobile”
Facet configured for fields: Brand and Color only. Both are text based fields (which means values of these fields will be of data type text).
Selected facet: Apple
selectedfacet= true

Request

Here in this example, since selectedfacet= true was sent explicitly as the part of request, In response we received a json which contained the field name, field id, value name, value id combination of the facets selected in the UI. (If selectedfacet=false, which is by default the case, we do not receive such information explicitly)

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&filter=brand_uFilter:%22Apple%22&facet.multiselect=true&selectedfacet=true  

Response

As explained above, since selectedfacet= true was sent explicitly as the part of request, response we received the field name, field id, value name, value id combination of the filters selected in the UI.

{
  "response": {
    "numberOfProducts": 47,
    "products": []
  },
  "searchMetaData": {},
  "facets": {
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Acer",
            1,
            "Apple",
            47,
            "Gionee",
            28,
            "Google",
            10,
            "HTC",
            20
          ],
          "displayName": "brand",
          "position": 0
        },
        {
          "facetName": "color_uFilter",
          "filterField": "color_uFilter",
          "values": [
            "Black",
            99,
            "Gold",
            80,
            "White",
            48,
            "Silver",
            31,
            "Grey",
            24
          ],
          "displayName": "color",
          "position": 1
        },
        {
          "selected": [
            {
              "facetName": "brand_uFilter",
              "position": 3,
              "filterField": "brand_uFilter",
              "displayName": "brand",
              "values": [
                "Apple"
              ]
            }
          ]
        }
      ]
    }
  }
}

3. Disabling Facet

Search query : “mobile”
Facet configured for fields : Brand and Color only. Both are text based fields (which means values of these fields will be of data type text).

facet=false/true

Facet : Disabled in response

Request

If client has configured facets, by defaults facets are sent in response if unbxd search api is fired.
In case client wants to disable facet, sending facet=false (default value is true) along with request will disable facet in response.

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&facet=false  

Response

Here, since facet = false was sent with request, no facet was received in response.

{
  "response": {
    "numberOfProducts": 490,
    "start": 0,
    "products": []
  },
  "searchMetaData": {}
}

Types of Facets

Facets are grouped under their respective types, so that it is easy to deserialize them. Currently, we support three types of facets:

  1. Text
  2. Range
  3. Multilevel

Text

Definition

Text Facets are configured on text fields in the catalog (essentially fields whose values are of text type). For example, color, brand, size etc.

Request Parameters

Parameter NameDescription
selectedfacetThe selectedfacet parameter enables or disables the Selected Facets in the API response. If selectedfacet is false. API Response will not change. The possible values are “true” or “false”. Default value is “false”.
facet.multiselectThis feature enables or disables the option to select multiple values within a facet or across facets for visitors.

Response Properties

PropertyDescription
textType of facet configured for the facet field. Facets are grouped under their respective types, so that it is easy to deserialize them. Currently, we support "multilevel"(MultiLevel Facets), "text"(Text Facets), "range" (Range Facets).
listList of all Fields from catalog configured for text facet type. For e.g.for the field Brand, Color, Size, this list will contain Json element of each of these fields with their values and count
facetNameName of the field, configured for faceting.If more than one field is configured for faceting, comma separated json element within list containing corresponding values will be send in response.
filterFieldInternal filter field created for facet field. This is for internal reference.
valuesAll the unique values for the current facet available and their count. For example for facet brand, for query “mobile”, values are samsung (663), HTC (513) .. and so on. This means for query mobile , under brand facet we have Samsung, HTC as filters ( values) and total number of products available with that value is also sent. Shopper can select any value among ( Samsung , HTC ..) and that value will be applied as filter in search query.
displayName Name of the facet to be displayed on the website.
positionPosition identifies the position of a particular facet on website w.r.t other facet.If multiple fields from catalog are configured for facet. For example Brand, Color, Size, Position identifies the position of a particular facet on website w.r.t other facet. Position=0 means , that facet will be at the first position.

Behavior

1. When no facet is selected

Search query: “mobile”
Facet configured for fields: Brand and Color only. Both are text based fields (which means values of these fields will be of data type text).

Request:

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&version=V2&facet.multiselect=true  

Response:

As we can see from the response, for both facets Brand and color, values and their corresponding count is sent in response along with their count.

For example:

For mobile,all available brands are Acer, Apple, Gionee, Google, and HTC and response also contains count of products under each brand. Here in this example, only “1” acer mobile is available, 47 Apple mobiles are available and so on.
Similarly for facet color, we have mobiles available in colors : Black, Gold, White etc. and corresponding to black color we have 99 mobiles, 80 Gold and 48 white mobiles are available on site.

{
  "facet": {
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Acer",
            1,
            "Apple",
            47,
            "Gionee",
            28,
            "Google",
            10,
            "HTC",
            20
          ],
          "displayName": "brand",
          "position": 0
        },
        {
          "facetName": "color_uFilter",
          "filterField": "color_uFilter",
          "values": [
            "Black",
            99,
            "Gold",
            80,
            "White",
            48,
            "Silver",
            31,
            "Grey",
            24
          ],
          "displayName": "color",
          "position": 1
        }
      ]
    }
  }
}

2. When one facet is selected

Search query: “mobile”
Facet configured for fields: Brand and Color only. Both are text based fields (which means values of these fields will be of data type text).

Selected facet: Apple

Request:

Adding parameter filter=brand_uFilter:%22Apple%22 in request suggests, in facet brand, Apple is selected, and in search request, the selected facet is sent as filter.

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&filter=brand_uFilter:%22Apple%22&facet.multiselect=true  

Response

Response will contain only the products with brand “Apple”. In the response below, total number of products are 47.

{
  "response": {
    "numberOfProducts": 47,
    "products": []
  },
  "searchMetaData": {},
  "facets": {
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Acer",
            1,
            "Apple",
            47,
            "Gionee",
            28,
            "Google",
            10,
            "HTC",
            20
          ],
          "displayName": "brand",
          "position": 0
        },
        {
          "facetName": "color_uFilter",
          "filterField": "color_uFilter",
          "values": [
            "Black",
            99,
            "Gold",
            80,
            "White",
            48,
            "Silver",
            31,
            "Grey",
            24
          ],
          "displayName": "color",
          "position": 1
        }
      ]
    }
  }
}

3. Selected facet in response

Search query: “mobile”
Facet configured for fields: Brand and Color only. Both are text based fields (which means values of these fields will be of data type text).
Selected facet : Apple
selectedfacet= true

Request

In current example and in previous example, selected facet is Brand “Apple”. Difference is the response. In previous, selectedfacet= false (default value) was sent with the request, hence in response, we didn't receive any json element/block which shows which facet was selected.
Here in this example since selectedfacet= true was sent explicitly as the part of request, response we received the field name, field id, value name, value id combination of the filters selected in the UI.

https://search.unbxd.io/<api_key>/<site_key>/search?&q=mobile&filter=brand_uFilter:%22Apple%22&facet.multiselect=true&selectedfacet=true  

Response

As explained above, since selectedfacet= true was sent explicitly as the part of request, response we received the field name, field id, value name, value id combination of the filters selected in the UI.

{
  "response": {
    "numberOfProducts": 47,
    "products": []
  },
  "searchMetaData": {},
  "facets": {
    "text": {
      "list": [
        {
          "facetName": "brand_uFilter",
          "filterField": "brand_uFilter",
          "values": [
            "Acer",
            1,
            "Apple",
            47,
            "Gionee",
            28,
            "Google",
            10,
            "HTC",
            20
          ],
          "displayName": "brand",
          "position": 0
        },
        {
          "facetName": "color_uFilter",
          "filterField": "color_uFilter",
          "values": [
            "Black",
            99,
            "Gold",
            80,
            "White",
            48,
            "Silver",
            31,
            "Grey",
            24
          ],
          "displayName": "color",
          "position": 1
        },
        {
          "selected": [
            {
              "facetName": "brand_uFilter",
              "position": 3,
              "filterField": "brand_uFilter",
              "displayName": "brand",
              "values": [
                "Apple"
              ]
            }
          ]
        }
      ]
    }
  }
}

Range

Definition

Range Facets are configured on numeric fields in the catalog (essentially fields whose values are of numeric datatype). For example, Price, Discount, Offer etc.

Sample Request

Search query: “mobile”
Facet configured for fields: Price
Facet Selected : Price range → 35000 to 37500
Adding parameter filter=productminprice:[35000 TO 37500] in request suggests that in Price range 35000 to 37500 is selected.

https://search.unbxd.io/<api_key>/<site_key>/search?q=mobile&filter=product_min_price:[35000 TO 37500]&version=V2  

Sample Response

Response Properties All properties are same as text facet, other than the properties in the table below, are additional properties for range facet.

{
  "facets": {
    "multilevel": {},
    "range": {
      "list": [
        {
          "facetName": "product_min_price",
          "values": {
            "counts": [
              "35000.0",
              1,
              "37500.0",
              3,
              "40000.0",
              5
            ],
            "gap": 2500,
            "start": 0,
            "end": 2635000
          },
          "displayName": "price",
          "position": 1
        }
      ]
    },
    "text": { }
  }
}

Multilevel Facet

Definition

You can build a hierarchy in your facet values to enable multi-level navigation and filtering. This pattern is great for very long lists of values and to improve discoverability: your users will be able to browse up and down in the levels to refine their searches.

For example
Query = Mobile
Categories are

  1. Mobile & Tablets
  2. Smartphone
  3. Electronics

Using multilevel faceting, we can apply view number of products present in each category and apply these filter directly to narrow down our search.

Multilevel facet can be created by adding a 'path' field in the product catalog. The 'path' field(s) contains hierarchy information used to generate multi-level facets. Also, the same ‘path’ field can be configured as multi-valued field in order to support 2 or more than 2 types of hierarchy information for the same product type.

Request Parameters

To enable Multilevel facets, you need to configure them through Unbxd console under "Manage > Configure Site > Configure Facet". No additional request parameters are required to configure Multilevel facets from API.

Response Properties

All properties are same as text facet, other than properties in the table below which are additional properties for multilevel facet.

PropertyDescription
multilevelHierarchical facets configured on the hierarchical field(s). Facets are grouped under their respective types, so that it is easy to deserialize them. Currently, we support "multilevel" (MultiLevel Facets), "text" (Text Facets), "range" (Range Facets).
listArray of hierarchical facets as configured on the hierarchical fields in Unbxd Console.
valuesAll the unique values for the sub categories available for query and their count. For example, for query “mobile” , values are "Mobiles & Tablets"(300) , "Smartphones" (36) and so on.. This means for query mobile , under multilevel facet we have Mobiles & Tablets, Smartphones as filters ( values) and total number of products available with that value is also available. Shopper can select any value among ( Mobiles & Tablets , Smartphones ..) and that value will be applied as filter in search query.
levelDepth of multilevel field
filterFieldField on which hierarchical facet is created
breadcrumbposition within the hierarchical field where the results appear

Behavior

Unbxd API always responds with the field values belonging to a particular level and the position within the field hierarchy where the results appear as breadcrumb.

Parameter "filter" will be used to refine the fields in case of search which is exactly similar to ‘p’ parameter of the ‘Category Page API request’, which is a valid Path from the catalog, starting from the root node to the node which is requested separated ‘>’ character.

This is further explained with the following scenarios.

1. When no facets are selected (or no filters are passed)

When no facets are selected (or no filters are passed), API is going to respond with facets belonging to the first level of the field.

Request

https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2  

Response

{
"searchMetaData": {...},
"response": {...},
"facets":
 {
    "multilevel": {
        "list": [{
                "filterField": "productType",
                "level": 1,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO",
                        "name": "Home",
                        "count": 31
                    },
                    {
                        "id": "J",
                        "name": "Jewelry",
                        "count": 22
                    }
                ],
                "breadcrumb": {}
            },
            {
                "filterField": "theme",
                "level": 1,
                "id": "200",
                "displayName": "Theme",
                "position": 2,
                "values": [{
                        "id": "12",
                        "name": "Animals",
                        "count": 34
                    },
                    {
                        "id": "13",
                        "name": "Birds",
                        "count": 21
                    }
                ],
                "breadcrumb": {}
            }
        ]
    }
}
}

2. When first level of facets are selected

When first level of facets are selected, the API will respond with the second level of field values.

Request

Here is the API when the "Home" is selected:

https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2&filter=productType:"Home"  

Response

{
"searchMetaData": {...},
"response": {...},
"facets":
{
    "multilevel": {
        "list": [{
                "filterField": "productType",
                "level": 2,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO001",
                        "name": "Decor",
                        "count": 15
                    },
                    {
                        "id": "HO002",
                        "name": "Outdoors",
                        "count": 16
                    }
                ],
                "breadcrumb": {
                    "filterField": "productType",
                    "values": [{
                        "id": "HO",
                        "name": "Home"
                    }],
                    "level": 1
                }

            },
            {
                "filterField": "theme",
                "level": 1,
                "id": "200",
                "displayName": "Theme",
                "position": 2,
                "values": [{
                        "id": "12",
                        "name": "Animals",
                        "count": 34
                    },
                    {
                        "id": "13",
                        "name": "Birds",
                        "count": 21
                    }
                ],
                "breadcrumb": {
                    "filterField": "theme",
                    "values": [{
                        "id": "21",
                        "name": "MNP"
                    }],
                    "child": {
                        "filterField": "theme",
                        "values": [{
                            "id": "23",
                            "name": "ZZZ"
                        }],
                        "level": 2
                    },
                    "level": 1
                }
            }
        ]
    }
}
}

3. When second level of facets are selected

When second level of facets are selected, API will respond with the third level of field values.

Request

Here is the API when the "Home>Decor" is selected:

https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2&filter=productType:"Home>Decor"  

Response

{
"searchMetaData": {...},
"response": {...},
"facets":
{
{
    "multilevel": {
        "list": [{
                "filterField": "productType",
                "level": 3,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO011",
                        "name": "Wall Decor",
                        "count": 10
                    },
                    {
                        "id": "Ho012",
                        "name": "Floor Decor",
                        "count": 5
                    }
                ],
                "breadcrumb": {
                    "filterField": "productType",
                    "values": [{
                        "id": "HO",
                        "name": "Home"
                    }],
                    "child": {
                        "filterField": "productType",
                        "values": [{
                            "id": "HO001",
                            "name": "Decor"
                        }],
                        "level": 2
                    },
                    "level": 1
                }

            },
            {
                "filterField": "theme",
                "level": 1,
                "id": "200",
                "displayName": "Theme",
                "position": 2,
                "values": [{
                        "id": "12",
                        "name": "Animals",
                        "count": 34
                    },
                    {
                        "id": "13",
                        "name": "Birds",
                        "count": 21
                    }
                ],
                "breadcrumb": {
                    "filterField": "theme",
                    "values": [{
                        "id": "21",
                        "name": "MNP"
                    }],
                    "child": {
                        "filterField": "theme",
                        "values": [{
                            "id": "23",
                            "name": "ZZZ"
                        }],
                        "level": 2
                    },
                    "level": 1
                }
            }
        ]
    }
}
}

4. When the value from the last level is selected

When the value from the last level is selected, API will respond back with the sibling field values from the last level

Request

Here is the API when the "Home>Decor>Wall Decor" is selected:

https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2&filter=productType:"Home>Decor>Wall Decor"  

Response

{
"searchMetaData": {...},
"response": {...},
"facets":
{
{
    "multilevel": {
        "list": [{
                "filterField": "productType",
                "level": 3,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO011",
                        "name": "Wall Decor",
                        "count": 10
                    },
                    {
                        "id": "Ho012",
                        "name": "Floor Decor",
                        "count": 5
                    }
                ],
                "breadcrumb": {
                    "filterField": "productType",
                    "values": [{
                        "id": "HO",
                        "name": "Home"
                    }],
                    "child": {
                        "filterField": "productType",
                        "values": [{
                            "id": "HO001",
                            "name": "Decor"
                        }],
                        "child": {
                            "filterField": "productType",
                            "values": [{
                                "id": "HO011",
                                "name": "Wall Decor"
                            }],
                            "level": 3
                        },
                        "level": 2
                    },
                    "level": 1
                }
            },
            {
                "filterField": "theme",
                "level": 1,
                "id": "200",
                "displayName": "Theme",
                "position": 2,
                "values": [{
                        "id": "12",
                        "name": "Animals",
                        "count": 34
                    },
                    {
                        "id": "13",
                        "name": "Birds",
                        "count": 21
                    }
                ],
                "breadcrumb": {
                    "filterField": "theme",
                    "values": [{
                        "id": "21",
                        "name": "MNP"
                    }],
                    "child": {
                        "filterField": "theme",
                        "values": [{
                            "id": "23",
                            "name": "ZZZ"
                        }],
                        "level": 2
                    },
                    "level": 1
                }
            }
        ]
    }
}
}

Backward Compatibility

1. Response format for older implementation
In some older implementation of the multi-level facets the response format for multilevel facets is different from the response format shown above.

The response below shows backward compatible format which comprised of 2 components: “bucket” and “breadcrumb”.

{
"searchMetaData": {...},
"response": {...},
"facets":
{
    "multilevel": {
        "bucket": [{
            "values": [{
                    "id": "FA0283",
                    "name": "Dresses",
                    "count": 28
                },
                {
                    "id": "FA0053",
                    "name": "Tops",
                    "count": 1
                }
            ],
            "position": 1,
            "displayName": "Category",
            "filterParam": "categoryPath3_catMap",
            "level": 3,
            "multiLevelField": "categoryPath"
        }],
        "breadcrumb": {
            "filterField": "u_categoryPathId",
            "values": [{
                "id": "FA"
            }],
            "child": {
                "filterField": "u_categoryPathId",
                "values": [{
                    "id": "FA0153"
                }],
                "level": 2
            },
            "level": 1
        }
}

Note: For some older implementations, the search API needed an additional parameter “facet.multilevel” to return the relevant multilevel facets.

https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2&filter=productType:“Dresses”&facet.multilevel=true  
2. When field-ID is used instead of field-name
The ‘path’ field ‘productType’ can be defined in the following two ways:
-When id NOT present in the schema (regular implementation)
Sample schema:
{
    "fieldName": "productType",
    "dataType": "path ",
    "multiValue ": true,
    "autoSuggest ": false,
    "isVariant ": true
}
Sample value in the product catalog:
    "productType": [
        Electronics > Accessories > Computer & Tablet accessories > Cases & Bags,
        Home > Luggage & Travel Accessories > Travel Accessories
    ]

- When id is present in the schema (older implementation)
Sample schema:
{
    "fieldName": "productType",
    "dataType": "path",
    "multiValue": true,
    "autoSuggest ": false,
    "isVariant ": true
}
Sample value in the product catalog:
    "productType": [
    "EC|Electronics>EC0498|Accessories>EC0504|Computer & Tablet accessories>EC0531|Cases & Bags",
    "HO|Home>HO0235|Luggage & Travel Accessories>HO0246|Travel Accessories"
]
In this implementation, the Field-id can be used in the search API instead of field name to apply facets:
&filter-id=<field-id>:<field-value-id>
Eg, &filter-id=100:”HO>HO0235>HO0246”  
Here is the API when the filter-id is used to select items from "HO | Home>HO001 | Decor>HO011| Wall Decor":
https://search.unbxd.io/<apikey>/<sitekey>/search?q=<query>&version=V2&filter-id=100:"HO>HO001>HO011"  
Generic Syntax : &filter-id=: where ‘field-id’ is the ‘id’ assigned to the field in the schema
Response
{
"searchMetaData": {...},
"response": {...},
"facets":
{
    "multilevel": {
        "list": [{
                "filterField": "productType",
                "level": 3,
                "id": "100",
                "displayName": "Product Type",
                "position": 1,
                "values": [{
                        "id": "HO011",
                        "name": "Wall Decor",
                        "count": 10
                    },
                    {
                        "id": "Ho012",
                        "name": "Floor Decor",
                        "count": 5
                    }
                ],
                "breadcrumb": {
                    "filterField": "productType",
                    "values": [{
                        "id": "HO",
                        "name": "Home"
                    }],
                    "child": {
                        "filterField": "productType",
                        "values": [{
                            "id": "HO001",
                            "name": "Decor"
                        }],
                        "child": {
                            "filterField": "productType",
                            "values": [{
                                "id": "HO011",
                                "name": "Wall Decor"
                            }],
                            "level": 3
                        },
                        "level": 2
                    },
                    "level": 1
                }
            },
            {
                "filterField": "theme",
                "level": 1,
                "id": "200",
                "displayName": "Theme",
                "position": 2,
                "values": [{
                        "id": "12",
                        "name": "Animals",
                        "count": 34
                    },
                    {
                        "id": "13",
                        "name": "Birds",
                        "count": 21
                    }
                ],
                "breadcrumb": {
                    "filterField": "theme",
                    "values": [{
                        "id": "21",
                        "name": "MNP"
                    }],
                    "child": {
                        "filterField": "theme",
                        "values": [{
                            "id": "23",
                            "name": "ZZZ"
                        }],
                        "level": 2
                    },
                    "level": 1
                }
            }
        ]
    }
}
}