Docs

Unbxd Autosuggest

Overview

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 deploy Unbxd Autosuggest as a standalone feature in your site.

Autosuggest API format

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>&version=V2&inFields.count=<value>&popularProducts.count=<value>&keywordSuggestions.count=<value>&topQueries.count=<value>&promotedSuggestion.count=<value>&popularProducts.fields=<comma separated list of fields>&variants=<true|false>&filter=<filter_query>  

Request Parameters

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

ParameterDescription
inFields.countDefines number of autosuggest results with doctype IN_FIELD. The default value is 2.
popularProducts.countDefines number of autosuggest results with doctype POPULAR_PRODUCTS. The default value is 3.
keywordSuggestions.countDefines number of autosuggest results with doctype KEYWORD_SUGGESTION. The default value is 2.
topQueries.countDefines number of autosuggest results with doctype TOP_QUERIES. The default value is 2.
popularProducts.fieldsReturns the fields required for popular products.
promotedSuggestion.countDefines the number of autosuggest results with doctype PROMOTED_SUGGESTION. The default value is 2.
popularProducts.filterRestrict the Popular Products based on criteria passed (using field name). This applies to only popularProducts in the Autosuggest API response and works similar to the "filter" request parameter for Search and Browse API
popularProducts.filter-idRestrict the Popular Products based on criteria passed (using field ID). This applies to only popularProducts in the Autosuggest API response and works similar to the "filter-id" request parameter for Search and Browse API
filterRestrict the products based on criteria passed (using field-name). For more information, see Filter - request parameter.
spellcheckEnable spellcheck in autosuggest. When spellcheck=true parameter is passed in the autosuggest API, it returns did-you-mean block with spellcheck suggestion same as the search API. (default=false)
versionVersion of the API. Passing “version” parameter is mandatory in the API. However, V1 is deprecated, please ensure that every API call has “version=V2”.
variantsEnables or disables variants in the API response. (default=false)

Headers

To enable personalization of the merchandising campaigns, we recommend passing these parameters as HTTPS headers. The following parameters are available:

ParameterDescriptionMandatorySignificance
userIdUnique 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 be affected.
user-agentBrowser identification information passed to the web server with every HTTPS request.NoIf not passed, device based merchandising campaigns will be affected.
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.

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.

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

Attribute NameTypeDescription
autosuggestStringThe query string suggested by Unbxd for the autosuggest
doctypeEnumThe type of autosuggest. Possible values are “POPULAR_PRODUCTS”, “TOP_SEARCH_QUERIES”, “PROMOTED_SUGGESTION” , “IN_FIELD” , “KEYWORD_SUGGESTION”
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.
productUrllinkThe URL of the suggested product. This is only for Popular product.

Filters (request parameter)

Filters can be of two types, text and range.

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, as shown below:

https://search.unbxd.io/<api-key>/<site-key>/autosuggest?q=<query>&filter=fieldname:"value"&version=V2  

The range filter is used to filter products based on fields with dataypes - date, number or decimal. It can be defined in the API call, as shown below:

https://search.unbxd.io/<api-key>/<site-key>/autosuggest?q=<query>&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 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.

API Response

The response varies based on, if the fields in the feed has IDs.

Case 1: Feed does not have IDs

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

{
    "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
            }
        ]
    }
}

Case 2: Feed has IDs

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

{
    "response": {
        "numberOfProducts": 319,
        "start": 0,
        "products": [{
                "product_name": "Bose&reg; Solo 5 All-in-One TV Sound System",
                "product_minimum_price": 24995,
                "product_maximum_price": 24995,
                "uniqueId": "8096200",
                "product_image_url": [
                    "https://i01.hsncdn.com/is/image/HomeShoppingNetwork/prodgrid230/boseandreg-solo-5-all-in-one-tv-sound-system-d-2016041214464463~487047.jpg"
                ],
                "doctype": "POPULAR_PRODUCTS",
                "autosuggest": "Bose&reg; Solo 5 All-in-One TV Sound System",
                "variantCount": 1,
                "score": 0.72101027,
                "relevantDocument": "parent",
                "variants": [{
                    "vId": "8096200_8096200",
                    "variant_price": 24995,
                    "variant_name": "Bose&reg; Solo 5 All-in-One TV Sound System",
                    "variant_image_url": [
                        "https://i01.hsncdn.com/is/image/HomeShoppingNetwork/prodgrid230/boseandreg-solo-5-all-in-one-tv-sound-system-d-2016041214464463~487047.jpg"
                    ],
                    "product_name": "Bose&reg; Solo 5 All-in-One TV Sound System",
                    "product_minimum_price": 24995,
                    "product_maximum_price": 24995,
                    "product_image_url": [
                        "https://i01.hsncdn.com/is/image/HomeShoppingNetwork/prodgrid230/boseandreg-solo-5-all-in-one-tv-sound-system-d-2016041214464463~487047.jpg"
                    ],
                    "doctype": "POPULAR_PRODUCTS",
                    "autosuggest": "Bose&reg; Solo 5 All-in-One TV Sound System",
                    "variantCount": 1,
                    "score": 0.55901694
                }]
            },
            {
                "autosuggest": "Tv",
                "autosuggest_unstemmed": "Tv",
                "doctype": "TOP_SEARCH_QUERIES",
                "unbxdAutosuggestScore": 9595,
                "uniqueId": "fc214f77-18f0-453a-86f0-b57b38e32edc",
                "timeStamp_unbxd": 1515997682378,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638785889468400,
                "parent_unbxd": true
            },
            {
                "autosuggest": "smart tv",
                "autosuggest_unstemmed": "smart tv",
                "doctype": "TOP_SEARCH_QUERIES",
                "unbxdAutosuggestScore": 3037,
                "uniqueId": "9bf4e2b3-e875-48aa-a0eb-78e2c9a8ff4e",
                "timeStamp_unbxd": 1515997682377,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638785876885500,
                "parent_unbxd": true
            },

            {
                "autosuggest": "TV Antennas",
                "autosuggest_unstemmed": "TV Antennas",
                "start_unbxdDate": 1504810200000,
                "end_unbxdDate": 3871602000000,
                "doctype": "PROMOTED_SUGGESTION",
                "uniqueId": "fd824703-1994-4944-a03a-a7bcb0015eba",
                "timeStamp_unbxd": 1515997682479,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638837046345700,
                "parent_unbxd": true
            },
            {
                "autosuggest": "Apple TV",
                "autosuggest_unstemmed": "Apple TV",
                "start_unbxdDate": 1502280240000,
                "end_unbxdDate": 3869078400000,
                "doctype": "PROMOTED_SUGGESTION",
                "uniqueId": "46b4a465-4db1-43b3-9b3a-560b68ff0e5b",
                "timeStamp_unbxd": 1515997682479,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638837037957000,
                "parent_unbxd": true
            },
            {
                "autosuggest": "TV Accessories",
                "autosuggest_unstemmed": "TV Accessories",
                "doctype": "IN_FIELD",
                "unbxdAutosuggestSrc": "categoryPath3",
                "categoryPath1_unbxdMap_in": [
                    "EC|Electronics",
                    "HO|Home"
                ],
                "categoryPath3_unbxdMap_in": [
                    "EC>EC0073>EC0508|Electronics>TVs & Home Theater>TV Accessories",
                    "HO>HO0209>HO0185|Home>Home Appliances>Living Room Furniture",
                    "HO>HO0115>HO0214|Home>Furniture>Heating",
                    "HO>HO0115>HO0185|Home>Furniture>Living Room Furniture",
                    "EC>EC0073>EC0469|Electronics>TVs & Home Theater>Media Streamers",
                    "EC>EC0542>EC0501|Electronics>Cell Phones & Accessories>Audio Accessories",
                    "EC>EC0202>EC0504|Electronics>Audio>Home Office Accessories",
                    "EC>EC0573>EC0503|Electronics>Home Office>Cell Phone Accessories"
                ],
                "categoryPath2_unbxdMap_in": [
                    "EC>EC0073|Electronics>TVs & Home Theater",
                    "HO>HO0209|Home>Home Appliances",
                    "HO>HO0115|Home>Furniture",
                    "EC>EC0573|Electronics>Home Office",
                    "EC>EC0542|Electronics>Cell Phones & Accessories",
                    "EC>EC0506|Electronics>Electronic Home Accessories",
                    "EC>EC0202|Electronics>Audio"
                ],
                "variant_available_flag_filter": [
                    "true",
                    "false"
                ],
                "categoryPath4_unbxdMap_in": [
                    "EC>EC0073>EC0508>HO0162|Electronics>TVs & Home Theater>TV Accessories>Fireplaces",
                    "HO>HO0209>HO0185>HO0191|Home>Home Appliances>Living Room Furniture>TV Stands & Media Centers",
                    "HO>HO0115>HO0214>HO0533|Home>Furniture>Heating>Fireplaces & Stoves",
                    "EC>EC0073>EC0508>HO0191|Electronics>TVs & Home Theater>TV Accessories>TV Stands & Media Centers"
                ],
                "Brand_in": [
                    "1-Brand|14725-Southern Enterprises",
                    "1-Brand|9627-Home Marketplace",
                    "1-Brand|11952-Home Styles",
                    "1-Brand|9304-Level Mount",
                    "1-Brand|1255-Dell",
                    "1-Brand|13951-Amazon",
                    "1-Brand|13525-American Dreams",
                    "1-Brand|13440-Logitech",
                    "1-Brand|1043-Samsung"
                ],
                "uniqueId": "5a8b2d4e-6382-4815-b7c3-134b0bcd4f0b",
                "timeStamp_unbxd": 1515997681725,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638785475281000,
                "parent_unbxd": true
            },

            {
                "autosuggest": "TV Accessories",
                "autosuggest_unstemmed": "TV Accessories",
                "doctype": "KEYWORD_SUGGESTION",
                "variant_available_flag_filter": [
                    "true",
                    "false"
                ],
                "uniqueId": "191a5505-0529-43cb-a859-334cd156e390",
                "timeStamp_unbxd": 1515997681726,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638785477378000,
                "parent_unbxd": true
            },
            {
                "autosuggest": "TVs & Home Theater",
                "autosuggest_unstemmed": "TVs & Home Theater",
                "doctype": "KEYWORD_SUGGESTION",
                "variant_available_flag_filter": [
                    "true",
                    "false"
                ],
                "uniqueId": "636eb648-dbce-4622-bfe9-d1be6d4e9a58",
                "timeStamp_unbxd": 1515997681661,
                "unbxdFeedId": "autosuggest",
                "_version_": 1589638785427046400,
                "parent_unbxd": true
            }
        ]
    },
    "searchMetaData": {
        "status": 0,
        "queryTime": 49,
        "queryParams": {
            "log.response": "false",
            "alternate.op": "true",
            "popularProducts.fields": "product_name,uniqueId,product_maximum_price,product_minimum_price,product_image_url,vId,relevantDocument,variant_name,variant_image_url,variant_price,doctype,autosuggest",
            "variants": "true",
            "platform": "refireSpellcheck",
            "f.categoryPath.facet.limit": "100",
            "f.categoryPath.position": "1",
            "req.rm.promotionEngine": "true",
            "f.categoryPath.nameId": "true",
            "inFields.count": "15",
            "_": "1516091870811",
            "topQueries.count": "15",
            "popularProducts.count": "8",
            "req.rm.asterix": "true",
            "brewer.spellcheck.refire": "true",
            "version": "V2",
            "f.categoryPath.displayName": "Category",
            "filter": [
                "((doctype:\"PROMOTED_SUGGESTION\") OR (doctype:\"IN_FIELD\") OR (doctype:\"TOP_SEARCH_QUERIES\") OR (doctype:\"KEYWORD_SUGGESTION\") OR (product_effective_start_date:[0 TO 1516091872952] AND product_effective_end_date:[1516091872952 TO 253404959399997]) )",
                "-product_available_flag:\"false\"",
                "-variant_available_flag:\"false\""
            ],
            "q": "tv",
            "f.categoryPath.max.depth": "4",
            "keywordSuggestions.count": "15",
            "facet.multilevel": "categoryPath",
            "user.behaviour": "true",
            "_JSONP_": "jQuery32107190347005969819_1516091870810",
            "enablePopularity": "true"
        }
    }
}

Doctypes

Unbxd Autosuggest comprises of different types of suggestions that are known as doctypes. A standard Unbxd Autosuggest is segmented into five doctypes:

  • In-fields
  • Keyword Suggestions
  • Top Queries
  • Popular Products
  • Promoted Suggestions

Important: Unbxd allows you to configure each autosuggest doctype.

In-fields

The query being typed by your visitor can belong to multiple product categories based on your product feed. The In-fields doctype in Autosuggest suggest groups of relevant products along with their associated field values the query may belong to. These field values can be categories, brands, occasion, etc.
The default Unbxd autosuggest has In-fields as the first doctype that appears in the dropdown. In-fields are generated and displayed to your visitors as they type.
For example, a visitor types ‘Sh’, the In-field doctype will have the following suggestions:

Shirts
In Men (based on gender)

In Nike, (based on brand)

In Blue (based on occasion)

Shoes
In Running shoes (based on occasion )

In Nike, (based on brand)

In Blue (based on occasion)

A default Unbxd Autosuggest with In-fields will look like this:

Keyword Suggestions

These are intelligent suggestions generated by Unbxd cloud servers whose algorithm identifies the keywords from the query being typed and suggests relevant products based on your product feed accordingly.
For example, a visitor types ‘Sh’, the keyword suggestions doctype will have the following suggestions:

  • Shirts
  • Shorts
  • Shoes
  • Shapewear

A default Unbxd Autosuggest with keyword suggestions will look like this:

Top Search Queries

As the name suggests, this autosuggest doctype displays the frequently searched queries in your e-commerce store. These top queries are populated with the help of Unbxd Analytics which keeps a track of your store. Hence, it is important that you integrate Unbxd Analytics in your e-commerce store.
To know more about Unbxd Analytics, refer Analytics Integration.

A default Unbxd Autosuggest with Top Queries will look like this:

Popular Products

The Popular Products doctype displays popular product in your ecommerce store with thumbnail images. Similar to Top Queries doctype, to render Popular products, Unbxd analytics needs to be integrated in your ecommerce store.

A default Unbxd Autosuggest with Popular Products will look like this:

Promoted Suggestions

Promoted Suggestions are documents that a customer can configure directly from merchandising console. This gives you the flexibility to manually insert keyword suggestions in autosuggest which may not be part of the default relevance results.

For example, if a customer configures “jogging shoes” and “running shoes” as promoted suggestions, then when a shopper searches for “sh”, the intended results get returned by the autosuggest API. Customer can choose to display promoted suggestions in autosuggest in the order that is preferred.