googleapis/google/cloud/retail/v2/common.proto

// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.retail.v2;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Retail.V2";
option go_package = "google.golang.org/genproto/googleapis/cloud/retail/v2;retail";
option java_multiple_files = true;
option java_outer_classname = "CommonProto";
option java_package = "com.google.cloud.retail.v2";
option objc_class_prefix = "RETAIL";
option php_namespace = "Google\\Cloud\\Retail\\V2";
option ruby_package = "Google::Cloud::Retail::V2";

// An intended audience of the [Product][google.cloud.retail.v2.Product] for
// whom it's sold.
message Audience {
  // The genders of the audience. Strongly encouraged to use the standard
  // values: "male", "female", "unisex".
  //
  // At most 5 values are allowed. Each value must be a UTF-8 encoded string
  // with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error
  // is returned.
  //
  // Google Merchant Center property
  // [gender](https://support.google.com/merchants/answer/6324479). Schema.org
  // property
  // [Product.audience.suggestedGender](https://schema.org/suggestedGender).
  repeated string genders = 1;

  // The age groups of the audience. Strongly encouraged to use the standard
  // values: "newborn" (up to 3 months old), "infant" (3–12 months old),
  // "toddler" (1–5 years old), "kids" (5–13 years old), "adult" (typically
  // teens or older).
  //
  // At most 5 values are allowed. Each value must be a UTF-8 encoded string
  // with a length limit of 128 characters. Otherwise, an INVALID_ARGUMENT error
  // is returned.
  //
  // Google Merchant Center property
  // [age_group](https://support.google.com/merchants/answer/6324463).
  // Schema.org property
  // [Product.audience.suggestedMinAge](https://schema.org/suggestedMinAge) and
  // [Product.audience.suggestedMaxAge](https://schema.org/suggestedMaxAge).
  repeated string age_groups = 2;
}

// The color information of a [Product][google.cloud.retail.v2.Product].
message ColorInfo {
  // The standard color families. Strongly recommended to use the following
  // standard color groups: "Red", "Pink", "Orange", "Yellow", "Purple",
  // "Green", "Cyan", "Blue", "Brown", "White", "Gray", "Black" and
  // "Mixed". Normally it is expected to have only 1 color family. May consider
  // using single "Mixed" instead of multiple values.
  //
  // A maximum of 5 values are allowed. Each value must be a UTF-8 encoded
  // string with a length limit of 128 characters. Otherwise, an
  // INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [color](https://support.google.com/merchants/answer/6324487). Schema.org
  // property [Product.color](https://schema.org/color).
  repeated string color_families = 1;

  // The color display names, which may be different from standard color family
  // names, such as the color aliases used in the website frontend. Normally
  // it is expected to have only 1 color. May consider using single "Mixed"
  // instead of multiple values.
  //
  // A maximum of 5 colors are allowed. Each value must be a UTF-8 encoded
  // string with a length limit of 128 characters. Otherwise, an
  // INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [color](https://support.google.com/merchants/answer/6324487). Schema.org
  // property [Product.color](https://schema.org/color).
  repeated string colors = 2;
}

// A custom attribute that is not explicitly modeled in
// [Product][google.cloud.retail.v2.Product].
message CustomAttribute {
  // The textual values of this custom attribute. For example, `["yellow",
  // "green"]` when the key is "color".
  //
  // At most 400 values are allowed. Empty values are not allowed. Each value
  // must be a UTF-8 encoded string with a length limit of 256 characters.
  // Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
  // [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
  // Otherwise, an INVALID_ARGUMENT error is returned.
  repeated string text = 1;

  // The numerical values of this custom attribute. For example, `[2.3, 15.4]`
  // when the key is "lengths_cm".
  //
  // At most 400 values are allowed.Otherwise, an INVALID_ARGUMENT error is
  // returned.
  //
  // Exactly one of [text][google.cloud.retail.v2.CustomAttribute.text] or
  // [numbers][google.cloud.retail.v2.CustomAttribute.numbers] should be set.
  // Otherwise, an INVALID_ARGUMENT error is returned.
  repeated double numbers = 2;

  // If true, custom attribute values are searchable by text queries in
  // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
  //
  // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
  //
  // Only set if type [text][google.cloud.retail.v2.CustomAttribute.text] is
  // set. Otherwise, a INVALID_ARGUMENT error is returned.
  optional bool searchable = 3;

  // If true, custom attribute values are indexed, so that it can be filtered,
  // faceted or boosted in
  // [SearchService.Search][google.cloud.retail.v2.SearchService.Search].
  //
  // This field is ignored in a [UserEvent][google.cloud.retail.v2.UserEvent].
  //
  // See [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter],
  // [SearchRequest.facet_specs][google.cloud.retail.v2.SearchRequest.facet_specs]
  // and
  // [SearchRequest.boost_spec][google.cloud.retail.v2.SearchRequest.boost_spec]
  // for more details.
  optional bool indexable = 4;
}

// Fulfillment information, such as the store IDs for in-store pickup or region
// IDs for different shipping methods.
message FulfillmentInfo {
  // The fulfillment type, including commonly used types (such as pickup in
  // store and same day delivery), and custom types. Customers have to map
  // custom types to their display names before rendering UI.
  //
  // Supported values:
  //
  // * "pickup-in-store"
  // * "ship-to-store"
  // * "same-day-delivery"
  // * "next-day-delivery"
  // * "custom-type-1"
  // * "custom-type-2"
  // * "custom-type-3"
  // * "custom-type-4"
  // * "custom-type-5"
  //
  // If this field is set to an invalid value other than these, an
  // INVALID_ARGUMENT error is returned.
  string type = 1;

  // The IDs for this [type][google.cloud.retail.v2.FulfillmentInfo.type], such
  // as the store IDs for
  // [FulfillmentInfo.type.pickup-in-store][google.cloud.retail.v2.FulfillmentInfo.type]
  // or the region IDs for
  // [FulfillmentInfo.type.same-day-delivery][google.cloud.retail.v2.FulfillmentInfo.type].
  //
  // A maximum of 2000 values are allowed. Each value must be a string with a
  // length limit of 10 characters, matching the pattern [a-zA-Z0-9_-]+, such as
  // "store1" or "REGION-2". Otherwise, an INVALID_ARGUMENT error is returned.
  repeated string place_ids = 2;
}

// [Product][google.cloud.retail.v2.Product] thumbnail/detail image.
message Image {
  // Required. URI of the image.
  //
  // This field must be a valid UTF-8 encoded URI with a length limit of 5,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // Google Merchant Center property
  // [image_link](https://support.google.com/merchants/answer/6324350).
  // Schema.org property [Product.image](https://schema.org/image).
  string uri = 1 [(google.api.field_behavior) = REQUIRED];

  // Height of the image in number of pixels.
  //
  // This field must be nonnegative. Otherwise, an INVALID_ARGUMENT error is
  // returned.
  int32 height = 2;

  // Width of the image in number of pixels.
  //
  // This field must be nonnegative. Otherwise, an INVALID_ARGUMENT error is
  // returned.
  int32 width = 3;
}

// A floating point interval.
message Interval {
  // The lower bound of the interval. If neither of the min fields are set, then
  // the lower bound is negative infinity.
  //
  // This field must be not larger than
  // [max][google.cloud.retail.v2.Interval.max]. Otherwise, an INVALID_ARGUMENT
  // error is returned.
  oneof min {
    // Inclusive lower bound.
    double minimum = 1;

    // Exclusive lower bound.
    double exclusive_minimum = 2;
  }

  // The upper bound of the interval. If neither of the max fields are set, then
  // the upper bound is positive infinity.
  //
  // This field must be not smaller than
  // [min][google.cloud.retail.v2.Interval.min]. Otherwise, an INVALID_ARGUMENT
  // error is returned.
  oneof max {
    // Inclusive upper bound.
    double maximum = 3;

    // Exclusive upper bound.
    double exclusive_maximum = 4;
  }
}

// The price information of a [Product][google.cloud.retail.v2.Product].
message PriceInfo {
  // The price range of all
  // [variant][google.cloud.retail.v2.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2.Product] having the same
  // [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id].
  message PriceRange {
    // The inclusive
    // [Product.pricing_info.price][google.cloud.retail.v2.PriceInfo.price]
    // interval of all [variant][google.cloud.retail.v2.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2.Product] having the same
    // [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id].
    Interval price = 1;

    // The inclusive
    // [Product.pricing_info.original_price][google.cloud.retail.v2.PriceInfo.original_price]
    // internal of all [variant][google.cloud.retail.v2.Product.Type.VARIANT]
    // [Product][google.cloud.retail.v2.Product] having the same
    // [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id].
    Interval original_price = 2;
  }

  // The 3-letter currency code defined in [ISO
  // 4217](https://www.iso.org/iso-4217-currency-codes.html).
  //
  // If this field is an unrecognizable currency code, an INVALID_ARGUMENT
  // error is returned.
  //
  // The [Product.Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2.Product]s with the same
  // [Product.primary_product_id][google.cloud.retail.v2.Product.primary_product_id]
  // must share the same
  // [currency_code][google.cloud.retail.v2.PriceInfo.currency_code]. Otherwise,
  // a FAILED_PRECONDITION error is returned.
  string currency_code = 1;

  // Price of the product.
  //
  // Google Merchant Center property
  // [price](https://support.google.com/merchants/answer/6324371). Schema.org
  // property [Offer.priceSpecification](https://schema.org/priceSpecification).
  float price = 2;

  // Price of the product without any discount. If zero, by default set to be
  // the [price][google.cloud.retail.v2.PriceInfo.price].
  float original_price = 3;

  // The costs associated with the sale of a particular product. Used for gross
  // profit reporting.
  //
  // * Profit = [price][google.cloud.retail.v2.PriceInfo.price] -
  // [cost][google.cloud.retail.v2.PriceInfo.cost]
  //
  // Google Merchant Center property
  // [cost_of_goods_sold](https://support.google.com/merchants/answer/9017895).
  float cost = 4;

  // The timestamp when the [price][google.cloud.retail.v2.PriceInfo.price]
  // starts to be effective. This can be set as a future timestamp, and the
  // [price][google.cloud.retail.v2.PriceInfo.price] is only used for search
  // after
  // [price_effective_time][google.cloud.retail.v2.PriceInfo.price_effective_time].
  // If so, the
  // [original_price][google.cloud.retail.v2.PriceInfo.original_price] must be
  // set and [original_price][google.cloud.retail.v2.PriceInfo.original_price]
  // is used before
  // [price_effective_time][google.cloud.retail.v2.PriceInfo.price_effective_time].
  //
  // Do not set if [price][google.cloud.retail.v2.PriceInfo.price] is always
  // effective because it will cause additional latency during search.
  google.protobuf.Timestamp price_effective_time = 5;

  // The timestamp when the [price][google.cloud.retail.v2.PriceInfo.price]
  // stops to be effective. The [price][google.cloud.retail.v2.PriceInfo.price]
  // is used for search before
  // [price_expire_time][google.cloud.retail.v2.PriceInfo.price_expire_time]. If
  // this field is set, the
  // [original_price][google.cloud.retail.v2.PriceInfo.original_price] must be
  // set and [original_price][google.cloud.retail.v2.PriceInfo.original_price]
  // is used after
  // [price_expire_time][google.cloud.retail.v2.PriceInfo.price_expire_time].
  //
  // Do not set if [price][google.cloud.retail.v2.PriceInfo.price] is always
  // effective because it will cause additional latency during search.
  google.protobuf.Timestamp price_expire_time = 6;

  // Output only. The price range of all the child
  // [Product.Type.VARIANT][google.cloud.retail.v2.Product.Type.VARIANT]
  // [Product][google.cloud.retail.v2.Product]s grouped together on the
  // [Product.Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
  // [Product][google.cloud.retail.v2.Product]. Only populated for
  // [Product.Type.PRIMARY][google.cloud.retail.v2.Product.Type.PRIMARY]
  // [Product][google.cloud.retail.v2.Product]s.
  //
  // Note: This field is OUTPUT_ONLY for
  // [ProductService.GetProduct][google.cloud.retail.v2.ProductService.GetProduct].
  // Do not set this field in API requests.
  PriceRange price_range = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The rating of a [Product][google.cloud.retail.v2.Product].
message Rating {
  // The total number of ratings. This value is independent of the value of
  // [rating_histogram][google.cloud.retail.v2.Rating.rating_histogram].
  //
  // This value must be nonnegative. Otherwise, an INVALID_ARGUMENT error is
  // returned.
  int32 rating_count = 1;

  // The average rating of the [Product][google.cloud.retail.v2.Product].
  //
  // The rating is scaled at 1-5. Otherwise, an INVALID_ARGUMENT error is
  // returned.
  float average_rating = 2;

  // List of rating counts per rating value (index = rating - 1). The list is
  // empty if there is no rating. If the list is non-empty, its size is
  // always 5. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // For example, [41, 14, 13, 47, 303]. It means that the
  // [Product][google.cloud.retail.v2.Product] got 41 ratings with 1 star, 14
  // ratings with 2 star, and so on.
  repeated int32 rating_histogram = 3;
}

// Information of an end user.
message UserInfo {
  // Highly recommended for logged-in users. Unique identifier for logged-in
  // user, such as a user name.
  //
  // The field must be a UTF-8 encoded string with a length limit of 128
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  string user_id = 1;

  // The end user's IP address. Required for getting
  // [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
  // This field is used to extract location information for personalization.
  //
  // This field must be either an IPv4 address (e.g. "104.133.9.80") or an IPv6
  // address (e.g. "2001:0db8:85a3:0000:0000:8a2e:0370:7334"). Otherwise, an
  // INVALID_ARGUMENT error is returned.
  //
  // This should not be set when using the JavaScript tag in
  // [UserEventService.CollectUserEvent][google.cloud.retail.v2.UserEventService.CollectUserEvent]
  // or if
  // [direct_user_request][google.cloud.retail.v2.UserInfo.direct_user_request]
  // is set.
  string ip_address = 2;

  // User agent as included in the HTTP header. Required for getting
  // [SearchResponse.sponsored_results][google.cloud.retail.v2.SearchResponse.sponsored_results].
  //
  // The field must be a UTF-8 encoded string with a length limit of 1,000
  // characters. Otherwise, an INVALID_ARGUMENT error is returned.
  //
  // This should not be set when using the client side event reporting with
  // GTM or JavaScript tag in
  // [UserEventService.CollectUserEvent][google.cloud.retail.v2.UserEventService.CollectUserEvent]
  // or if
  // [direct_user_request][google.cloud.retail.v2.UserInfo.direct_user_request]
  // is set.
  string user_agent = 3;

  // True if the request is made directly from the end user, in which case the
  // [ip_address][google.cloud.retail.v2.UserInfo.ip_address] and
  // [user_agent][google.cloud.retail.v2.UserInfo.user_agent] can be populated
  // from the HTTP request. This flag should be set only if the API request is
  // made directly from the end user such as a mobile app (and not if a gateway
  // or a server is processing and pushing the user events).
  //
  // This should not be set when using the JavaScript tag in
  // [UserEventService.CollectUserEvent][google.cloud.retail.v2.UserEventService.CollectUserEvent].
  bool direct_user_request = 4;
}

// Promotion information.
message Promotion {
  // ID of the promotion. For example, "free gift".
  //
  // The value value must be a UTF-8 encoded string with a length limit of 128
  // characters, and match the pattern: [a-zA-Z][a-zA-Z0-9_]*. For example,
  // id0LikeThis or ID_1_LIKE_THIS. Otherwise, an INVALID_ARGUMENT error is
  // returned.
  //
  // Google Merchant Center property
  // [promotion](https://support.google.com/merchants/answer/7050148).
  string promotion_id = 1;
}