Docs

Browse API

Overview

The Browse API lets you interact with the Unbxd platform and implement all category related functionality with ease. The API can customize your page experience by leveraging various built-in features of Browse. You can also power any type of page using this API, such as, Category, Brand, or any other attribute.This API can communicate over HTTP and HTTPS.

Authentication

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

Request Parameters

A standard Browse API call will have the following format:

https://search.unbxd.io/<API-KEY>/<SITE-KEY>/category?p=<page>&version=V2  
&pagetype=boolean&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
pIdentifier of page being requested as Names.At least one of these parameters should be present.n/a
p-idIdentifier of page being requested as IDs.At least one of these parameters should be present.n/a
pagetypeType of the page being requested.Yesn/a
API KeyAPI Key.Yesn/a
Site KeySite Key.Yesn/a
versionVersion of the API.NoV1
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 detail below.Notrue
facet.multilevelEnables or disables displaying multi-level facets in response.Non/a
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)
category-filter-idRestrict the products based on category (using path comprised of category ID). Used only for multilevel-facets.Non/a (no filter will be applied)
category-filterRestrict the products based on category (using path comprised of category name). Used only for multilevel-facets. Non/a (no filter will be applied)
sortRank products based on criteria passed.Non/a (default rank would be based on Unbxd relevancy)
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 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

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 category hierarchy where the results lie.
selectedFilters which are selected in the UI.
bannerBanner response for the page.

Parameter details

A sample request is shown below:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:"Fashion>Shoes"&pagetype=boolean&rows=1&version=V2  

p-id

Identifier of the page being requested as IDs. It is an optional parameter and has the following form p-id=field-id:value-id.

For category page, field-id is “categoryPathId” and value-id is the corresponding category path comprised of category IDs. Example, p-id=categoryPathId:”J>J00157>J00158”.

For any other page, field-id is corresponding field ID as passed in the feed and value-id is the corresponding value ID. Example, p-id=1:9357, p-id=12224:18010.

p

Identifier of the page being requested as Names. It is an optional parameter and has the following form p=fieldname:”fieldvalue”.

For category page, fieldname is “categoryPath” and fieldvalue is the corresponding category path comprised of category names. Example, p=categoryPath:”Jewelery>Necklaces>Beaded Necklaces”.

For any other page, fieldname is corresponding field as passed in the feed and fieldvalue is the corresponding value. Example, p=Brand:”Nike”, p=Events:”40 Years of Innovation”

IMPORTANT:

  • It is mandatory to pass either “p” or “p-id”. If both are passed together, “p” would be ignored and results would be shown as per “p-id”.
  • The value passed under “p-id” (or “p”) is displayed in the Console and reports as-it-is.

IMPORTANT: In the tracker api, the following parameters need to be passed:

  • page: Pass the exact value as passed under “p-id” (or “p”).
  • page_type: Always pass “BOOLEAN”.

Example,

Unbxd Category APIUnbxd Tracker API
https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p-id=categoryPathId:%22FA%3EFA0484%22&pagetype=boolean&version=V2https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"categoryPathId:\"FA>FA0484\"","page_type":"BOOLEAN","url":"https://www.example.com/shop/jeans/fa0173","referrer":"","visit_type":"repeat","ver":"2.16.16","event_timestamp":1506514262120,"domain":".example.com","_uf":2771417494,"ABCode":"9","visitId":"visitId-1506513264549-17911","domEvent":false}&UnbxdKey=docs-unbxd700181508846765&action=categoryPage&uid=uid-1495055696458-50129&t=1506514262128|0.87185566634374
https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:"Fashion>Shoes"&pagetype=boolean&version=V2https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"categoryPath:\"Fashion>Shoes\"","page_type":"BOOLEAN","url":"https://www.example.com/shop/jeans/fa0173","referrer":"","visit_type":"repeat","ver":"2.16.16","event_timestamp":1506514262120,"domain":".example.com","_uf":2771417494,"ABCode":"9","visitId":"visitId-1506513264549-17911","domEvent":false}&UnbxdKey=docs-unbxd700181508846765&action=categoryPage&uid=uid-1495055696458-50129&t=1506514262128|0.87185566634374
https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p-id=76678:5001&pagetype=boolean&version=V2https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"76678:5001","page_type":"BOOLEAN","url":"https://www.example.com/shop/ralph laurena/76678","referrer":"","visit_type":"repeat","ver":"2.16.16","event_timestamp":1506513821736,"domain":".example.com","_uf":2771417494,"ABCode":"9","visitId":"visitId-1506513264549-17911","domEvent":false}&UnbxdKey=docs-unbxd700181508846765&action=categoryPage&uid=uid-1495055696458-50129&t=1506513821745|0.04864827241894698
https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=vColor:"Black"&pagetype=boolean&version=V2https://tracker.unbxdapi.com/v2/1p.jpg?data={"page":"Brand:\"G by GIULIANA\"","page_type":"BOOLEAN","url":"https://www.example.com/shop/ralph lauren/76678","referrer":"","visit_type":"repeat","ver":"2.16.16","event_timestamp":1506513821736,"domain":".example.com","_uf":2771417494,"ABCode":"9","visitId":"visitId-1506513264549-17911","domEvent":false}&UnbxdKey=docs-unbxd700181508846765&action=categoryPage&uid=uid-1495055696458-50129&t=1506513821745|0.04864827241894698

Note: The values passed in the API should be encoded, when required, for correct interpretation.

If you have a categorypath containing “&”, you will need to encode it in the request.

Example,
“Fashion>Shoes>Sneakers & Athletic shoes” will be encoded to“Fashion%3EShoes%3ESneakers%20%26%20Athletic%20shoes”

pagetype

The pagetype is a mandatory parameter and has the value “boolean”.

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/category?p=categoryPath:%22Fashion%22&pagetype=boolean&format=json&version=V2  

Sample XML request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&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/category?p=categoryPath:%22Fashion%22&pagetype=boolean&start=40&version=V2  

rows

The row parameter is used to paginate the results of listing in a category page. 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/category?p=categoryPath:%22Fashion%22&pagetype=boolean&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.
https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&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/category?p=categoryPath:%22Fashion%22&pagetype=boolean&rows=20&variants.count=2&variants=true&version=V2  

API request to get all variants per product:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&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 the parameter is not applied, all the fields will be returned in the response by default.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&fields=product_name&version=V2  

facet

Facets are the filters in the UI that allow visitors to narrow down result set based on product fields. It is usually known as Layered Navigation or Guided Navigation.

Facets can be of three types:

  1. Multi-level: Facets on Categories. For a given API response, multi-level facets would represent the top-most categories those products lie under.
  2. Text: Facets on text fields in the feed. For example, color, brand, etc.
  3. Range: Facets on numeric fields in the feed. For example, price, discount, etc.

Facets can be easily configured from the Manage -> Category Pages -> Configure Facet section of the Console. It is an optional parameter and if not passed, all facets will be returned in the response.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&facet=false&version=V2  

facet.multiselect

This feature enable or disables the option to select multiple values within a facet or across facets for visitors. For example, for a category “Fashion”, facets on gender and size fields are displayed. If the value for facet.multiselect is set as true and if a visitor selects Women in the Gender facet, the category page results will be refined according to the selection. However, all values in the gender facet will still be sent in the response as if the gender filter isn’t applied (and other filters are applied, if any). Multi-select faceting is based on filter operations, i.e. AND and OR which are explained in the next section.

If one is using name-id relationship in the feed, for facet multiselect to work, filter should be on the id itself.
This feature is disabled by default. To enable the feature, set the value as ‘true’.

Sample request:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&facet.multiselect=true&version=V2  

facet.multilevel

The facet.multilevel parameter is used to enable multi-level facets in the API response. It takes a fixed value “categoryPath” if you want multi-level facets in the response. If not passed, multi-level facets will not appear in the response.

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&facet.multilevel=categoryPath&version=V2  

Breadcrumb

The breadcrumb parameter gives the position within category hierarchy where the results appear. For example, if the visitor opens the category page for “Fashion>Women's Apparel>Jeans”, the breadcrumb would be:

Sample response:

{
    "breadcrumb": {
        "filterField": "Category1_fq",
        "values": [{
            "id": "Fashion"
        }],
        "child": {
            "filterField": "Category2_fq",
            "values": [{
                "id": "Women's Apparel"
            }],
            "child": {
                "filterField": "Category3_fq",
                "values": [{
                    "id": "Jeans"
                }],
                "level": 3
            },
            "level": 2
        },
        "level": 1
    }
}

selectedfacet

The selectedfacet parameter enables or disables Selected Facets block in the API response.

Sample request:

The possible values are “true” or “false”. Default value is “false”.

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter-id=76678:5001&selectedfacet=true&version=V2  

Selected

Sample response:

This section mentions the field name, field id, value name, value id combination of the filters selected in the UI.

{
    "selected": [{
            "facetName": "u_5110_unbxdMap",
            "displayName": "Color",
            "values": [
                "5335"
            ],
            "id": "5110",
            "position": 785,
            "filterField": "ShopbyColor_uFilter"
        },
        {
            "facetName": "u_2707_unbxdMap",
            "displayName": "Price",
            "values": [
                "6666"
            ],
            "id": "2707",
            "position": 784,
            "filterField": "ShopbyPrice_uFilter"
        }
    ]
}

Facets

Once you have correctly configured your facets, the Browse API call will return facets as a part of the catalog-based response.

To know more about how Unbxd powers facets in the Browse API, please refer to the Facets documentation.

Facets Response

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).

Multilevel facets are controlled using the “facet.multilevel” request parameter as mentioned above.

Text and Range facets are sent only when the corresponding facet is configured in the Console.

  • displayName: Name of the facet to be displayed on the website.
  • position: Numerical order of facets in ascending order.

For example, if you have configured facets on color, brand and price, when a visitor reaches particular category page, the facet response in JSON format will look like:

Sample response:

{
    "facets": {
        "multilevel": {
            "bucket": [{
                "values": [{
                        "id": "FA",
                        "name": "Fashion",
                        "count": 3904
                    },
                    {
                        "id": "HF",
                        "name": "Health & Wellness",
                        "count": 55
                    }
                ],
                "position": 1,
                "displayName": "Category",
                "filterParam": "categoryPath1_fq",
                "level": 1,
                "multiLevelField": "categoryPath"
            }],
            "breadcrumb": {}
        },
        "text": {
            "list": [{
                    "facetName": "u_1_unbxdMap",
                    "filterField": "Brand_uFilter",
                    "id": "1",
                    "values": [{
                            "name": "Steve Madden",
                            "count": 288,
                            "id": "107"
                        },
                        {
                            "name": "Vince Camuto",
                            "count": 228,
                            "id": "4064"
                        }
                    ],
                    "displayName": "Brand",
                    "position": 783
                },
                {
                    "facetName": "u_5110_unbxdMap",
                    "filterField": "ShopbyColor_uFilter",
                    "id": "5110",
                    "values": [{
                            "name": "Black",
                            "count": 2174,
                            "id": "5335"
                        },
                        {
                            "name": "Blue",
                            "count": 1075,
                            "id": "5336"
                        }
],
                    "displayName": "Color",
                    "position": 785
                }
            ]
        }
    }
}

Filtering

If IDs are present in the feed, filtering should be done on IDs only. Results of the API can be filtered by passing the required criteria as request parameters. The criteria can be passed in two ways, either using field IDs or field names.

Three types of filters are supported:

  • text
  • range
  • multilevel

text

The text filter is used to filter products based on fields with string values such as color, gender, brand, etc. It can be defined in the API call in two ways:

1. Using Field IDs

“filter-id” is used to filter the results using field-id. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a facet is selected in the UI, the corresponding filter is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter-id=field-id:value-id&version=V2  

The value of the parameter should be a field-id and value-id separated by a colon, where:

  • field-id: The id of the field on which the text filter is applied.
  • value-id: The id of the value on which the results are filtered.

Sample request:

For example, a visitor arrived on “Fashion” category page . To return only ”black dresses” in the response, the API call below is made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter-id=76678:5001&version=V2  

2. Using Field Names

“filter” is used to filter the results using field names. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a facet is selected in the UI, the corresponding filter is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter=fieldname_uFilter:"value"&version=V2  

The value of the parameter should be a fieldname and value separated by a colon, where:

  • fieldname: The field on which the text filter is applied.
  • value: The value of the field on which the results are filtered. You must use double quotes for the value parameter.

Sample request:

For example, a visitor arrived on “Fashion” category page . To return only ”black dresses” in the response, the API call below is made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter=vColor:%22Black%22&version=V2  

range

The range filter is used to filter products based on fields with dataypes - date, number or decimal. It can also be defined in the API in two ways:

1. Using Field IDs

“filter-id” is used to filter the results using field-id. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a facet is selected in the UI, the corresponding filter is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter-id=field-id:[lowerlimit-id TO upperlimit-id]&version=V2  

The value of the parameter should be a field-id and range separated by a colon, where:

  • field-id: The id of the field on which the text filter is applied.
  • lowerlimit-id: The id of the lower limit of the range.
  • upperlimit-id: The id of the upper limit of the range.

Note: Here, the range is specified within square brackets [ ], inclusive of both lower limit and upper limit.

2. Using Field Names

“filter” is used to filter the results using field names. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a facet is selected in the UI, the corresponding filter is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter=fieldname:[lowerlimit TO upperlimit]&version=V2  

The value of the parameter should be a fieldname and range separated by a colon, where:

  • fieldname: The field on which the text filter is applied.
  • lowerlimit: The lower limit of the range
  • upperlimit: The upper limit of the range

Note: Here, the range is specified within square brackets [ ], inclusive of both lower limit and upper limit.

multilevel

The multilevel filter is used to filter products based on categories. It can be defined in the API call in two ways:

1. Using Field IDs

“category-filter-id” is used to filter the results using category path comprised of category IDs. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a multilevel facet is selected in the UI, the corresponding category-filter-id is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&category-filter-id=<categoryIDPath>&version=V2  

The value of the parameter should be a categoryIDPath, where:

  • categoryIDPath: The category path comprises of category ids on which the multilevel filter is applied.

Sample request:

For example, if a visitor arrived on “Black” page and applies a multilevel filter on “Shirts” category, the following API call would need to be made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=vColor:"Black"&pagetype=boolean&category-filter-id=FA>FA0485&version=V2  

2. Using Field Names

“category-filter” is used to filter the results using category path comprised of category names. It is an optional parameter. If passed, it eliminates those products that do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a multilevel facet is selected in the UI, the corresponding category-filter-id is sent in the request.

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&category-filter=<categoryPath>&version=V2  

The value of the parameter should be a categoryPath, where:

  • categoryPath: The category path comprises of category names on which the multilevel filter is applied.

Sample request:

For example, if a visitor arrived on “Black” page and applies a multilevel filter on “Shirts” category, the following API call would need to be made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=vColor:"Black"&pagetype=boolean&category-filter=Fashion>Shirts&version=V2  

IMPORTANT: If categoryPath is passed under “p” parameter, the multilevel filters are calculated using that value. Hence in that case, passing “category-filter-id” or “category-filter” isn’t explicitly required.

Example, p=categoryPath:”Jewelry>Necklaces>Beaded Necklaces”&pagetype=boolean will return multilevel facets for the categoryPath passed under “p”

However, if “category-filter-id” and/or “category-filter” is passed along with “categoryPath” under “p” parameter, then all the values are considered and the final result is accordingly.

Example,

p=categoryPath:"Jewelry>Necklaces"&pagetype=boolean&category-filter-id=J>J00156>J00234&category-filter=Jewelry>Necklaces>Diamond

Multiple Filters

Multiple facets can be selected which applies corresponding filters in a single API call.
Since faceting works on filters, you can apply multiple filters in a single API call only when facets are configured from the dashboard and multi-select faceting is enabled ie. facet.multiselect=true.

There are two types of filter operations:

  • AND
  • OR

AND Operation

To perform an AND filter operation, you need to add individual filters separated with an “&” operator in the API request as shown below:

1. Using Field IDs

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter-id=field1-id:fieldvalue-id&filter-id=field2-id:fieldvalue-id&facet.multiselect=true&version=V2  
  • field1-id: The id of the field on which the first filter is applied.
  • field2-id: The id of the field on which the second filter is applied.

For example, a visitor wants to see results filtered on both color and price, the API call below must be made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter-id=76678:5001&filter-id=76678:4003&facet.multiselect=true&version=V2  

2. Using Field Names

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&filter=field1_uFilter:"fieldvalue"&filter=field2_uFilter:"fieldvalue"&facet.multiselect=true&version=V2  
  • field1: The field on which the first filter is applied.
  • field2: The field on which the second filter is applied.

For example, a visitor wants to see results filtered on both color and price, the API call below must be made:

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter=vColor_uFilter:%22Black%22&filter=vPrice:[0 TO 100]&facet.multiselect=true&version=V2  

OR Operation

To perform an OR filter operation, you need to add individual filters separated with OR operator in the API call as shown below:

1. Using Field IDs

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&filter-id=(field1-id:fieldvalue-id OR field1-id:fieldvalue-id)&facet.multiselect=true&version=V2  

Notes:

  • There is a space before and after the OR operator in the API call.
  • Same field should be passed within a single filter condition, example, filter-id=(field1-id:fieldvalue-id OR field1-id:fieldvalue-id) is valid while filter-id=(field1-id:fieldvalue-id OR field2-id:fieldvalue-id) is not valid.

For example, if a visitor wants to see results filtered on more than one color, the API call below is made:

https://search.unbxd.io/90a674215bffc3f7d99bea32cdb4f58e/home-unbxd-com700181506870085/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter-id=(76678:5001%20OR%2076678:5021)&facet.multiselect=true&version=V2  

2. Using Field Names

https://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&filter=(field1_fq:"fieldvalue" OR field2:"fieldvalue")&facet.multiselect=true&version=V2  

Note: There is a space before and after the OR operator in the API call.

For example, a visitor wants to see results filtered on more than one color, the API call below is made:

http://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&filter=(vColor_uFilter:%22Black%22%20OR%20vColor_uFilter:%22Brown%22)&facet.multiselect=true&version=V2  

Sorting

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 category page API results using a sort function as shown below:

http://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&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:

http://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&sort=price%20asc&version=V2  

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:

http://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&verison=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:

http://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/category?p=categoryPath:%22Fashion%22&pagetype=boolean&sort=price%20asc&sort=title%20desc&version=V2  

Banners

Banners can be easily configured from your dashboard during campaign creation. Once you have correctly configured your banner, the category page 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:

http://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&banner=false&version=V2  

Banners 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 arrived on a particular category page .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 page hit for analytics. By default, tracking is enabled. To disable tracking, set value to false.

http://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&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:

http://search.unbxd.io/<api-key>/<site-key>/category?p=<page>&pagetype=boolean&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"