This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Serving control rules

A rule is a condition-action pair. The condition dictates when the rule will execute, and the action specifies what behavior the rule will enact. You can apply rules to customize how Retail Search treats search queries and returns results.

To make a rule, create a rule-based serving control in the Cloud Console consisting of a condition that triggers the rule, and an action that takes place when the condition triggers.

You can then attach the new serving control to any Retail Search serving configurations you have created.

For more about how to create serving controls in Cloud Console, see Serving controls.

The following serving controls are available:

  • Boost/bury: Affects result ranking and order in the returned result list.
  • Filter: Removes results that do not pass the filter from the returned result list.
  • Redirect: Redirects your users to a specific page depending on the search query.
  • Linguistic: Customizes search query linguistics. Several types of linguistic controls are available:
    • Synonym: Expands considered synonyms for a search query.
    • One-way synonym: Expands considered synonyms unidirectionally for specific terms.
    • Ignore: Prevents a term from being used in searches.
    • Do not associate: Prevent terms from being used in searches when specific terms appear.
    • Replacement: Replaces terms in the search query.

Control conditions

Control conditions dictate when a rule will execute.

Control condition fields can be query terms, time ranges, or both. Depending on the rule type, you can specify multiple condition fields.

The rule condition fields available:

  • Query terms: Triggered when the term appears in the search query.
    • A full match requires the entire search query to match the query term.
    • Multiple query terms can be specified. Triggers as long as one of the query terms appears in the search query.
  • Active time range: Triggered when the date of the search query is in the time range.
    • Multiple time ranges can be specified. Triggers as long as date of query is within the time range (inclusive).

The condition fields that you specify determine whether the control will be applied.

  • Multiple condition fields are combined using AND. This means that if you specify both time range and query terms, both condition fields need to be triggered for the control to apply.
  • Multiple condition sub-fields are combined using OR. This means that if you have multiple query terms the query terms will be triggered if any one query term matches. If you have multiple time ranges, then time range will be triggered if any one time range matches.
  • No condition fields specified mean the control always applies. However, some controls require a field to be defined.

Control actions

A control action specifies what behavior the rule will enact if the control conditions are met during a search.

What kind of action you can specify depends on the type of rule you create. For example, the action for a boost/bury control is to apply a boost/bury value to products that the filter you specify, while the action for a one-way synonym control is to apply an associated term that you specify.

Boost/bury controls

Boost/bury controls enable you to show certain search results as higher or lower in ranking.

When creating a boost/bury rule, you can use filter expressions to specify the rule conditions based on Product fields. See Filtering and ordering for the filter expression syntax. You can then apply a boost value between -1.0 and 1.0 to indicate how much to boost or bury product results matching those conditions. A positive value boosts the results, and a negative value buries them.

Setting a high boost strength gives the item a large promotion, but doesn't necessarily mean that the boosted item will be the top result at all times. Results that are significantly more relevant to the search query can still trump heavily favored but irrelevant items. Likewise, setting the boost strength to -1.0 would give the item a large demotion, but results that are deeply relevant might still be shown.

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify a filter for products to boost or bury, and set the boost/bury value.

As an example of using boost/bury, you could prioritize cheaper products and de- prioritize the expensive ones.

To create a boost/bury control in Cloud Console, see Create a new serving control.

Filter controls

With filter rules, you can dynamically add pre-defined filter rules based on a specific search request.

You can use filter expressions based on Product fields. See Filtering and ordering for the filter expression syntax.

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify a filter to apply at query time.

For example, given the query "blue shoes", you can use a filter rule to automatically filter search results on the color blue. You can also use filter rules to prevent certain results from being returned to shoppers.

To create a filter control in Cloud Console, see Create a new serving control.

Redirect controls

You can use a redirect rule to redirect your shoppers to different pages based on their intent, instead of only showing them search results.

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify a redirect URI to redirect to if the conditions are matched.

For example, you could create a redirect rule so that during a promotion for a the product "gShoe", queries with "running shoes" or "sports" shoes redirects to the gShoe product page.

To create a redirect control in Cloud Console, see Create a new serving control.

Linguistic controls

You can create additions or overrides to how words are treated by default.

For example, if you are a merchandiser, you might want to expand queries that have the term "running shoes" to include "sport shoes", so that search results include both keywords. With linguistic controls, you can create a linguistic synonym rule where the condition is that "running shoes" is entered as the search term, and the action is include the synonym "sport shoes" with that search. When a shopper on your site enters "running shoes" as a query, Retail Search finds that match in the linguistic rule you created, and expands the search to include "sport shoes" when it returns search results to the shopper.

Synonym controls

Use synonym controls to link several terms together so that Retail Search treats them the same during searches.

You can set query terms and applicable time ranges as the rule conditions. You do not need to set a separate control action; if a term you specified is used as a query, the control action is to use other terms you specified as the synonyms.

For example, you could set a synonym control that associates the terms "dish towel" and "kitchen towel" as synonyms. When a shopper on your site enters "kitchen towel" as a query, Retail Search can then expand the query to include results for "dish towel", and vice versa.

To create a synonym control in Cloud Console, see Create a new serving control.

One-way synonym controls

One-way synonym controls link terms together unidirectionally.

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify the terms to use as one-way synonyms.

For example, you could set a one-way synonym control that expands searches for the term "rose" to include the term "pink". Because it is a one-way synonym, searches for the term "pink" do not expand to include the term "rose."

To create a one-way synonym control in Cloud Console, see Create a new serving control.

Ignore controls

Ignore controls prevents Retail Search from using certain query terms during searches.

An ignore rule does not guarantee that Retail Search won't provide any results. To prevent this from happening entirely, use a filter control.

You can set query terms and applicable time ranges as the rule conditions. You do not need to set a separate control action; if a term you specified is used as a query, the control action is to ignore that term.

For example, you could create a rule that ignores query terms that use offensive language.

To create an ignore control in Cloud Console, see Create a new serving control.

Do-not-associate controls

Do-not-associate controls prevent query terms from being queried together during searches with other terms that you specify.

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify the terms that should not be associated with the query terms.

For example, you could create a rule that prevents a brand name (eg. "gShoe") from being grouped with the term "cheap" and "poor quality" in a query, so that if a shopper searches for "poor quality cheap gShoe", Retail Search searches only for "gShoe."

If a relevant result for the query term also contains a term specified as "do not associate", that relevant result might still be returned. To prevent this from happening entirely, use a filter control.

To create a do-not-associate control in Cloud Console, see Create a new serving control.

Replacement controls

Replacement controls replace one or more given query terms with a different term that you specify. You can specify multiple terms that can be mapped to single term (but not vice versa).

You can set query terms and applicable time ranges as the rule conditions. As a control action, specify the term that should be used as a replacement.

For example, you could create a rule that replaces nicknames for a brand with the full brand name that is more commonly used in product descriptions.

To create an ignore control in Cloud Console, see Create a new serving control.