Calling the Personalized Search API
Monetate's Personalized Search API is the search integration for your applications, allowing you to implement smart search and suggestions 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. This is 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 search to automatically go to your Returns Policy page. You can set up redirects in the Personalized Search UI to handle these cases.
Once set up, redirects can be retrieved and configured by the Personalized Search API, allowing you to cache them. After making the Engine API decision request, configure 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 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
Here's an example of an auto-suggestions request to the Personalized Search API:
The parameters are as follows:
- id — An identifier associated with a suggestion request. Every suggestion must have a unique ID.
- typeOfQuery — The type of suggestion query. Use "AUTO_SUGGESTIONS" for this parameter.
- query — The search term the customer input.
- limit — The maximum number of suggestions to return.
- hlStartElem — An HTML element applied at the start of the part of the auto-suggestion result that matches what the customer typed to highlight the match. If you don't specify this parameter, a value of <b> is automatically applied to make the match boldface.
- hlEndElem — An HTML element applied at the end of the part of the auto-suggestion result that matches what the customer typed. If you don't specify this parameter, a value of </b> is automatically applied.
The response to the example auto-suggestions request is as follows:
Complete records are returned after the customer executes a search. An executed search is referred to as a query. Site Search searches return records from your entire storefront.
Here's an example of a query request to the Personalized Search API:
The parameters are as follows:
- id — An identifier associated with a suggestion request. Every suggestion must have a unique ID.
- typeOfRequest — The type of suggestion query. Use "SEARCH" for this parameter.
- settings — The settings used for search results. You can include additional parameters here to further refine the query results.
- query — The search term the customer input.
- limit — The maximum number of suggestions to return.
- typeOfRecords — The type of results to return. Use "MONETATE_PRODUCT" for this parameter.
The response includes multiple records, representing the search results. Each record contains data related to a single product.
Here's the response to the example query request:
By default, returned query records include all fields. You can limit the response to specific fields by specifying what you want returned by adding a fields parameter and applicable values in the settings parameter of the request. Limiting returned fields improves response time and decreases response size. As such, you should limit returned fields to only those you intend to render.
Here's an example of a query request to the Personalized Search API with specific fields identified:
The response to this example is as follows:
If a product has multiple color variants, the response includes an additional swatchesInfo parameter that includes information about the color variant. Color variants are indicated by the presence of swatch_color and swatch_label values in your catalog feed. If these are present, records return with values for swatchesInfo.
The response includes the top five color variants for the product. An example response:
These parameters are numbered 1 through 5, each corresponding to the top five color variants.
- variantId1 — The label for the variant. This is usually the name of the color, like "Red".
- variantColor1 — The color of the variant. This is a hexadecimal color code, and is displayed as the color variant selector.
- variantImage1 — The image URL for the color variant of the product. This is displayed for the product when the variant color is selected.
- variantSwatchImage1 — An image URL to display as the color variant selector. This is used for patterend color variants.
A page of search results contains a number of records up to the limit specified in the settings of the call. Additional pages containing records beyond that limit can be created by repeating the query request with an offset specified.
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.
A fallback query is an additional query included in the request that returns records only when the original query returns no results. You can configure a fallback query, for example, to display a preferred list of results, such as best-selling products. Fallback queries are ignored if the originating query returns any results.
Monetate recommends setting a fallback query so that you avoid a search results page that's empty.
To set up a fallback query, include another query that includes the isFallbackQuery parameter that's set to true. Then in the original query, add the fallbackQueryId parameter to the settings and set it to the ID of the fallback query.
In this example request, the fallback query uses a wildcard search ("term": "*") to return records of all products. You can combine this with other functionality such as sorting to display a customized results page to take the place of an empty results page.
By default, records are sorted by relevance to the search term. You can specify another order by setting the sort parameter in the request settings.
The options for sort order are as follows:
- RELEVANCE — The default sort order.
- PRICE_ASC — Sort by price in ascending order.
- PRICE_DESC — Sort by price in descending order.
- NAME_ASC — Sort by the name of each record in alphabetical order.
- NAME_DESC — Sort by the name of each record in reverse alphabetical order.
- RATING_ASC — Sort by average rating in ascending order.
- RATING_DESC — Sort by average rating in descending order.
- NEW_ARRIVAL_ASC — Sort by record published date in ascending order.
- NEW_ARRIVAL_DESC — Sort by record published date in descending order.
Instead of searching through your entire product catalog, you can instead search through specific categories. Similar to Site Search, Monetate's Category Pages search provides relevant and personalized results based on the predefined product categories in your storefront.
The call for Category Page search is similar to a Site Search call. Change the typeOfRequest parameter to "CATNAV" and add a categoryPath parameter to the query object.
All functions available in Site Search queries (such as pagination and fallback queries) are also available to use in Category Page queries.
Here's an example of a Category Page search request:
Parameters:
- typeOfRequest — The type of suggestion query. Use "CATNAV" for this parameter.
- categoryPath — The path to the search category, separated by semicolons.
The response is also similar to a Site Search response, but also includes the parameter monetate_category indicating the product category.
Here's the response to the example query request:
Facets are attribute categories for records that customers can use to further filter results. For example, if a customer searches for shirts, facets might include size, color, or material type. Within a Monetate Personalized Search API request, you can both retrieve applicable facets to display to customers and apply facets to filter results.
Retrieving facets is a computationally expensive operation. For best performance, you should minimize the number of times you retrieve them. For example, if you're paginating search results, retrieve facets only on the first query.
To retrieve facets in a Personalized Search API request, add the filters object to the parameters with filtersToReturn.enabled set to true.
The response returns a list of filters:
You can use this list of facets to present to the customer additional options to filter their results.
Applying facets to a query filters the results based on the selected facets and values. Run this query after a customer selects the facets they want to filter by. Apply facets in a query by using the applyFilters object.
Applying facets filters out any record for which the facet attribute doesn't match the specified value. You can apply multiple facets to further filter results.
The singleSelect parameter determines the result when multiple values are specified for a facet. When it's set to true, the records returned must contain all the values. When it's set to false, the records returned must contain at least one of the values.