Services feed

message ServiceFeed {
  repeated Service data = 1;
}

// The definition of a service provided by a merchant.
message Service {
  // An opaque string from an aggregator partner which uniquely identifies a
  // merchant.
  // Required.
  string merchant_id = 1;

  // An opaque string of ASCII characters from an aggregator partner which
  // uniquely identifies the service.
  // Must be equal to or shorter than 100 characters.
  // Required.
  string service_id = 2;

  // The name of the service, e.g. "Men's haircut". Possibly in several locales.
  // Required.
  Text localized_service_name = 3;

  // The name of the service category, e.g. "Haircut", "Shave", "Color".
  // Possibly in several locales. The category will be used to group services
  // when presented to the consumer.
  // Note: For merchants without categories on your website, you can group all
  // services into one category and use a generic name such as "All Services"
  // or "General." Merchants who have categories you should try to replicate
  // those categories.
  // Required.
  Text localized_service_category = 4;

  // The user-visible description of the service, possibly in several locales.
  // This field is not required for every services, but is strongly
  // recommended to be filled when available.
  // Important notes:
  //   * The recommended maximum size is 2,000 characters.
  // Optional.
  Text localized_service_description = 5;

  // The price of the service.
  // Note, if a service (or merchant) doesn't provide price up front, use
  // RangeInterpretation.INTERPRETATION_NOT_DISPLAYED as PriceInterpretation.
  // Required.
  ServicePrice service_price = 6;

  // An action link related to this service. Action link should deep link to the
  // 3P page with the preselected service.
  // Note: Only the first entry will be used. Other provided action links will
  // be ignored.
  // Optional, but highly recommended if service-level deep links are supported.
  // This enables service-level entrypoints on Google if provided.
  // Note: For merchants participating in Healthcare vertical should not provide
  // service-level deep link.
  repeated ActionLink action_link = 8;

  // Duration of the service.
  // Note, if a service (or merchant) doesn't provide service duration, use
  // RangeInterpretation.INTERPRETATION_NOT_DISPLAYED as DurationInterpretation.
  // Required.
  ServiceDuration service_duration = 9;

  // Ranking hint for this service.
  // Optional.
  ServiceRankingHint ranking_hint = 10;
}

// A possibly-localized text payload. Some Text fields may contain marked-up
// content.
message Text {
  // Text value in an unknown locale, which will be displayed if
  // `localized_value` for the user locale is empty or missing. The locale for
  // this value may depend on the partner or service provider, and it should not
  // be assumed to be any specific language.
  // Required.
  string value = 1;

  // Per-locale text values.
  // Optional.
  repeated LocalizedString localized_value = 2;
}

// Describes how a range of values should be interpreted and displayed to the
// user.
enum RangeInterpretation {

  // When range represents an exact value (such that min value equals to max)
  // Will be interpreted as a specific value.
  //
  // Examples:
  //   $20 for a yoga class; 50 min haircut duration
  INTERPRETATION_EXACT = 1;

  // When only minimum of the range is known and displayed to consumers.
  // The maximum value will be decided based on other configurations
  // (e.g., price may go up if consumer selecting add-ons)
  //
  // Examples:
  //   $30 for dog grooming, but additional consumer choices may increase the
  //   price
  //   40 min massage, but there are also options for extending the time.
  INTERPRETATION_STARTS_AT = 2;

  // When the range is variable and both minimum and maximum values are known
  // and displayed to consumers.
  //
  // Examples:
  //   $30 - $60 for dog grooming, the exact price will depend on additional
  //   consumer choices.
  //   1 - 3 hour hair color service.
  INTERPRETATION_RANGE = 3;

  // When the range is variable and no min value is known. No information is
  // displayed to consumers ahead of time.
  //
  // Examples:
  //   A consultation for a home service
  INTERPRETATION_NOT_DISPLAYED = 4;
}

// The price of a service.
message ServicePrice {
  // Describes how a Price should be interpreted and displayed to the user.
  RangeInterpretation price_interpretation = 1;

  // The minimum price of the service. Must be set if price_interpretation is
  // set to EXACT, STARTS_AT, or RANGE.
  // price is known.
  // Required.
  Price min_price = 2;

  // The maximum price of the service. Must be set if price_interpretation is
  // set to RANGE.
  // Optional.
  Price max_price = 3;
}

// The price of a service or a fee.
message Price {
  // The price in micro-units of the currency.
  // For example: 1.95 USD is 1950000 in micro-units.
  // If your price contains fractions of the smallest currency unit, then it
  // will be rounded using nearest even rounding (e.g. 2.5 cents rounded
  // to 2 cents, 3.5 cents rounded to 4 cents, 0.5 cents rounded to 0 cents,
  // 2.51 cents rounded to 3 cents).
  // Required.
  int64 price_micros = 1;

  // The currency of the price that is defined in ISO 4217.
  // Required.
  string currency_code = 2;

  // An optional and opaque string that identifies the pricing option that is
  // associated with the extended price.
  // Optional.
  string pricing_option_tag = 3;
}

// An action URL for a service.
message ActionLink {

  // The entry point URL for this action link.
  // Required.
  string url = 1;
}

message ServiceDuration {
  // Describes how a service duration should be interpreted and displayed to
  // the user.
  // Note, if a service (or merchant) doesn't provide service duration, use
  // 'INTERPRETATION_NOT_DISPLAYED' as DurationInterpretation.
  // Required.
  RangeInterpretation duration_interpretation = 1;

  // The minimum duration (in seconds) that the service may take. Must be set
  // if duration_interpretation is set to EXACT, STARTS_AT, or RANGE.
  // Required.
  int64 min_duration_sec = 2;

  // The maximum duration (in seconds) that the service may take. Must be set
  // if duration_interpretation is set to RANGE.
  // Optional.
  int64 max_duration_sec = 3;
}

// Ranking hints for a service.
message ServiceRankingHint {
  // Arbitrary partner or merchant assigned rank for this service.
  //
  // Services with a lower score will be displayed more prominently (e.g.
  // displayed higher in lists).
  //
  // Ranking hints affect both the ordering of services within a service
  // category, and the ordering of the categories themselves. The ranking hint
  // for a category is assumed to be the minimum ranking hint of any item in the
  // category. Note that other factors may also influence the final ranking,
  // such as price, user history, etc.
  //
  // The recommended approach is to define a total ordering on all the services,
  // by assigning each one a unique integer ranking hint and ensuring that
  // ranking hint values don’t overlap between categories. For example, if we
  // want the preferred ordering of categories and services to be:
  // Category 1: A, B, C
  // Category 2: D, E, F
  // Then the simplest ranking hint scheme to indicate this would be:
  // A=1, B=2, C=3, D=4, E=5, F=6.
  //
  // Optional. Must be non-negative if set.
  float score = 1 [features.field_presence = EXPLICIT];
}

// Instance of a string in one locale.
message LocalizedString {
  // IETF BCP 47 language code, such as "en", "mas", "zh-Hant", "de-CH-1901".
  // See http://www.w3.org/International/articles/language-tags/.
  // Required.
  string locale = 1;

  // Message in the locale above (UTF-8).
  // Required.
  string value = 2;
}