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.

Site Search Request Overview

The basic Monetate Personalized Search API request is a POST call to the following URL:

Personalized Search API Endpoint


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.

Basic Request Code

Here's the basic Personalized Search API request:

Basic Personalized Search API Request


The search token is required for all Personalized Search API calls. It's obtained in the initial decision request.

Basic Response Code

The basic response is as follows:

Basic Personalized Search API Response


URL Redirects

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:

Personalized Search API Endpoint


The following is an example response to the GET call:

Example URL Redirect Response


You can then check for these URL redirects locally instead of making a Personalized Search API call, thus improving performance for these terms.

Auto-Suggestions

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

POST
Request
Body Parameters
id
required
String
An identifier associated with a suggestion request. Every suggestion must have a unique ID.
typeOfQuery
required
String
The type of suggestion query. Use "AUTO_SUGGESTIONS" for this parameter.
query
required
String
The search term the customer input.
limit
required
Number
The maximum number of suggestions to return.
hlStartElem
optional
String
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
optional
String
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.
Example Auto-Suggestions Request
Responses
200


Personalized Site Search Queries

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.

POST
Request
Body Parameters
id
required
String
An identifier associated with a suggestion request. Every suggestion must have a unique ID.
typeOfRequest
required
String
The type of suggestion query. Use "SEARCH" for this parameter.
settings
required
Object
The set of parameters that define the settings used for search results.
Example Personalized Site Search Query Request
Responses
200


Specifying a Query Type

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:

Example Query Request with Query Type Specified
Example Query Response with Query Type Specified


Displaying Color Variants

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:

Example Query Response with Color Variants


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

Setting Up Pagination

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.

Example Query Request with Offset


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.

Sorting Results

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.

Example Query Request with Sorting


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

Personalized Category Page Queries

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.

POST
Request
Body Parameters
id
required
String
The unique identifier associated with the request.
typeOfRequest
required
String
The type of request query. Use "CATNAV" for this parameter.
categoryPath
required
String
The name of the product category from which to retrieve results, in the same case and format as mapped into Personalized Search and with a semicolon (;) used to separate the hierarchy (for example, Mens > Shoes > Sneakers becomes Mens;Shoes;Sneakers).
Example Personalized Category Page Request
Responses
200