Search API Request

JSON Reference:

{ "biasing": {
     "bringToTop": ["productId1","productId3","productId2"],
     "restrictToIds": ["productId1","productId3","productId2"],
     "influence": 5.0,
     "augmentBiases": false,
     "biases": [
          {"name":"brand", "content":"Brand A", "strength":"Medium_Increase"},
          {"name":"brand", "content":"Brand B", "strength":"Strong_Increase"},
          {"name":"material", "content":"Material A", "strength":"Strong_Decrease"}
     ],
    "numericBoosts": [
     {"name":"size", "strength":10, "inverted":false},
     {"name":"price", "strength":0.001, "inverted":true}
]
}}

Biasing Profile

Override the biasing profile used for this query - takes precedence over any biasing profile set in the command center.

JSON Reference:

{ "biasingProfile": "PopularityBias" }

Collection

The collection to use. If you don’t pass this parameter, default will be the collection used. This is case sensitive and should be same as your collection name.

JSON Reference:

{ "collection": "FAQs" }

Custom Url Param

Sets any additional parameters that can be used to trigger rules. Takes a name and a value.

JSON Reference:

Custom URL parameters separated by ~ in the form:

{ "customUrlParams": [ { "key": "region", "value": "east" } ] }

Disable Autocorrection

Specifies whether the auto-correction behavior should be disabled. By default, when no results are returned for the given query (and there is a did-you-mean available), the first did-you-mean is automatically queried instead. Defaults to false

JSON Reference:

{ "disableAutocorrection": false }

Excluded Navigations

Specify which navigations should not be returned. If set, this forces the response to exclude certain navigations defined in Command Center. If this parameter is blank all navigations in Command Center are returned. If a navigation name is specified that does not exist, it will be ignored. If “includedNavigations” are specified, then all “excludedNavigations” are ignored. Please see the documentation on “includedNavigations” for details on wildcard characters in the field name.

JSON Reference:

{ "excludedNavigations": [ "width", "brand", "categories.categories.value" ] }

Fields

Specify which fields should be returned on each record that comes back from the engine. You may specify more than one field, if you specify \* all fields will be returned. If this parameter is blank, the search service will return an error. If this parameter is omitted, the search service will return only the title field. The title field is always returned. You can exclude fields from being returned using -. Exclusion will take precedence over inclusion.

JSON Reference:

{ "fields": [ "width", "brand", "height" ] }
{ "fields" : [ "*", "-height", "-price" ] }

Included Navigations

An array that specifies which navigations should be returned.

If set, this overrides the navigations defined in Command Center and only returns the navigations specified. If this parameter is blank the Dynamic Navigations from Command Center are returned.

The values here must be defined via Command Center or Bulk Upload. If a navigation is specified that has not been defined, it will be ignored.

This means, if this parameter uses a dummy navigation that is not real, this will both override any Command Center definitions, and will return nothing, as the navigation does not exist.

The field name supports two types of wildcard characters: ‘?’ and ‘*’. The ‘?’ wildcard will match one character. For example “???_price” will match “sale_price”, but not “sales_price”. The ‘*’ wildcard will match any number of characters. For example, a name of “*_price” will match both "sale_price and “sales_price”, but not “sale_prices”.

JSON Reference:

{ "includedNavigations": [ "width", "brand", "categories.categories.value" ] }

Language

Sets the language filter on the query and restricts the results to a certain language. If you do not specify a language, english (“lang_en”) will be considered the default. An unrecognized language will result in an error.

Currently supported languages are:

lang_en

JSON Reference:

{ "language": "lang_en" }

Match Strategy

A match strategy allows you to explicitly manage recall on a per query basis. There must always be one term matching in a query, thus termsGreaterThan can only be defined from 1 upwards and terms can only be defined from 2 upwards. It is not possible to match more terms than passed into the query. Relative mustMatch values can be used in conjunction with termsGreaterThan. A "percentage": true flag denotes a relative mustMatch to the portion of the terms and will always round down (i.e. 50% must match of 3 terms, means that 1 term must match).

The following is the default match strategy:

{ "matchStrategy": { "rules":[{ "terms": 2, "mustMatch": 2 },
                              { "terms": 3, "mustMatch": 2 },
                              { "terms": 4, "mustMatch": 3 },
                              { "terms": 5, "mustMatch": 3 },
                              { "terms": 6, "mustMatch": 4 },
                              { "terms": 7, "mustMatch": 4 },
                              { "terms": 8, "mustMatch": 5 },
                              { "termsGreaterThan": 8, "mustMatch": 60, "percentage": true }] } }

An exact matching strategy would be:

{ "matchStrategy": { "rules": { "termsGreaterThan": 1, "mustMatch": 100, "percentage": true } } }

Please note, it is highly recommended that the highest rule is defined with termsGreaterThan and a relative mustMatch as that guarantees that the number of matches required grows with the number of terms passed into the query.

JSON Reference:

{ "matchStrategy": { "rules":[{ "terms": 2, "mustMatch": 2 },
                              { "terms": 3, "mustMatch": 2 },
                              { "terms": 4, "mustMatch": 3 },
                              { "terms": 5, "mustMatch": 3 },
                              { "terms": 6, "mustMatch": 4 },
                              { "terms": 7, "mustMatch": 4 },
                              { "terms": 8, "mustMatch": 5 },
                              { "termsGreaterThan": 8, "mustMatch": 60, "percentage": true }] } }
{ "matchStrategy": { "rules": { "termsGreaterThan": 1, "mustMatch": 100, "percentage": true } } }
{ "matchStrategy": { "rules":[{ "terms": 2, "mustMatch": 1 },
                              { "termsGreaterThan": 2, "mustMatch": 75, "percentage": true }] } }

Match Strategy Name

Override the match strategy used for this query - takes precedence over any match strategy set in the command center.

JSON Reference:

{ "matchStrategyName": "RelaxedMatch" }

Or Field

Specify which fields should be queried with ‘OR’ instead of the default ‘AND’. This behavior is typically defined in command center on a per navigation basis. However, you can set which fields should be treated as an OR field at the query level if desired. As with normal refinement selections, once you have refined, the list of refinements for that selected navigation will no longer be returned.

JSON Reference:

{ "orFields": [ "field1", "field2" ] }

Page Size

Page size. Default is 10.

JSON Reference:

{ "pageSize": 8 }

Pinned Refinements

By default, the engine will return up to twenty refinements for a navigation. These refinements are ordered by either count or value. However, there are cases where the business may require a particular refinement to be always returned at the top of the list regardless of count or value (e.g. a promoted or ‘house’ brand.)

These refinements can be defined as pinnedRefinements within the navigations array, so that they are always returned at the top of the list in the Search API Response. There is a limit of 20 pinnedRefinements per navigation.

To define pinnedRefinements, you must always include the navigation name within the array, as shown below:

JSON Reference:

{ "navigations": [ {"name": "brand", "pinnedRefinements": ["Apple", "Bose", "Sennheiser"]} ] }

Prune Refinements

Parameter	Default State
pruneRefinements	true

By default, the engine will only return refinements that make a difference in the returned results. This is called pruning.

For example, let’s say you search for “Nike Red Shoes”, and 15 results come back. If we have refinements on Brand and Color, and they show:

• brand: Nike (15)
• color: red (15)

… the engine will not show those refinements by default, as they make no difference.

However, if you set pruneRefinements to false, the engine will return navigations even if they make no difference in the returned set of results.

JSON Reference:

{ pruneRefinements: false }

Query

Set a search string. If query is blank all records are considered. There are some limits enforced on the search string, it:

     - must not exceed 60 characters
     - must not exceed 10 terms.

If the limits are exceeded, the search string is truncated until all limits are satisfied. For example, the following search string

 The quick brown fox jumps over the colorful wide bridge into the cold river.

will get truncated to:

 The quick brown fox jumps over the colorful wide bridge

The terms the, cold, and river were truncated because the term limit was exceed, and into was also removed because the resulting string exceeded the character limit. Stop words are included in the string when determining if limits are exceeded. If there is only one term and it exceeds the character limit, the query will fail.

JSON Reference:

{ "query": "gloves" }

Refinement

Add a refinement. Please note that refinements are case-sensitive

JSON Reference:

Value and range refinements are both appended to an array on the refinements field. Note the ‘type’ field, which marks the refinement as either a value or range refinement.

{ "refinements": [ {"type": "Range", "navigationName": "price", "low": "1.0", "high": "2.0"},
{"type": "Value", "navigationName": "brand", "value": "Nike" } ] }

Refinements can be negated by setting the exclude property. An excluded refinement will return results that do not match the value or fall into the range specified in the refinement.

{ "refinements": [ {"type": "Range", "navigationName": "price", "low": "1.0", "high": "2.0", "exclude": true},
{"type": "Value", "navigationName": "brand", "value": "Nike", "exclude": true } ] }

Restrict Navigation

Warning This will count as two queries against your search index. Typically, this feature is used when you have a large number of navigation items that will overwhelm the end user. It works by using one of the existing navigation items to decide what the query is about and fires a second query to restrict the navigation to the most relevant set of navigation items for this search term. For example, if you pass in a search of paper and a restrict navigation of category:2 The bridge will find the category navigation refinements in the first query and fire a second query for the top 2 most populous categories. Therefore, a search for something generic like “paper” will bring back top category matches like copy paper (1,030), paper pads (567). The bridge will fire off the second query with the search term, plus an OR refinement with the most likely categories. The navigation items in the first query are entirely replaced with the navigation items in the second query, except for the navigation that was used for the restriction so that users still have the ability to navigate by all category types.

JSON Reference:

{ "restrictNavigation": { "name": "category", "count": 2 } }

Return Binary

Tells the search service to return binary data. This is enabled by default in the APIs for more efficient transport. To disable this in an API, set this to false.

JSON Reference:

If passed true, informs the search service to return binary data rather than JSON.

{ "returnBinary": true }

Secured Payload

Add a secured payload to the query.

JSON Reference:

{
  "securedPayload": {
     "cipherText":"",
     "initialValue":"",
     "messageAuthenticationCode":""
  }
}

Skip

Tell the search service to offset by N records. For example, if N is 10, the records returned will start at 11.

JSON Reference:

{ "skip": 400 }

Sort

Specifies the sort order applied to the fields in the order specified. If no sort criteria are specified, the default is to sort by relevance. There is a special sort field _relevance, which also specifies sorting by relevance. It is possible to specify multiple sort criteria. The criteria order matters, as the records will be sorted by the first criteria and then any matches will be tie-broken using the next criteria. Given an example where the sort is specified as category then _relevance, results will be sorted first by category and relevance will only affect the order between records that have the same category. Records can also be sorted by a specific ID as well when you want to return items in a specific order. If a record ID is included as a sort, but that record not a part of the result set, that item will not be included (unlike push to top). There is a limit of 1000 id’s that you can sort by. Any ID’s beyond this limit will be ignored. ID sort can also be used with other types of sorts.

Please note, sorting is based on the actual value in the record. For example, if sorting on price, and price is a Range navigation, the records will be sorted according to the actual price value in the record and not the bucket value.

The order field can be set to either Ascending or Descending. When sorting by relevance, the order is always Descending. For any other field, the default order is Ascending.

JSON Reference:

{ "sort": { "field": "price", "order": "Descending" } }
{ "sort": [{ "field": "_relevance" }, { "field": "price", "order": "Descending" }] }
{ "sort": [{ "field": "brand", "order":"Ascending" }, { "field": "_relevance" }, { "field": "price" }] }
{ "sort": [{ "type": "ByIds", "ids": ["1234"," 5678"]}] }
{ "sort": [{ "type": "ByIds", "ids": ["1234"," 5678"]}, { "field": "price", "order": "Descending" }] }

Wildcard Search Enabled

Indicate if the *(star) character in the search string should be treated as a wildcard prefix search. For example, sta* will match star and start.

JSON Reference:

{ "wildcardSearchEnabled" : true }