Calling the Personalized Search API
Monetate's Personalized Search API is the search integration for your applications, allowing you to implement Personalized Site Search and Personalized Category Pages for your customers.
The basic Monetate Personalized Search API request is a POST call to the following URL:
The action ID is the ID you obtained in the initial decision request.
A request is comprised of two parts:
- Suggestions: Automatic suggestions based on the text currently typed into the search field. Suggestions are updated live as the customer updates their search.
- Queries: Complete results from a search. An individual result is called a record. Queries are returned after the customer formally sends their search request.
Both suggestions and queries can be included in the request.
Here's the basic Personalized Search API request:
The search token is required for all Personalized Search API calls. It's obtained in the initial decision request.
The basic response is as follows:
You might want some terms a customer searches for to go to a specific page instead of returning a list of records. For example, if a customer searches for return policy, you want Personalized Site Search to automatically send the customer to your Returns Policy page. See Create URL Redirects in the Monetate Knowledge Base for the steps to set up URL redirects in the Personalized Search user interface.
Once set up, URL redirects can be retrieved and configured by the Personalized Search API, allowing you to cache them. After making the Engine API decision request, configure URL redirects by making a GET call to the following URL:
The following is an example response to the GET call:
You can then check for these URL redirects locally instead of making a Personalized Search API call, thus improving performance for these terms.
The auto-suggestions search type returns live results as the customer types each character in their search term. Results are returned as a response to a Personalized Search API call that's made each time the customer types a new character.
The recommended interval to wait between auto-suggestions request calls is 250 ms on key presses and 30 ms on focus
Complete records are returned after the customer executes a search. An executed search is referred to as a query. Personalized Site Search searches return records from your entire storefront. The response includes multiple records, representing the search results. Each record contains data related to a single product.
The value that you can pass in the optional typeOfSearch parameter determines the methods 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 query types to find matches. The first type attempted is WILDCARD_AND. If it finds no results, Monetate then tries the FUZZY_AND query type. The order of query types 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 query types. |
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 query type that is the same as a 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 query, 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*, Monetate then looks for records containing hooded or any words beginning with jacket). |
FUZZY_OR | This value indicates a query type that is the same as a WILDCARD_OR 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 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 query type, 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 query type, 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:
If a product has multiple color variants, the response includes an additional swatchesInfo object that includes 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 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 patterend color variants |
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.
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 |
Just as Personalized Site Search allows you to serve up customized, personalized search results from your entire product catalog, Monetate's Personalized Category Pages allows you to present customers with customized, personalized product category list pages based on the product categories defined in your product catalog.
A Personalized Category Page request to the Pesonalized Search API is similar to a Personalized Site Search request. Change the typeOfRequest parameter to "CATNAV", and then add a categoryPath parameter to the query object.
The response is also similar to a Personalized Site Search response, but it also includes the monetate_category parameter that indicates the product category.
All functions available in Personalized Site Search queries—such as pagination and facets—are available to use in Personalized Category Page queries.