- HTTP request
- Path parameters
- Request body
- Response body
- Authorization Scopes
- IAM Permissions
- BoostSpec
- ConditionBoostSpec
- QueryExpansionSpec
- Condition
- SearchMode
- PersonalizationSpec
- Mode
- SpellCorrectionSpec
- Mode
- SearchResult
- Facet
- FacetValue
- QueryExpansionInfo
- Try it!
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 |
Required. The resource name of the search engine placement, such as |
Request body
The request body contains data with the following structure:
JSON representation |
---|
{ "branch": string, "query": string, "visitorId": string, "userInfo": { object ( |
Fields | |
---|---|
branch |
The branch resource name, such as Use "default_branch" as the branch ID or leave this field empty, to search products under the default branch. |
query |
Raw search query. If this field is empty, the request is considered a category browsing request and returned results are based on |
visitorId |
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 The field must be a UTF-8 encoded string with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error is returned. |
userInfo |
User information. |
pageSize |
Maximum number of If this field is negative, an INVALID_ARGUMENT is returned. |
pageToken |
A page token When paginating, all other parameters provided to |
offset |
A 0-indexed integer that specifies the current offset (that is, starting result location, amongst the If this field is negative, an INVALID_ARGUMENT is returned. |
filter |
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 |
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 See |
orderBy |
The order in which products are returned. Products can be ordered by a field in an If this field is unrecognizable, an INVALID_ARGUMENT is returned. |
facetSpecs[] |
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. 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 |
Boost specification to boost certain products. See more details at this user guide. Notice that if both |
queryExpansionSpec |
The query expansion specification that specifies the conditions under which query expansion will occur. See more details at this user guide. |
variantRollupKeys[] |
The keys to fetch and rollup the matching For Supported keys are:
If this field is set to an invalid value other than these, an INVALID_ARGUMENT error is returned. |
pageCategories[] |
The categories associated with a category page. Required for category navigation queries to achieve good search quality. The format should be the same as 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 |
The search mode of the search request. If not specified, a single search request triggers both product search and faceted search. |
personalizationSpec |
The specification for personalization. |
labels |
The labels applied to a resource must meet the following requirements:
See Google Cloud Document for more details. |
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 ( |
Fields | |
---|---|
results[] |
A list of matched items. The order represents the ranking. |
facets[] |
Results of facets requested by user. |
totalSize |
The estimated total count of matched items irrespective of pagination. The count of |
correctedQuery |
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 |
A unique search token. This should be included in the |
nextPageToken |
A token that can be sent as |
queryExpansionInfo |
Query expansion information for the returned results. |
redirectUri |
The URI of a customer-defined redirect page. If redirect action is triggered, no search is performed, and only |
appliedControls[] |
The fully qualified resource name of applied controls. |
invalidConditionBoostSpecs[] |
The invalid |
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 ( |
Fields | |
---|---|
conditionBoostSpecs[] |
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 |
Whether to skip boostspec validation. If this field is set to true, invalid |
ConditionBoostSpec
Boost applies to products which match a condition.
JSON representation |
---|
{ "condition": string, "boost": number } |
Fields | |
---|---|
condition |
An expression which specifies a boost condition. The syntax and supported fields are the same as a filter expression. See Examples:
|
boost |
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 ( |
Fields | |
---|---|
condition |
The condition under which query expansion should occur. Default to |
pinUnexpandedResults |
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 |
FACETED_SEARCH_ONLY |
Only faceted search will be performed. The product search will be disabled. When in this mode, one or both of |
PersonalizationSpec
The specification for personalization.
JSON representation |
---|
{
"mode": enum ( |
Fields | |
---|---|
mode |
Defaults to |
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 ( |
Fields | |
---|---|
mode |
The mode under which spell correction should take effect to replace the original search query. Default to |
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 ( |
Fields | |
---|---|
id |
|
product |
The product data snippet in the search response. Only
If relevancy can be deternmined, use |
matchingVariantCount |
|
matchingVariantFields |
If a For example, a key "sku1" with field mask "products.color_info" indicates there is a match between "sku1" |
variantRollupValues |
The rollup matching For textual and numerical attributes, the rollup values is a list of string or double values with type
For |
Facet
A facet result.
JSON representation |
---|
{
"key": string,
"values": [
{
object ( |
Fields | |
---|---|
key |
The key for this facet. E.g., "colorFamilies" or "price" or "attributes.attr1". |
values[] |
The facet values for this field. |
dynamicFacet |
Whether the facet is dynamically generated. |
FacetValue
A facet value which contains value names and their count.
JSON representation |
---|
{ "count": string, // Union field |
Fields | |
---|---|
count |
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 |
Text value of a facet, such as "Black" for facet "colorFamilies". |
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 |
Bool describing whether query expansion has occurred. |
pinnedResultCount |
Number of pinned results. This field will only be set when expansion happens and |