This is the documentation for Recommendations AI only. To try Retail Search and the unified Retail console in the restricted GA phase, contact Cloud sales. If you are not planning to use Retail Search, remain on the Recommendations console until further notice.

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 submit a form here to contact cloud sales if you are interested in using Retail placements.search.

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)
}
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.
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.

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 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

object (DynamicFacetSpec)

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

This feature requires additional allowlisting. Contact Retail placements.search support team if you are interested in using dynamic facet feature.
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. The attributes from all the matching variant Products are merged and de-duplicated. Notice that rollup variant Products attributes will lead to extra query latency. Maximum number of keys is 10.

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.

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
}
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

If spell correction applies, the corrected query. Otherwise, empty.
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 will be performed, and only redirectUri and attributionToken will be set in the response.

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.

FacetSpec

A facet specification to perform faceted search.

JSON representation 
{
  "facetKey": {
    object (FacetKey)
  },
  "limit": integer,
  "excludedFilterKeys": [
    string
  ],
  "enableDynamicPosition": boolean
}
Fields
facetKey

object (FacetKey)

Required. The facet key specification.
limit

integer

Maximum of facet values that should be returned for this facet. If unspecified, defaults to 20. The maximum allowed value is 300. Values above 300 will be coerced to 300.

If this field is negative, an INVALID_ARGUMENT is returned.
excludedFilterKeys[]

string

List of keys to exclude when faceting.

By default, FacetKey.key is not excluded from the filter unless it is listed in this field.

For example, suppose there are 100 products with color facet "Red" and 200 products with color facet "Blue". A query containing the filter "colorFamilies:ANY("Red")" and have "colorFamilies" as FacetKey.key will by default return the "Red" with count 100.

If this field contains "colorFamilies", then the query returns both the "Red" with count 100 and "Blue" with count 200, because the "colorFamilies" key is now excluded from the filter.

A maximum of 100 values are allowed. Otherwise, an INVALID_ARGUMENT error is returned.
enableDynamicPosition

boolean

Enables dynamic position for this facet. If set to true, the position of this facet among all facets in the response is determined by Google Retail placements.search. It will be ordered together with dynamic facets if dynamic facets is enabled. If set to false, the position of this facet in the response will be the same as in the request, and it will be ranked before the facets with dynamic position enable and all dynamic facets.

For example, you may always want to have rating facet returned in the response, but it's not necessarily to always display the rating facet at the top. In that case, you can set enableDynamicPosition to true so that the position of rating facet in response will be determined by Google Retail placements.search.

Another example, assuming you have the following facets in the request:

  • "rating", enableDynamicPosition = true

  • "price", enableDynamicPosition = false

  • "brands", enableDynamicPosition = false

And also you have a dynamic facets enable, which will generate a facet 'gender'. Then the final order of the facets in the response can be ("price", "brands", "rating", "gender") or ("price", "brands", "gender", "rating") depends on how Google Retail placements.search orders "gender" and "rating" facets. However, notice that "price" and "brands" will always be ranked at 1st and 2nd position since their enableDynamicPosition are false.

FacetKey

Specifies how a facet is computed.

JSON representation 
{
  "key": string,
  "intervals": [
    {
      object (Interval)
    }
  ],
  "restrictedValues": [
    string
  ],
  "prefixes": [
    string
  ],
  "contains": [
    string
  ],
  "orderBy": string,
  "query": string
}
Fields
key

string

Required. Supported textual and numerical facet keys in Product object, over which the facet values are computed. Facet key is case-sensitive.

Allowed facet keys when FacetKey.query is not specified:

  • textual_field =

    • "brands"
    • "categories"
    • "genders"
    • "ageGroups"
    • "availability"
    • "colorFamilies"
    • "colors"
    • "sizes"
    • "materials"
    • "patterns"
    • "conditions"
    • "attributes.key"
    • "pickupInStore"
    • "shipToStore"
    • "sameDayDelivery"
    • "nextDayDelivery"
    • "customFulfillment1"
    • "customFulfillment2"
    • "customFulfillment3"
    • "customFulfillment4"
    • "customFulfillment5"
    • "inventory(placeId,attributes.key)"

  • numerical_field =

    • "price"
    • "discount"
    • "rating"
    • "ratingCount"
    • "attributes.key"
    • "inventory(placeId,price)"
    • "inventory(placeId,attributes.key)"
intervals[]

object (Interval)

Set only if values should be bucketized into intervals. Must be set for facets with numerical values. Must not be set for facet with text values. Maximum number of intervals is 30.
restrictedValues[]

string

Only get facet for the given restricted values. For example, when using "pickupInStore" as key and set restricted values to ["store123", "store456"], only facets for "store123" and "store456" are returned. Only supported on textual fields and fulfillments. Maximum is 20.

Must be set for the fulfillment facet keys:

  • pickupInStore

  • shipToStore

  • sameDayDelivery

  • nextDayDelivery

  • customFulfillment1

  • customFulfillment2

  • customFulfillment3

  • customFulfillment4

  • customFulfillment5
prefixes[]

string

Only get facet values that start with the given string prefix. For example, suppose "categories" has three values "Women > Shoe", "Women > Dress" and "Men > Shoe". If set "prefixes" to "Women", the "categories" facet will give only "Women > Shoe" and "Women > Dress". Only supported on textual fields. Maximum is 10.
contains[]

string

Only get facet values that contains the given strings. For example, suppose "categories" has three values "Women > Shoe", "Women > Dress" and "Men > Shoe". If set "contains" to "Shoe", the "categories" facet will give only "Women > Shoe" and "Men > Shoe". Only supported on textual fields. Maximum is 10.
orderBy

string

The order in which [Facet.values][] are returned.

Allowed values are:

  • "count desc", which means order by [Facet.FacetValue.count][] descending.

  • "value desc", which means order by [Facet.FacetValue.value][] descending. Only applies to textual facets.

If not set, textual values are sorted in natural order; numerical intervals are sorted in the order given by FacetSpec.FacetKey.intervals; FulfillmentInfo.place_ids are sorted in the order given by FacetSpec.FacetKey.restricted_values.
query

string

The query that is used to compute facet for the given facet key. When provided, it will override the default behavior of facet computation. The query syntax is the same as a filter expression. See SearchRequest.filter for detail syntax and limitations. Notice that there is no limitation on FacetKey.key when query is specified.

In the response, [FacetValue.value][] will be always "1" and [FacetValue.count][] will be the number of results that matches the query.

For example, you can set a customized facet for "shipToStore", where FacetKey.key is "customizedShipToStore", and FacetKey.query is "availability: ANY("IN_STOCK") AND shipToStore: ANY("123")". Then the facet will count the products that are both in stock and ship to store "123".

DynamicFacetSpec

The specifications of dynamically generated facets.

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

enum (Mode)

Mode of the DynamicFacet feature. Defaults to Mode.DISABLED if it's unset.

Mode

Enum to control DynamicFacet mode

Enums
MODE_UNSPECIFIED Default value.
DISABLED Disable Dynamic Facet.
ENABLED Automatic mode built by Google Retail placements.search.

BoostSpec

Boost specification to boost certain items.

JSON representation 
{
  "conditionBoostSpecs": [
    {
      object (ConditionBoostSpec)
    }
  ]
}
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 10.

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_spec][] 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.

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.