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 parameter determines the method(s) that Personalized Search uses to find record matches for a customer's search term. The typeOfSearch parameter value options are as follows:
Value | Description |
|---|---|
DEFAULT | This value prompts Monetate to use a successive order of search methods to find matches. The first type attempted is WILDCARD_AND. If it finds no results, Monetate then tries the FUZZY_AND search method. The order of search methods used is as follows: 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 parameter, 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 parameter to the initial search query, and use its value to identify the fallback. In a second query within the request, pass the id parameter with the same value as the value of the fallbackQueryId parameter, the Boolean parameter isFallbackQuery with the value true, along with the other required parameters and any optional parameters.
You can only add the fallbackQueryId parameter 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 parameter. 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 parameter 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 price in ascending order |
PRICE_DESC | Sort by the value of price in descending order |
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 parameter specified in the settings object. Additional pages containing records beyond that limit can be created by repeating the query request with the offset parameter.
The value of the offset parameter 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.
If a product has multiple color variants, the query response includes an additional swatchesInfo object that contains information about the color variant. Color variants are indicated by the presence of swatch_color and swatch_label values in your product catalog. If they're present, records return with values for the parameters of swatchesInfo.
The response includes the top five color variants for the product.
Here's an example response:
The parameters of the swatchesInfo object are numbered 1 through 5, each corresponding to the top five color variants.
Parameter | Data Type | Description |
|---|---|---|
variantId1 | String | The label for the variant, which is usually the name of the color, such as "Red" |
variantColor1 | String | The color of the variant expressed as a hexadecimal color code that's displayed as the color variant selector |
variantImage1 | String | The image URL for the color variant of the product that's displayed for the product when the variant color is selected |
variantSwatchImage1 | String | An image URL to display as the color variant selector that's used for patterned color variants |