Calling the Personalized Search API
The basic Monetate Personalized Search API request is a POST call to the following URL:
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 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.
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.
- typeOfQuery — 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:
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.