This Recommendations AI documentation references the Recommendations console. We recommend switching to the Retail console and using the Retail documentation, which documents Recommendations AI, the Retail console, and Retail Search.

If you are using the v1beta version of Recommendations AI, migrate to the Retail API version.

Method: projects.locations.catalogs.placements.search

Performs a search.

This feature is only available for users who have Retail placements.search enabled. Please enable Retail placements.search on Cloud Console before using this feature.

HTTP request

POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/placements/*}:search

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
placement

string

Required. The resource name of the search engine placement, such as projects/*/locations/global/catalogs/default_catalog/placements/default_search. This field is used to identify the serving configuration name and the set of models that will be used to make the search.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "branch": string,
  "query": string,
  "visitorId": string,
  "userInfo": {
    object (UserInfo)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "dynamicFacetSpec": {
    object (DynamicFacetSpec)
  },
  "boostSpec": {
    object (BoostSpec)
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "variantRollupKeys": [
    string
  ],
  "pageCategories": [
    string
  ],
  "searchMode": enum (SearchMode),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "labels": {
    string: string,
    ...
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  }
}
Fields
branch

string

The branch resource name, such as projects/*/locations/global/catalogs/default_catalog/branches/0.

Use "default_branch" as the branch ID or leave this field empty, to search products under the default branch.
query

string

Raw search query.

If this field is empty, the request is considered a category browsing request and returned results are based on filter and pageCategories.
visitorId

string

Required. A unique identifier for tracking visitors. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website.

This should be the same identifier as UserEvent.visitor_id.

The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error is returned.
userInfo

object (UserInfo)

User information.
pageSize

integer

Maximum number of Products to return. If unspecified, defaults to a reasonable value. The maximum allowed value is 120. Values above 120 will be coerced to 120.

If this field is negative, an INVALID_ARGUMENT is returned.
pageToken

string

A page token SearchResponse.next_page_token, received from a previous SearchService.Search call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to SearchService.Search must match the call that provided the page token. Otherwise, an INVALID_ARGUMENT error is returned.
offset

integer

A 0-indexed integer that specifies the current offset (that is, starting result location, amongst the Products deemed by the API as relevant) in search results. This field is only considered if pageToken is unset.

If this field is negative, an INVALID_ARGUMENT is returned.
filter

string

The filter syntax consists of an expression language for constructing a predicate from one or more fields of the products being filtered. Filter expression is case-sensitive. See more details at this user guide.

If this field is unrecognizable, an INVALID_ARGUMENT is returned.
canonicalFilter

string

The default filter that is applied when a user performs a search without checking any filters on the search page.

The filter applied to every search request when quality improvement such as query expansion is needed. For example, if a query does not have enough results, an expanded query with SearchRequest.canonical_filter will be returned as a supplement of the original query. This field is strongly recommended to achieve high search quality.

See SearchRequest.filter for more details about filter syntax.
orderBy

string

The order in which products are returned. Products can be ordered by a field in an Product object. Leave it unset if ordered by relevance. OrderBy expression is case-sensitive. See more details at this user guide.

If this field is unrecognizable, an INVALID_ARGUMENT is returned.
facetSpecs[]

object (FacetSpec)

Facet specifications for faceted search. If empty, no facets are returned.

A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error is returned.
dynamicFacetSpec
(deprecated)

object (DynamicFacetSpec)

Deprecated. Refer to https://cloud.google.com/retail/docs/configs#dynamic to enable dynamic facets. Do not set this field.

The specification for dynamically generated facets. Notice that only textual facets can be dynamically generated.
boostSpec

object (BoostSpec)

Boost specification to boost certain products. See more details at this user guide.

Notice that if both ServingConfig.boost_control_ids and SearchRequest.boost_spec are set, the boost conditions from both places are evaluated. If a search request matches multiple boost conditions, the final boost score is equal to the sum of the boost scores from all matched boost conditions.
queryExpansionSpec

object (QueryExpansionSpec)

The query expansion specification that specifies the conditions under which query expansion will occur. See more details at this user guide.
variantRollupKeys[]

string

The keys to fetch and rollup the matching variant Products attributes, FulfillmentInfo or LocalInventorys attributes. The attributes from all the matching variant Products or LocalInventorys are merged and de-duplicated. Notice that rollup attributes will lead to extra query latency. Maximum number of keys is 30.

For FulfillmentInfo, a fulfillment type and a fulfillment ID must be provided in the format of "fulfillmentType.fulfillmentId". E.g., in "pickupInStore.store123", "pickupInStore" is fulfillment type and "store123" is the store ID.

Supported keys are:

If this field is set to an invalid value other than these, an INVALID_ARGUMENT error is returned.
pageCategories[]

string

The categories associated with a category page. Required for category navigation queries to achieve good search quality. The format should be the same as UserEvent.page_categories;

To represent full path of category, use '>' sign to separate different hierarchies. If '>' is part of the category name, please replace it with other character(s).

Category pages include special pages such as sales or promotions. For instance, a special sale page may have the category hierarchy: "pageCategories" : ["Sales > 2017 Black Friday Deals"].
searchMode

enum (SearchMode)

The search mode of the search request. If not specified, a single search request triggers both product search and faceted search.
personalizationSpec

object (PersonalizationSpec)

The specification for personalization.
labels

map (key: string, value: string)

The labels applied to a resource must meet the following requirements:

  • Each resource can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters and cannot be empty. Values can be empty and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

See Google Cloud Document for more details.
spellCorrectionSpec

object (SpellCorrectionSpec)

The spell correction specification that specifies the mode under which spell correction will take effect.

Response body

If successful, the response body contains data with the following structure:

Response message for SearchService.Search method.

JSON representation 
{
  "results": [
    {
      object (SearchResult)
    }
  ],
  "facets": [
    {
      object (Facet)
    }
  ],
  "totalSize": integer,
  "correctedQuery": string,
  "attributionToken": string,
  "nextPageToken": string,
  "queryExpansionInfo": {
    object (QueryExpansionInfo)
  },
  "redirectUri": string,
  "appliedControls": [
    string
  ],
  "invalidConditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
Fields
results[]

object (SearchResult)

A list of matched items. The order represents the ranking.
facets[]

object (Facet)

Results of facets requested by user.
totalSize

integer

The estimated total count of matched items irrespective of pagination. The count of results returned by pagination may be less than the totalSize that matches.
correctedQuery

string

Contains the spell corrected query, if found. If the spell correction type is AUTOMATIC, then the search results are based on correctedQuery. Otherwise the original query will be used for search.
attributionToken

string

A unique search token. This should be included in the UserEvent logs resulting from this search, which enables accurate attribution of search model performance.
nextPageToken

string

A token that can be sent as SearchRequest.page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
queryExpansionInfo

object (QueryExpansionInfo)

Query expansion information for the returned results.
redirectUri

string

The URI of a customer-defined redirect page. If redirect action is triggered, no search is performed, and only redirectUri and attributionToken are set in the response.
appliedControls[]

string

The fully qualified resource name of applied controls.
invalidConditionBoostSpecs[]

object (ConditionBoostSpec)

The invalid SearchRequest.BoostSpec.condition_boost_specs that are not applied during serving.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the placement resource:

  • retail.placements.search

For more information, see the IAM documentation.

BoostSpec

Boost specification to boost certain items.

JSON representation 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ],
  "skipBoostSpecValidation": boolean
}
Fields
conditionBoostSpecs[]

object (ConditionBoostSpec)

Condition boost specifications. If a product matches multiple conditions in the specifictions, boost scores from these specifications are all applied and combined in a non-linear way. Maximum number of specifications is 20.
skipBoostSpecValidation

boolean

Whether to skip boostspec validation. If this field is set to true, invalid BoostSpec.condition_boost_specs will be ignored and valid BoostSpec.condition_boost_specs will still be applied.

ConditionBoostSpec

Boost applies to products which match a condition.

JSON representation 
{
  "condition": string,
  "boost": number
}
Fields
condition

string

An expression which specifies a boost condition. The syntax and supported fields are the same as a filter expression. See SearchRequest.filter for detail syntax and limitations.

Examples:

  • To boost products with product ID "product_1" or "product_2", and color "Red" or "Blue":
    • (id: ANY("product_1", "product_2")) AND (colorFamilies: ANY("Red","Blue"))
boost

number

Strength of the condition boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0.

Setting to 1.0 gives the item a big promotion. However, it does not necessarily mean that the boosted item will be the top result at all times, nor that other items will be excluded. Results could still be shown even when none of them matches the condition. And results that are significantly more relevant to the search query can still trump your heavily favored but irrelevant items.

Setting to -1.0 gives the item a big demotion. However, results that are deeply relevant might still be shown. The item will have an upstream battle to get a fairly high ranking, but it is not blocked out completely.

Setting to 0.0 means no boost applied. The boosting condition is ignored.

QueryExpansionSpec

Specification to determine under which conditions query expansion should occur.

JSON representation 
{
  "condition": enum (Condition),
  "pinUnexpandedResults": boolean
}
Fields
condition

enum (Condition)

The condition under which query expansion should occur. Default to Condition.DISABLED.
pinUnexpandedResults

boolean

Whether to pin unexpanded results. If this field is set to true, unexpanded products are always at the top of the search results, followed by the expanded results.

Condition

Enum describing under which condition query expansion should occur.

Enums
CONDITION_UNSPECIFIED Unspecified query expansion condition. This defaults to Condition.DISABLED.
DISABLED Disabled query expansion. Only the exact search query is used, even if SearchResponse.total_size is zero.
AUTO Automatic query expansion built by Google Retail placements.search.

SearchMode

The search mode of each search request.

Enums
SEARCH_MODE_UNSPECIFIED Default value. In this case both product search and faceted search will be performed. Both [SearchResponse.SearchResult] and [SearchResponse.Facet] will be returned.
PRODUCT_SEARCH_ONLY

Only product search will be performed. The faceted search will be disabled.

Only [SearchResponse.SearchResult] will be returned. [SearchResponse.Facet] will not be returned, even if SearchRequest.facet_specs or SearchRequest.dynamic_facet_spec is set.
FACETED_SEARCH_ONLY

Only faceted search will be performed. The product search will be disabled.

When in this mode, one or both of SearchRequest.facet_specs and SearchRequest.dynamic_facet_spec should be set. Otherwise, an INVALID_ARGUMENT error is returned. Only [SearchResponse.Facet] will be returned. [SearchResponse.SearchResult] will not be returned.

PersonalizationSpec

The specification for personalization.

JSON representation 
{
  "mode": enum (Mode)
}
Fields
mode

enum (Mode)

Defaults to Mode.AUTO.

Mode

The personalization mode of each search request.

Enums
MODE_UNSPECIFIED Default value. Defaults to Mode.AUTO.
AUTO Let CRS decide whether to use personalization.
DISABLED Disable personalization.

SpellCorrectionSpec

The specification for query spell correction.

JSON representation 
{
  "mode": enum (Mode)
}
Fields
mode

enum (Mode)

The mode under which spell correction should take effect to replace the original search query. Default to Mode.AUTO.

Mode

Enum describing under which mode spell correction should occur.

Enums
MODE_UNSPECIFIED Unspecified spell correction mode. This defaults to Mode.AUTO.
SUGGESTION_ONLY Google Retail placements.search will try to find a spell suggestion if there is any and put in the SearchResponse.corrected_query. The spell suggestion will not be used as the search query.
AUTO Automatic spell correction built by Google Retail placements.search. placements.search will be based on the corrected query if found.

SearchResult

Represents the search results.

JSON representation 
{
  "id": string,
  "product": {
    object (Product)
  },
  "matchingVariantCount": integer,
  "matchingVariantFields": {
    string: string,
    ...
  },
  "variantRollupValues": {
    string: value,
    ...
  }
}
Fields
id

string

Product.id of the searched Product.
product

object (Product)

The product data snippet in the search response. Only Product.name is guaranteed to be populated.

Product.variants contains the product variants that match the search query. If there are multiple product variants matching the query, top 5 most relevant product variants are returned and ordered by relevancy.

If relevancy can be deternmined, use matchingVariantFields to look up matched product variants fields. If relevancy cannot be determined, e.g. when searching "shoe" all products in a shoe product can be a match, 5 product variants are returned but order is meaningless.
matchingVariantCount

integer

The count of matched variant Products.
matchingVariantFields

map (key: string, value: string (FieldMask format))

If a variant Product matches the search query, this map indicates which Product fields are matched. The key is the Product.name, the value is a field mask of the matched Product fields. If matched attributes cannot be determined, this map will be empty.

For example, a key "sku1" with field mask "products.color_info" indicates there is a match between "sku1" ColorInfo and the query.
variantRollupValues

map (key: string, value: value (Value format))

The rollup matching variant Product attributes. The key is one of the SearchRequest.variant_rollup_keys. The values are the merged and de-duplicated Product attributes. Notice that the rollup values are respect filter. For example, when filtering by "colorFamilies:ANY("red")" and rollup "colorFamilies", only "red" is returned.

For textual and numerical attributes, the rollup values is a list of string or double values with type google.protobuf.ListValue. For example, if there are two variants with colors "red" and "blue", the rollup values are

{ key: "colorFamilies"
  value {
    listValue {
      values { stringValue: "red" }
      values { stringValue: "blue" }
     }
  }
}

For FulfillmentInfo, the rollup values is a double value with type google.protobuf.Value. For example, {key: "pickupInStore.store1" value { numberValue: 10 }} means a there are 10 variants in this product are available in the store "store1".

Facet

A facet result.

JSON representation 
{
  "key": string,
  "values": [
    {
      object (FacetValue)
    }
  ],
  "dynamicFacet": boolean
}
Fields
key

string

The key for this facet. E.g., "colorFamilies" or "price" or "attributes.attr1".
values[]

object (FacetValue)

The facet values for this field.
dynamicFacet

boolean

Whether the facet is dynamically generated.

FacetValue

A facet value which contains value names and their count.

JSON representation 
{
  "count": string,

  // Union field facet_value can be only one of the following:
  "value": string,
  "interval": {
    object (Interval)
  }
  // End of list of possible types for union field facet_value.
}
Fields
count

string (int64 format)

Number of items that have this facet value.
Union field facet_value. A facet value which contains values. facet_value can be only one of the following:
value

string

Text value of a facet, such as "Black" for facet "colorFamilies".
interval

object (Interval)

Interval value for a facet, such as [10, 20) for facet "price".

QueryExpansionInfo

Information describing query expansion including whether expansion has occurred.

JSON representation 
{
  "expandedQuery": boolean,
  "pinnedResultCount": string
}
Fields
expandedQuery

boolean

Bool describing whether query expansion has occurred.
pinnedResultCount

string (int64 format)

Number of pinned results. This field will only be set when expansion happens and SearchRequest.QueryExpansionSpec.pin_unexpanded_results is set to true.