Personalized Site Search Queries
When a customer executes a search, or query, it triggers a Personalized Site Search request to identify complete records from your entire storefront that meet the query criteria. The response includes multiple records, representing the search results. Each record contains data related to a single product.
Refer to Omnichannel Personalized Search Action Request for the information you must provide in an Engine API request for an Omnichannel experience configured with a Personalized Search action.
The value that you can pass in the optional typeOfSearch key determines the method(s) that Personalized Search uses to find record matches for a customer's search term. The value options for typeOfSearch are as follows:
Value | Description |
|---|---|
DEFAULT | This value prompts Monetate to use a successive order of search methods to find matches. The first method attempted is AND, which means that Monetate must find all the words of a search term exactly as typed in a record to include it in the results. If it finds no results, Monetate then tries the WILDCARD_AND search method. The order of search methods used is as follows: AND WILDCARD_AND FUZZY_AND WILDCARD_OR FUZZY_OR If a search term only contains 1 word or more than 6 words, then Monetate skips the WILDCARD_OR and FUZZY_OR search methods. |
WILDCARD_AND | This value dictates that all words of the search term must be found somewhere in a record for Monetate to include it in the results. To bolster the possibility of matches, Monetate appends a wildcard suffix to the last word of the search term (for example, the search term hooded jacket becomes hooded jacket*, and Monetate then looks for records containing hooded and any words beginning with jacket). |
FUZZY_AND | This value indicates a search method that is the same as the WILDCARD_AND query but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this query type, Monetate can still match the search term hooder jakcet to records containing hooded and jacket). |
WILDCARD_OR | This value indicates an OR search method, so Monetate must find at least 1 of the search term words in a record. To bolster the possibility of matches, Monetate appends a wildcard suffix to the last word of the search term (for example, the search term hooded jacket becomes hooded jacket*, and Monetate then looks for records containing hooded or any words beginning with jacket). |
FUZZY_OR | This value indicates a search method that is the same as the WILDCARD_OR search method but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this search method, Monetate can still match the search term hooder jakcet to records containing hooded or jacket). |
AND | This value indicates that Monetate must find all the words of a search term exactly as typed in a record to include it in the results (for example, with this search method, a search for hooded jacket only yields records that contain hooded and jacket). |
OR | This value indicates that Monetate must find at least 1 of the words of a search term exactly as typed in a record to include it in the results (for example, with this search method, a search for hooded jacket yields records that contain hooded or jacket or hooded jacket). |
Here's an example query request with the FUZZY_OR search method specified in the typeOfSearch key-value pair, along with the response:
While you can present a customer with a "No results found" message when their search term yields no products or other results, Personalized Site Search allows you to include in a query request a backup that presents the customer with the results from another query that might interest them.
Not only does a fallback query present the customer with results in lieu of a "No results found" message, it doesn't require additional HTTP requests. Furthermore, the fallback query doesn't jeopardize the initial query's performance.
To include a fallback query in a request, add the fallbackQueryId key to the initial search query, and use its value to identify the fallback. In a second query within the request, pass the id key with the same value as the value of the fallbackQueryId key, the Boolean key isFallbackQuery with the value true, along with the other required key-value pairs and any optional key-value pairs.
You can only add the fallbackQueryId key-value pair to the initial search query. You cannot add a fallback query to a fallback query.
Personalized Search triggers the fallback query only when the initial query fails to return the minimum number of results, which you define using the fallbackWhenCountLessThan key-value pair. For example, if you want the fallback query to supply results only if the initial query yields fewer than two results, then pass "fallbackWhenCountLessThan": 3 in the initial query.
If the value of isFallbackQuery is false, then Personalized Search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackWhenCountLessThan. The results of the fallback query are added to those from the initial query, which could potentially double the number of results.
The default value of isFallbackQuery is false.
Here's an example of a Personalized Site Search request that includes a fallback query along with its response:
By default, records are sorted by relevance to the search term. You can specify another order by including the sort key-value pair in the settings object.
The value options for sort are as follows:
Value | Description |
|---|---|
RELEVANCE | The default sort order, with sorting based on a combination of Personalized Search's machine learning and your merchandising configurations |
PRICE_ASC | Sort by the value of salePrice in each record (the value of the sale_price attribute in the mapped product catalog) in ascending order, or by the value of price if the mapped product catalog doesn't include a sale price |
PRICE_DESC | Sort by the value of salePrice in each record (the value of the sale_price attribute in the mapped product catalog) in descending order, or by the value of price if the mapped product catalog doesn't include a sale price |
NAME_ASC | Sort by the value of name in alphabetical order |
NAME_DESC | Sort by the value of name in reverse alphabetical order |
RATING_ASC | Sort by the average rating for each result in ascending order, if the mapped product catalog includes rating information |
RATING_DESC | Sort by the average rating for each result in descending order, if the mapped product catalog includes rating information |
NEW_ARRIVAL_ASC | Sort by the date each record was published in ascending order |
NEW_ARRIVAL_DESC | Sort by the date each record was published in descending order |
A page of search results contains a number of records up to the limit key-value specified in the settings object. Additional pages containing records beyond that limit can be created by repeating the query request with the offset key-value pair.
The value of the offset key indicates how many records should be skipped. In this example, the returned records are the sixth through tenth matches.
To properly paginate the search results, repeat the request while incrementing the offset in multiple values of the limit. For example, if the limit is 5, then the offsets in the sequence of requests should be 0, 5, 10, 15, 20, and so on.