Docs

Introduction

RESTful APIs provide the best way to communicate with our platforms and let you to perform all the necessary actions for building an efficient site search for your ecommerce site or app.

This section describes the API requests for each operation in detail for you to integrate correctly.

Feed Upload API

Once your dashboard is set up, you are now ready to upload your first Product Feed. All Unbxd algorithms work around the Product Feed which must be uploaded in a specific format.

Learn how to create a Product Feed

Once you have formatted your Product Feed, you can upload it in two ways.

  1. Full Feed Upload
  2. Incremental Upload

Full Feed Upload

A Full Feed Upload will completely replace any existing Product Feed with the current upload. This type of upload is mainly preferred for initial uploads. You can do a full feed upload even when you have many untracked updates in your feed file.

Request Format

curl -F "file=@yourfile" 'http://feed.unbxdapi.com/upload/v2/yoursecretkey/yoursitekey?fullimport=true'  
  • yourfile: The file path of the Product Feed in your server.
  • Secret Key: Your Secret Key.
  • Site Key: Your Site Key.
Example:

A sample Full Feed Upload request for a site is given below:

curl -F "file=@\Program Files\MSSQL13.77MSID\" 'http://feed.unbxdapi.com/upload/v2/aa68ef948ca3c56ca2eb34fd8fcc7e8c/myecommercesite_com-u1446615164623?fullimport=true'  

Response Format

The response format in JSON is given below:

{
  "statusCode" : 200,
  "message" : "File has been processed successfully.",
  "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
  "unknownSchemaFields" : [ ],
  "fieldErrors" : [ ],
  "rowNum" : null,
  "colNum" : null,
  "integrationStep" : false
}
Response Keys

The API response will give you processing status and message about the request call. The following details are included in the response:

statusCode Status message
message Message describing the processing status
unbxdFileName Name of the uploaded file
unknownSchemaFields Fields that have not been defined in the schema
fieldErrors Detailed list of fields with validation errors that occurred at a field level. This consists of fieldName, fieldValue, dataType, and multiValue.
fieldName Name of the field
fieldValueThe value of the field that shows validation error
dataTypeThe datatype defined for the field
multiValueIdentifies if the field is single-valued or multi-valued
rowNum Line number of the file which indicates fielderror validation failure
colNum Column number of the file which indicates fielderror validation failure
integrationStep 'false'. (default)
status Processing status
UploadID() Id for the upload request. Only in SDK implementation.
taxonomyStatus FALSE. (This is set to TRUE when you are uploading your taxonomy data).
Sample Responses

Here are some sample Feed responses in JSON format which might help you understand the upload response.

Upload Success

Every successful upload will look like this:

{
  "statusCode" : 200,
  "message" : "File has been processed successfully.",
  "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
  "unknownSchemaFields" : [ ],
  "fieldErrors" : [ ],
  "rowNum" : null,
  "colNum" : null,
  "integrationStep" : false
}    
Incorrect field value

You uploaded your Product feed, wherein the value of the field qty is incorrect, the feed API response will look like this:

{
  "statusCode" : 401,
  "message" : "Validation failed for the uploaded file.",
  "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
  "unknownSchemaFields" : [ ],
  "fieldErrors" : [ {
    "fieldName" : "qty",
    "fieldValue" : [ "ten" ],
    "dataType" : "number",
    "multiValue" : "false",
    "errorCode" : 402,
    "message" : "Expect single value data for this field."
    "rowNum" : "207",
    "colNum" : "22"
  } ],
  "rowNum" : null,
  "colNum" : null,
  "integrationStep" : false
}
Undefined Fields in the Schema

The uploaded feed data has two fields namely, categories and meta_title that do not have a schema. The feed API response will look like this:

{
        "statusCode" : 602,
        "message" : "Your data does not have schema for some of the fields.",
        "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
        "unknownSchemaFields" : [ "categories", "meta_title" ],
        "fieldErrors" : [ ],
        "rowNum" : null,
        "colNum" : null,
        "integrationStep" : false
}
Different Field Name

You uploaded your feed data in which one of the fields, namely count was supposed to be number as per the schema, since the value was decimal.

{
        "statusCode" : 401,
        "message" : "Validation failed for the uploaded file.",
        "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
        "unknownSchemaFields" : [ ],
        "fieldErrors" : [ {
                "fieldName" : "count",
                "fieldValue" : "10",
                "dataType" : "number",
                " multiValue" : "false",
                "errorCode" : 402,
                "message" : "Expected value# number.",
                "rowNum" : "77",
                "colNum" : "15"
        } ],
        "rowNum" : null,
        "colNum" : null,
        "integrationStep" : false
}
Missing Tags

You uploaded your feed data where one of the JSON tags namely, count has a missing closing tag.

{
        "statusCode" : 401,
        "message": "ParseError at [row,col]:[77,9]\nMessage: The element type \"count\" must be terminated by the matching end-tag \"</count>\".",
        "unbxdFileName" : "9e07024c-e328-45ea-9374-874648371c58.json",
        "unknownSchemaFields" : [ ],
        "fieldErrors" : [ ],
        "rowNum" : "77",
        "colNum" : "9",
        "integrationStep" : false
}

Incremental Upload

You can also upload your first Product feed incrementally by performing a series of operations followed by an API call.

Feed Operations

There are 3 Feed Operations which can be performed on your existing Product Feed with Unbxd:

  1. Adding a Product.
  2. Updating a Field Value
  3. Deleting a Product

NOTE

You can perform multiple operations in single incremental upload.

Adding a Product

This operation is used for adding a new product or replacing an existing product. If any new field has been added, it should be defined in the schema. The operation will fail otherwise.

You can add products as shown below:

<?xml version="1.0" encoding="UTF-8"?>  
    <feed>
        <catalog>
            <schema>
             <fieldName>value</fieldName>
             <dataType>value</dataType>
             <multiValued>value</multiValued>
             <autoSuggest>value</autoSuggest>
             </schema>
               <add>
                    <items>
                         <uniqueId>uniqueid1</uniqueId>
                         <field1>value</field1>
                         <field2>value</field2>
                         <field3>value</field3>
                         <field4>value</field4>
                     </items>
                     <items>
                          <uniqueId>uniqueid2</uniqueId>
                          <field1>value</field1>
                          <field2>value</field2>
                          <field3>value</field3>
                          <field4>value</field4>
                     </items>
                </add>
           </catalog>
     </feed>
Example:

To add a product with uniqueId71, the feed file should look like this:

<?xml version="1.0" encoding="UTF-8"?>  
<feed>  
   <catalog>
      <schema>
         <fieldName>occasion</fieldName>
         <dataType>text</dataType>
         <multiValued>true</multiValued>
         <autoSuggest>false</autoSuggest>
      </schema>
      <add>      
        <items>
            <uniqueId>71</uniqueId>
            <title>Amzer iPhone Cases</title>
            <brand>Amzer</brand>
            <sku>SKU711</sku>
            <occasion>Casual</occasion>
        </items>
      </add>
   </catalog>
</feed>  

Here a new field "occasion" is added to the schema along with the new products.

See a sample JSON feed.

Updating a Field Value

This operation is used to update a field value of an existing field. This operation is mainly used for price and quantity fields.

You can update field values products as shown below:

<?xml version="1.0" encoding="UTF-8"?>  
     <feed>
        <catalog>
           <update>
                <items>
              <uniqueId>value</uniqueId>
              <field>value</field>
                </items>
           </update>
        </catalog>
     </feed>
Example:

To update the qty field, the feed file should look like this:

<?xml version="1.0" encoding="UTF-8"?>  
     <feed>
        <catalog>
           <update>
                <items>
              <uniqueId>53115</uniqueId>
              <qty>20</qty>
                </items>
           </update>
        </catalog>
     </feed>

IMPORTANT

Ensure the updated field value agrees with the previously defined schema.

Deleting a Product

This operation is used for deleting an existing product. You can delete a product using only its uniqueId as shown below:

<?xml version="1.0" encoding="UTF-8"?>  
     <feed>
          <catalog>
               <delete>
                    <items>
                         <uniqueId>uniqueid1</uniqueId>
                    </items>
                    <items>
                          <uniqueId>uniqueid2</uniqueId>
                    </items>
               </delete>
           </catalog>
     </feed>
Example:

To delete a product with uniqueId 53115, the feed file should look like this:

<?xml version="1.0" encoding="UTF-8"?>  
     <feed>
          <catalog>
               <delete>
                   <items>
                       <uniqueId>53115</uniqueId>
                     </items>
               </delete>
           </catalog>
     </feed>

See a sample JSON feed.

Request Format

The API request for an Incremental Upload is given below:

curl -F "file=@yourfile" 'http://feed.unbxdapi.com/upload/v2/yoursecretkey/yoursitekey'
  • yourfile: The file path of the Product Feed in your server.
  • Secret Key: Your Secret Key.
  • Site Key: Your Site Key.

Integrating analytics

After you have successfully uploaded your Product Feed, your next step is to integrate Unbxd Analytics in your eCommerce website. Unbxd provides dedicated event tracking calls for each visitor event.

NOTE

Unbxd Analytics can also be integrated using HTML meta tags. Learn how to integrate Unbxd Analytics using HTML metatags.

Prerequisite

Before you start making the event calls, it is mandatory that you insert a JavaScript code snippet in the header section of all the pages in your website.

This JavaScript code acts as an event listener which identifies and records events tracked through the event trackers.

JavaScript code

<script type="text/javascript">  
  /* * * CONFIGURATION * * */
  var UnbxdSiteName = "<Site Key>";
  /* * * DON'T EDIT BELOW THIS LINE * * */
  (function() {
  var ubx = document.createElement('script'); ubx.type = 'text/javascript'; ubx.async = true;
  ubx.src = '//d21gpk1vhmjuf5.cloudfront.net/unbxdAnalytics.js';
  (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(ubx);
  })();
</script>  
  • Site Key: Your Site Key.

IMPORTANT

The JavaScript code needs to be inserted only once in a page.

Tracking an event

After you have successfully inserted the JavaScript code in all the pages, you would now need to configure event trackers across your website. These trackers are event-triggered API calls made to Unbxd servers to track and record different visitor events.

The API calls must be in the form of an HTTP GET request to the below URL:

tracker.unbxdapi.com/v2/1p.jpg  

Request format:

Unbxd.track(type,params)  

  • type: Name of the event. This parameter can have the following values: search, click, addToCart, and order.
  • params: The event parameters. This parameter should have values in Key-Value format.

Refer the table below to input the correct Key Values:

KeyDescription
queryThe search query
pidUniqueID or skuID of the product
prankRank/Position of the product in a page
qtyNumber of products ordered
pricePrice of the product

IMPORTANT

If your catalog contains variants, the pid must not be replaced with the variant ID.

Tracking a search event

The below API call needs to be made whenever a visitor searches on your site's search box:

Unbxd.track("search", {"query":"VALUE"})  

Example:

A visitor searched for 'iphone cases', the tracking API request will look like this:

Unbxd.track("search", {"query":"iphone cases"})  

Know more about the Search event.

Tracking product clicks:

The below API call needs to be made for every product click on your website:

Unbxd.track("click",{"pid":"VALUE", "prank":" VALUE"})  

Example:

A visitor clicked on 'Spigen Silicone Bumper Back Cover', the tracking API request will look like this:

Unbxd.track("click",{"pid":"SPSIBBC71","prank":"3"});  

Know more about the Product Click event.

Tracking Cart additions

The below API call needs to be made for every cart additions.

Unbxd.track("addToCart", {“pid”: " VALUE"})  

Example:

A visitor added a product Spigen Silicone Bumper Back Cover to the cart, the tracking API request will look like this:

Unbxd.track("addToCart", {"pid":"SPSIBBC71"})  

Know more about the Cart Addition event.

Tracking Orders

The below API call needs to be made for every successful order:

Unbxd.track("order",{"pid": " VALUE ","qty": VALUE,"price": " VALUE"})  
Example:

A visitor ordered Spigen Silicone Bumper Back Cover, the tracking API request will look like this:

Unbxd.track("order",{"pid":"SPSIBBC71","qty":"1","price":"450"})  

NOTE

price and qty field values can be passed with or without double quotes. However, it is strongly recommended that the price value is within double quotes to avoid any value round offs.

Know more about the Order Event.

Tracking Product Page Views

Product Page Views is used to specify the total number visits to the "product detail page" of a product. To track "product page views" configure the below code in your ecommerce store.

Unbxd.track('product_view', {pid : pid})  
  • pid - uniqueId of the product (type String)
Example:

For a visitor on a product page of a product Spigen Silicone Bumper Back Cover the tracking API request will look like this:

Unbxd.track('product_view', {pid : 10021})  

Know more about the Product Page Views Event.

Tracking Dwell Time

Dwell time specifies the visitor's duration of stay on a particular product detail page. To track dwell time for a particular product configure the below code in your store:

Unbxd.track(‘dwellTime', {pid : pid, dwellTime : dwellTime})  
  • pid - uniqueId of the product (type String)
  • dwellTime - time spent on the product description page (type long)

Know more about the Dwell Time Event.

Tracking Facets

At Unbxd, the more data we capture, more relevant the results would be. That is why tracking facet interaction on a result page becomes essential for building a comprehensive profile for a visitor that helps in fetching relevant results.

To track the facets on the results listing page configure the following code as instructed:

Unbxd.track('facets', {query : <query>, facets : <facets>})  

Know more about the Facets Event.

Tracking Cart Removal

Like "Cart Additions", tracking "cart removal" is also important as it helps us better understand the visitor's field preferences. Configure the following code as instructed to track when visitors remove a product from her/his cart.

To track the facets on the results listing page configure the following code as instructed:

Unbxd.track('cartRemoval', {pid : <pid>, qty : <qty>})  
The above code must be configured for all "cart removal" buttons on the cart page. For example,
Unbxd.track('cartRemoval', {pid : S0012, qty : 1})  


Know more about the Cart Removal Event.

Tracking Search Impressions

Search impressions refer to the event when search results are loaded on a page. This event is tracked to track the different products loaded for a search query. In case of an infinite scroll, search impression will be tracked on every page scroll.

Unbxd.track('search_impression', {query : query, pids_list : pids_list})  

Know more about the Search Impression Event.

Search API

Overview

Unbxd provides RESTful API for Site Search. You can consume the JSON / XML response of this API and customize the search experience on your site by leveraging various built-in features of Unbxd Search. This API can communicate over HTTP and HTTPS.

Authentication Keys

Search API should be authenticated using API Key and Site Key. These keys are generated at the time of account creation and can be accessed from the Manage section of the console.

Learn more about authentication keys.

Headers

We recommend passing certain parameters as HTTP/HTTPS headers to enable personalisation, segmentation, and A/B testing of merchandising campaigns. These are:

Request HeadersDescriptionSignificance
userIdUnique identification for visitors. Refer the sample userId, uid-1466015353887-20419. The Unbxd Analytics JavaScript code generates the "userId" in your browser cookie.Personalisation, segmentation, and campaign AB testing will be affected if this is not passed.
userAgentThe browser identification information passed to the web server with every HTTP request.Device based merchandising campaigns will be affected if this is not passed.
Accept-EncodingThis signifies the content encoding of the response. Currently, we supports only "gzip" compression. To enable this, ‘gzip’ needs to be passed.The response will not be compressed if this is not passed.

API Syntax

A basic search request has the following format:

http://search.unbxdapi.com/<API_key>/<Site_key>/search?q=<query string>&start=<start_no>&rows=<page_size>&filter=<filter_query>&sort=<sort field>asc|desc&uid=<uid>&<fields=comma separated list of fields>  

Request Parameter

ParameterDescriptionMandatoryDefault value
qsearch query stringYes
API_keyAPI key.Yes
Site_KeySite keyYes
formatFormat of the response. We support "xml" and "json" formatNojson
rowsNumber of products per page. To return 0 products in the response, set rows=0.No10
startThe offset of the first product in a result set.No0
fieldsFields returned in the response.NoAll fields
facetsUsed to show/hide facets on the results page.Notrue
filterUsed to refine products based on defined conditions.No
sortUsed to rearrange products based on defined conditions.NoRelevancy
bannerUsed to show/hide banners on the result page.Notrue
redirectUse to enable or disable the redirect response for a query. If you want to override a redirect response with search response, set "redirect=false".Notrue
spellcheck Used to enable or disable spellcheck for a query.Notrue
analytics Used to enable or disable request tracking by Unbxd Analytics.Notrue
stats Used to specify a field for which statistics should be generated.Non/a

A sample request and response is shown below:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&fields=uniqueId,title,description,imageUrl,price,color&rows=3  

Response Components

ComponentsDescription
statusResponse status code for the request. ‘0’ represents success. Non-zero represents error.
queryTimeTime taken to process the query after Unbxd receives the request. It doesn’t include network time between client end and Unbxd server.
queryParamsParameters sent as part of the request
numberOfProductsTotal number of products that matched with the query
startOffset in the complete result set of products for the query
productsAll products matched. Structure will be the same as passed in the feed.
facetsFilters which are displayed in the UI to allow visitors to narrow down result set based on product fields.
redirectRedirect response for the query.
didYouMeanspellcheck response with a query suggestion.
bannerbanner response for the query.

The response for the above request is shown below:

{
    "searchMetaData": {
        "status": 0,
        "queryTime": 10,
        "queryParams": {
            "q": "iphone cases",
            "fields": "uniqueId,title,description,imageUrl,price,color",
            "rows": "3",
            "type": "interpreter"
        }
    },
    "response": {
        "numberOfProducts": 89,
        "start": 0,
        "products": [{
                "uniqueId": "5315b8565e4016e5737be4a7",
                "description": "A zebra with attitude lends new dimension to a sturdy holographic-print case that keeps your iPhone safe from scratches. Fits iPhone 5 and 5s.Polycarbonate.By MARC BY MARC JACOBS; imported.",
                "title": "'Zebra' Lenticular iPhone 5 & 5s Case",
                "color": [
                    "Orange Multi"
                ],
                "imageUrl": [
                    "http://g.nordstromimage.com/imagegallery/store/product/Medium/1/_8493781.jpg"
                ],
                "price": 2803
            },
            {
                "uniqueId": "5315b8565e4016e5737be4a8",
                "description": "Olive the dog lends new dimension to a sturdy silicone case that keeps your iPhone safe from scratches. Fits iPhone 5 and 5s.Silicone.By MARC BY MARC JACOBS; imported.",
                "title": "'Olive' iPhone 5 & 5s Case",
                "color": [
                    "Black Multi"
                ],
                "imageUrl": [
                    "http://g.nordstromimage.com/imagegallery/store/product/Medium/5/_8467885.jpg"
                ],
                "price": 3204
            },
            {
                "uniqueId": "5315b8565e4016e5737be761",
                "description": "Crosshatched texturing and a goldtone Tory Burch logo lend visual interest to a rigid case designed to protect your iPhone from dust and scratches. Fits iPhone 5.Plastic.By Tory Burch; imported.",
                "title": "'Robinson' iPhone 5 Case",
                "color": [
                    "Black/ Gold,Carnival,Electric Purple,Ginko Leaf/ Windstrom,Luggage/ Ginko Leaf"
                ],
                "imageUrl": [
                    "http://g.nordstromimage.com/imagegallery/store/product/Medium/12/_8830332.jpg"
                ],
                "price": 4005
            }
        ]
    }
}

q

Main query parameter passed in the request. This is the search term visitor enters in the search box. It is a mandatory query parameter and should be non-empty.

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases

format

This 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:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&format=json  

Sample XML request:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&format=xml

start

This parameter is used to paginate the results from a query. It indicates the offset in the complete result set of the products. It is an optional parameter and the default value is 0.

Sample request:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&start=40  

rows

This parameter is used to paginate the results from a query. It indicates number of products in a single page. It is an optional parameter and the default value is 10.

This parameter needs to be set to 0 if products aren't required in the response.

Sample request:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&rows=20  

fields

This 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’s 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:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone 20cases&fields=uniqueId,title,description,imageUrl,price,color  

facet

Facets are filters which are displayed in the UI to allow visitors to narrow down result set based on product fields. This parameter is used to get different groups products belong to based on fields, to be displayed in the UI. It is also usually known as Layered Navigation or Guided Navigation.

The facets can be configured in the console under the Manage -> Configure Search -> Configure Facet section. It is an optional parameter and if not passed, all facets will be returned in the response.

Sample request:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone 20cases&facet=false  

facet.multiselect

This feature enable or disables the option to select multiple values within a facet or across facets for visitors

For instance, “brand” and “size” facets are displayed for a query, “shoes”. If the value for facet.multiselect is set as true and if a visitor selects Nike in the brand facet, the search results will be refined according to the selection. However, all values in the brand facet and the size facet will still be sent in the response based on the unfiltered result set to enable selecting multiple facets. Multi-select faceting is based on filter operations, i.e. AND and OR which are explained in the next section.

This feature will be disabled by default. This can be enabled by setting the value as ‘true’. Here is the sample request

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&facet.multiselect=true  

filter

This parameter is used to filter the results based on the criteria passed. It is an optional parameter and if passed, it only eliminates those products which do not match the criteria. However, it doesn’t impact the relevancy of the results. Whenever a facet is selected in the UI, corresponding filter needs to be sent in the request. There are two types of filters:

text

Text filter is used for fields with string values such as, color, gender, brand, etc. A text filter can be defined in the request as shown below:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&facet.multiselect=true  
  • fieldname: The name of the the field. Filter fields in the request are recognized by a suffix “_fq”.
  • value: The value of the field on which the results are filtered.

Sample request:

For example, for a query “iphone cases”, to return only ”gold iphone cases” in the response, the below API call is made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&filter=color_fq:"Gold"  

range

Range filter is used for fields with the following data types - date, number, or decimal. A range filter can be defined in the API call as shown below

http://search.unbxdapi.com/yourapikey/yoursitekey/search?q=query&format=value&start=value&rows=value&filter=fieldname_fq:[lowerlimit TO upperlimit]  
  • fieldname: The field on which the range filter is applied.
  • lowerlimit: The lower limit of the range
  • upperlimit: The upper limit of the range
Here, the range is specified within square brackets [ ].

Sample request:

For example, for a query “iphone cases”, to show results within a price range of $2000 to $3000, the below API call is made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&filter=price:[2000%20TO%203000]  
Filters are also utilized to power facets. Whenever a visitor selects a facet field value, appropriate filters are sent in the request.

Multiple Filters

Multiple filters can be applied in a single API call. There are two types of filter operations:

Multiple filters can only be applied if “multiple selection of facet field values is enabled” i.e. “facet.multiselect=true”.
There are two types of filter operations:

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:

http://search.unbxdapi.com/yourapikey/yoursitekey/search?q=query&filter=field1_fq:"fieldvalue"&filter=field2_fq:"fieldvalue"&facet.multiselect=true
  • field1: The field on which the first filter is applied.
  • field2: The field on which the second filter is applied.

For example, a visitor searched for iphone cases. To show results filtered on both color and brand, the below API call must be made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&filter=color_fq:%22Gold%2F%20Gold%22%20AND%20brand_fq:%22Tory%20Burch%22&facet.multiselect=true
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:

http://search.unbxdapi.com/yourapikey/yoursitekey/search?q=query&format=value&filter=(field1_fq:"fieldvalue" OR field2:"fieldvalue")&facet.multiselect=true  

NOTE

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

For example, a visitor searched for “iphone cases”. To show results filtered on more than one color, the below API call is made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&filter=color_fq:%22Black%22%20OR%20color_fq:%22Blue%20Chevron%22&facet.multiselect=true  

Sort

This parameter is used to rank the products based on specified fields in the specified order. It is optional, and if not passed, products would be returned ordered on Unbxd relevancy algorithm.

Sorting on single field

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

http://search.unbxdapi.com/yourapikey/yoursitekey/search?q=query&format=value&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 searched for “iphone cases”. To sort results on price in ascending order, the below API call is made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&sort=price%20desc

NOTE

There is a space between the sort 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.unbxdapi.com/yourapikey/yoursitekey/search?q=query&format=value&sort=field1 sort_order&sort=field2 sort_order&sort=field3 sort_order  

NOTE

When multiple sort parameters are applied, the products will be sorted based on the first criteria. 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, a visitor searched for iphone cases. To show results sorted on price and title the below API call is made:

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&sort=price%20asc&sort=title%20desc  

Banners can be configured easily from Unbxd console. 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 ‘false’. Here is the sample request.

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&banner=true  

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 the 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 Merchandising section of your console. By default, redirect is enabled for the search query if set in the console.

NOTE

Set value to false, if you want to forcefully override redirect response with search response. Here is the sample:
http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone%20cases&redirect=false  


spellcheck

This feature provides spelling suggestions or spell-check for misspelled search queries. In such cases, Unbxd’s context-aware algorithm 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, below API call needs to be made:

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

analytics

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

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

stats

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

http://search.unbxdapi.com/64a4a2592a648ac8415e13c561e44991/demosite-u1407617955968/search?&q=iphone cases&stats=price  

Response

Facets

Facets can be easily configured from the Manage -> Configure Search -> Configure Facet section of the console. Once you have correctly configured your facets, the search API call will return facets as a part of the catalog-based response.

Facet response

A typical Facet response in JSON format will look like this:

Every search call will return a JSON or XML response on your website. There are two kinds of responses for a search call:

"facets":{
       "field1_fq":{
               "type":"facet_fields",
               "values":[
                       "value1", number of products,
                       "value2", number of products,
                       "value3", number of products,
                       "value4", number of products]},
        "field_fq":{
               "type":"facet_ranges",
               "values":{
                       "counts":[
                               "rangevalue1", number of products,
                               "rangevalue2", number of products,
                               "rangevalue3", number of products,
                               "rangevalue4", number of products,
                               "rangevalue5", number of products],
                       "gap": gapvalue,
                       "start": rangevalue1,
                       "end":endvalue
                       }
               }
       }

For example, you had configured facets on color, material, style, price, and gender. When a visitor searches for iphone cases, the facet response in JSON format will look like this:

{
    "facets": {
        "category_fq": {
            "type": "facet_fields",
            "values": [
                "women", 85,
                "men", 2
            ]
        },
        "color_fq": {
            "type": "facet_fields",
            "values": [
                "Solid White", 2,
                "Black", 7,
                "Gold/ Gold", 3,
                "Multi", 3,
                "Blue Chevron", 23
            ]
        },
        "brand_fq": {
            "type": "facet_fields",
            "values": [
                "STEPHANIE JOHNSON", 16,
                "Kate Spade New York", 15,
                "Tory Burch", 11,
                "MARC BY MARC JACOBS", 10,
                "Lolo", 6
            ]
        },
        "size_fq": {
            "type": "facet_fields",
            "values": [
                "Regular", 87
            ]
        },
        "price_fq": {
            "type": "facet_ranges",
            "values": {
                "counts": [],
                "gap": 100.0,
                "start": 100.0,
                "end": 1000.0
            }
        }
    }
}

redirect

The response looks like below:

{  
    "redirect":{  
        "type":" www.myecommercesite.com",
        "value":"www.myecommercesite.com/contact-us"
    }
}

specllcheck

The response looks like below:

{
    "didYouMean": [{
        "suggestion": "iphone",
        "frequency": "7"
    }]
}

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

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

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 for “iphone cases”. The below banner response 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
        }]
    }
}

Integrating Autosuggest

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

http://search.unbxdapi.com/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:

ParameterDescription
inFields.count Defines number of autosuggest results with doctype IN_FIELD. The default value is 2.
popularProducts.count Defines number of autosuggest results with doctype POPULAR_PRODUCTS. The default value is 3.
keywordSuggestions.count Defines number of autosuggest results with doctype KEYWORD_SUGGESTION. The default value is 2.
topQueries.count Defines number of autosuggest results with doctype TOP_QUERIES. The default value is 2.

<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:

Attribute NameTypeDescription
autosuggestStringThe query string suggested by Unbxd.
doctypeEnumThe type of autosuggest.
unbxdAutosuggestSrcStringThe field on which autosuggest string was generated. It is present only in autosuggest results with doctype IN_FIELD.
unbxdAutosuggestScoreFloatThe relevancy score given to the autosuggest strings by Unbxd. This is not meant to be used by the clients.
uniqueIdStringThe random ID created for each autosuggest string. However, in the case of popular products the uniqueId is “popularProduct_” where PRODUCT_ID is the Unique ID of the product.
_inListAll fields containing _in as suffix are a part of autosuggest results for which doctype is “IN_FIELD”. For example, X_in in the autosuggest response contains all the possible values of field X which is linked to the autosuggest string.
pricedecimalPrice of the of the suggested product. This is only for Popular product.
imageUrllinkThe URL of the suggested product’s thumbnail image. This is only for Popular product.
productUrl/url_pathlinkThe URL of the suggested product. This is only for Popular product.
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"}]
  }})

Know more about Autosuggest and the doctypes


Other Sections