/search
Request Body
This is an example request body. To explore different types of request, you can use your Ref App.
You can find more information on Search API Request body here.
The key as found in your Key Management page in Command Center.
The collection to use. If you don’t pass this parameter, the system will consider default as the collection. This is case sensitive and should be same as your collection name.
The area you wish to fire against, production, staging, etc… If not specified, the Production area will be used (and if one doesn’t exist, an error will be returned).
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 and must not exceed 10 terms.
Add a biasing profile, which is defined at query time.
Override the biasing profile used for this query - takes precedence over any biasing profile set in the command center.
Sets any additional parameters that can be used to trigger rules. Takes a name and a value.
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.
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.
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.
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”.
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.
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).
Note: It is highly recommended that the highest rule is defined with
termsGreaterThanand a relativemustMatchas that guarantees that the number of matches required grows with the number of terms passed into the query.
Override the match strategy used for this query - takes precedence over any match strategy set in the command center.
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.
By default, the engine will only return refinements that make a difference in the returned results. This is called pruning.
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.
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.
Add a secured payload to the query.
Tell the search service to offset by N records. For example, if N is 10, the records returned will start at 11.
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.
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.
The Area of Command Center that was used when this query fired. If you didn’t specify anything, ‘Production’ will be used.
Holds the final text that was used in the query to the engine.
In other words, changes by the engine, like autocorrection or synonyms, are not reflected here. Changes made by a merchandiser via Command Center, like a spell correction or a stop word, are reflected here.
If synonyms are applied, only the content of this field will be used to check against the rules.
- Autocorrect
If an autocorrect was applied, this will hold the original query.
Let’s say my query of egle is autocorrected to eagle.
- Spelling correction via Command Center
If spell correction by a merchandiser via Command Center was applied, this will hold the corrected, new query.
Let’s say my query of egle is spell corrected to penguin via Command Center due to a merchandising decision.
- Stopwords via Command Center
If a stop word was added by a merchandiser, and applied against the query, this will hold the corrected, new query.
Let’s say I added record as a stopword, and the customer searched for dress record.
This returns a nested array, with each top-level item representing a unique result in the record set.
Returns the total number of results that came back within this query.
The biasing profile used to define the order of results within the returned products.
This can be controlled by settings at:
- Area level
- Rule level, which will override Area settings
- Query level, which will override Rule and Area settings
Returned if autocorrect, stop vword, or a spell correction via Command Center was applied.
Autocorrect
Let’s say my query of egle is autocorrected to eagle.
Spelling correction via Command Center
Let’s say my query of egle is spell corrected to penguin via Command Center due to a merchandising decision.
Stopwords via Command Center
Let’s say I added “record” as a stop word, and the customer searched for dress record.
This section will hold all the information about the Rule and Template that was triggered from the Command Center. If no template was defined or triggered, this will be blank.
Returns the number of the starting and last record within the response. This is 1-indexed. If your page size is larger than the number of returned records, this will return the number of the last record.
Will return the name, if applicable, and the rules that defined the match strategy that was applied to this search. This information can be used to decide on fall-back queries (if you want to re-fire a query with a softer match strategy, for example).
The name of the match strategy is defined in Command Center.
The rules that apply to this match strategy can be defined in Command Center, or at query time.
This section will return all the Dynamic Navigations defined in Command Center, that had available refinements for the given set of results. This portion can be used to render your left hand side navigation.
There are a few ways that this portion could return attributes that are different from what you expect:
includedNavigations: will restrict what’s returned here to only what’s defined in the queryexcludedNavigations: will remove navigations from this portion of the responsepruneRefinements: won’t return the navigations that wouldn’t change the results (same results, same count)- Controlled from Command Center: merchandisers can control which navigations are included at Rule level
- Scope of the recall: the navigations will only be returned if they contain refinements that are applicable to the recalled records
This holds all the refinements that were applied within the query, whether or not the field is defined as a Dynamic Navigation. All refinable fields can be filtered by, and this section will hold any selected filters.
If the query had possible alternative spellings within a close alphabetical space, alternative spellings will be returned as an array here. The didYouMean array can be used to suggest possible alternative searches.
The volume of the suggestions is controlled at Area level.
Returns an array of key-value pairs of the metadata that was defined in the Command Center area. This is controlled by the merchandiser and can be used to define Area-wide attributes to manage the rendering or behavior of your site
This is an array of values populated by the Merchandiser from Command Center. In Command Center, under query rewrites there is a Related Queries section. The merchandisers can define related queries to show given a trigger word. Those queries will return as an array in this portion of the response.
For example, a list of related queries of “coat, bear, koala” can be represented as:
{ "relatedQueries": [ "coat", "bear", "koala" ] }
This will return a list of all the query rewrites that were applied to the query. The possible values within this section are:
- “
spellings” if a spell correction from Command Center was applied - “
synonyms” if synonyms were configured in Command Cente - “
stopwords” if the query included stop words that were removed from the query - “
autocorrect” if no results were found, autocorrect was not disabled, and an autocorrect was applied
If Autocorrection was applied, this will be returned with the corrected query. This is omitted when no autocorrect was applied.