Overview

Unbxd Site Search is an e-commerce search platform that enhances your on-site search to deliver fast, relevant, and tailored search results to visitors on your website/mobile application. Unbxd Site Search is platform-agnostic, which makes it incredibly versatile and easily implementable.

For more information, see here.

Using Search Method

Search methods perform a search with key and a few other parameters. The search key is the mandatory argument and rest is applied for different criteria.

Query method signature:

init(key: String, rows: Int? = nil, start: Int? = nil, format: ResponseFormat = .JSON, spellCheck: Bool = false, analytics: Bool = true, statsField: String? = nil, variant: Variant? = nil, fields: Array? = nil, facet: Facet? = nil, filter: FilterAbstract? = nil, categoryFilter: CategoryFilterAbstract? = nil, multipleFilter: MultipleFilterAbstract? = nil, fieldsSortOrder: Array? = nil, personalization: Bool? = nil)

Search method signature:

func search(query: SearchQuery, completion: @escaping (_ response: Dictionary<String, Any>?, _ httpResponse: HTTPURLResponse?, _ error: Error?) -> Void) {  
    // Handle response or request
}

Keywords marked in bold are different arguments for the search method. ‘query’ of type ‘SearchQuery’ is mandatory argument and rest are optional which are used as needed. SearchQuery consists of searchKey parameter with a few other parameters. Let’s see how these arguments can be composed and passed in search() method invocation.

Search Query

SearchQuery consists of a searchKey parameter with other parameters. Invoking Search method with key:

let query = SearchQuery(key: "Shirt")
client.search(query: query, completion: { (response, httpResponse, err) -> Void in  
    //Handle response
})

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

let query = SearchQuery(key: "Shirt", format: .XML)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

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.

let query = SearchQuery(key: "Shirt", start: 2, format: .JSON)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Rows

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

let query = SearchQuery(key: "Shirt", rows: 20)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Spellcheck

The spellcheck feature provides spelling suggestions or spell-checks for misspelled search queries.

let query = SearchQuery(key: "Shirt", spellCheck: true)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Analytics

The analytics parameter enables or disables tracking the query hit for analytics. By default, tracking is enabled.

let query = SearchQuery(key: "Shirt", analytics: false)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Stats

The stats parameter gives information about the products with the highest and lowest field value.

let query = SearchQuery(key: "Shirt", statsField: "price")
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Variants

Products in the feed can be available in different sizes, colors, styles, materials, etc. For example, a dress can be available in different sizes, colors and/or styles.

Variant 1: Color – Blue, Size: Small, Style – Solid print
Variant 2: Color – Red, Size: Small, Style – Solid print
Variant 3: Color – Blue, Size: Large, Style – Polka-dot

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

Examples:

{
    "feed": {
        "catalog": {
            "schema": [{
                "fieldName": "vColor",
                "id": "76678",
                "dataType": "text",
                "multiValue": "true",
                "autoSuggest": "false",
                "isVariant": "true"
            }, {
                "fieldName": "vSize",
                "dataType": "text",
                "multiValue": "true",
                "autoSuggest": "false",
                "isVariant": "true"
            }, {
                "fieldName": "vImages",
                "dataType": "link",
                "multiValue": "true",
                "autoSuggest": "false",
                "isVariant": "true"
            }, {
                "fieldName": "vPrice",
                "dataType": "decimal",
                "multiValue": "true",
                "autoSuggest": "false",
                "isVariant": "true"
            }]
        }
    }
}

Example: Search with variants:

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

let query = SearchQuery(key: "Shirt", variant: Variant(has: true, count: 2))  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

If you want to get more than one variants in the API response, you can use variantCount parameter. It can have any numerical value (for example, 1, 2, 3, etc) or “.max” (to get all the variants).

Fields

The fields parameter is used to specify the set of fields to be returned as the response, otherwise, all the fields will be returned in the response by default.

For more information, see here (Request Parameters section).

Example: Search:

The fields parameter is used to specify the set of fields to be returned. When returning the results, only fields in the list will be included.

let query = SearchQuery(key: "Shirt", fields: ["title","vPrice"])
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Facets

Facets are 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 easily configured from the SDK.

Facets can be of three types:

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

Example: Search with multi-level Facets:

let query = SearchQuery(key: "Shirt", facet: .MultiLevel)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Example: Search with multi-select Facets:

This feature enables or disables the option to select multiple values within a facet or across facets for visitors. For example, for a query “red dress”, facets of gender and size fields are displayed. If the value for facet.mult is selected is set as true and if a visitor selects Women in the Gender Facet, the search 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).

let query = SearchQuery(key: "Shirt", facet: .MultiSelect)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

Example: Search with the selected facet with field ID and value ID:

let query = SearchQuery(key: "Shirt", facet: .Selected(IdFilter(field: "76678", value: "5001")))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Selected facet with field name and value name:

let query = SearchQuery(key: "Shirt", facet: .Selected(NameFilter(field: "Brand_uFilter", value: "Vince Camuto")))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Filtering

A filter is used to restrict the products based on criteria passed. Three types of filters are supported:

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

Using Field Ids:

IdFilter can be formed with 2 parameters.

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

Example:

let query = SearchQuery(key: "Shirt", filter: IdFilter(field: "76678", value: "5001"))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Using Field Names:

NameFilter can be formed with 2 parameters.

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

let query = SearchQuery(key: "Shirt", filter: NameFilter(field: "vColor_uFilter", value: "Black"))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Range: It is used to filter products based on fields with data types – date, number or decimal. It can be defined in the API in two ways:

Using Field Names:

Filter Range of type id is built using IdFilterRange class and it can be initialized with below parameters.

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

Example:

let query = SearchQuery(key: "Shirt", filter: IdFilterRange(field: "76678", lower: "2034", upper: "8906"))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Using Field Name:

Filter Range of type name is built using NameFilterRange class and it can be initialized with below parameters.

field: The name of the field on which the text filter is applied.
lower: The name of the lower limit of the range.
upper: The name of the upper limit of the range.

Example:

let query = SearchQuery(key: "Shirt", filter: NameFilterRange(field: "vColor", lower: "red", upper: "blue"))
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Multilevel: It is used to filter products based on categories.

Each of the three filters can filter on field-name and field-id. Field-id/field-name is an optional parameter. If passed, it eliminates those products that do not match the criteria.

NOTE: If IDs are present in the feed, filtering should be done on IDs only.

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

Using Field Ids:

CategoryIdFilter is used to filter the results using category path comprised of category IDs.

Example:

let categoryNameFilter = CategoryNameFilter()  
categoryNameFilter.categories.append("Fashion")  
categoryNameFilter.categories.append("Shirts")
let query = SearchQuery(key: "Shirt", categoryFilter: categoryNameFilter)
client.search(query: query, completion: {(response, httpResponse, err) -> Void in  
    //Handle response
})

Search with Multiple Filters using Field ID/Field Name

Multiple Filters: Multiple facets can be selected, which applies corresponding filters in a single call. There are two types of filter operations:

Search with multiple filters using AND and field ID/field name:

MultipleIdFilter takes two parameters, fieldType Id and fieldValue id.

MultipleNameFilter takes two parameters, fieldType name, and fieldValue name.

Multiple filters can be added and operatorType is set to ‘AND’.

// Using field ID
let multipleIdFilter = MultipleIdFilter.init()
multipleIdFilter.operatorType = .AND
multipleIdFilter.filters.append(IdFilter.init(withFieldType: "76678", fieldValue: "5001"))
multipleIdFilter.filters.append(IdFilter.init(withFieldType: "76678", fieldValue: "5021"))
client?.searchWithQuery(query: searchQuery, multipleFilter: multipleIdFilter, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response 
})

// Using field name
let multipleNameFilter = MultipleNameFilter.init()
multipleNameFilter.operatorType = .AND
multipleNameFilter.filters.append(NameFilter.init(withFieldType: "vColor_uFilter", fieldValue: "Black"))
multipleNameFilter.filters.append(NameFilter.init(withFieldType: "vColor_uFilter", fieldValue: "White"))  
client?.searchWithQuery(query: searchQuery, multipleFilter: multipleNameFilter, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response 
})

Search with multiple filters using OR and field ID/field name:

MultipleIdFilter takes two parameters, fieldType Id and fieldValue id.

MultipleNameFilter takes two parameters, fieldType name, and fieldValue name.

Multiple filters can be added and operatorType is set to ‘OR’.

// Using field ID
let multipleIdFilter = MultipleIdFilter()  
multipleIdFilter.operatorType = .OR  
multipleIdFilter.filters.append(IdFilter(field: "76678", value: "5001"))  
multipleIdFilter.filters.append(IdFilter(field: "76678", value: "5021"))  
let query = SearchQuery(key: "Shirt", multipleFilter: multipleIdFilter)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

// Using field name
let multipleNameFilter = MultipleNameFilter()  
multipleNameFilter.operatorType = .OR  
multipleNameFilter.filters.append(IdFilter(field: "vColor_uFilter", value: "Black"))  
multipleNameFilter.filters.append(IdFilter(field: "vColor_uFilter", value: "White"))  
let query = SearchQuery(key: "Shirt", multipleFilter: multipleIdFilter)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

Sorting

The sort parameter is used to rank the products based on specified fields in the specified order. You can sort on a single field or in multiple fields.

Search with sorting on the single field/multiple fields:

fieldName: The field on which the sort is applied.
sortOrder: The order in which the sort is applied. This value can be “ASC” (for ascending) or “DSC” (for descending).

// single field
var fieldsWithOrder = Array()  
fieldsWithOrder.append(FieldSortOrder(field: "price", order: .ASC))  
let query = SearchQuery(key: "Shirt", fieldsSortOrder: fieldsWithOrder)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

// multiple fields hence 2 or more FieldSortOrder instances are added
var fieldsWithOrder = Array()  
fieldsWithOrder.append(FieldSortOrder(field: "price", order: .ASC))  
fieldsWithOrder.append(FieldSortOrder(field: "title", order: .DSC))  
let query = SearchQuery(key: "Shirt", fieldsSortOrder: fieldsWithOrder)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

Spellcheck

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

let query = SearchQuery(key: "Shirt", spellCheck: true)  
client.search(query: query, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})

// Using Field Name
let nameRange = NameFilterRange(field: "vColor", lower: "red", upper: "blue")  
let autoSuggestQuery = AutoSuggestQuery(withKey: "Shir", docType: DocTypeKeywordSuggestions(resultsCount: 4), filter: nameRange)  
client.autoSuggest(query: autoSuggestQuery, completion: {(response: Any?, error: Error?) -> Void in  
    //Handle response
})