Services feed

ServiceFeed Definition

message ServiceFeed {
  FeedMetadata metadata = 1;
  repeated Service service = 2;
}

Service Definition

// 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 from an aggregator partner which uniquely identifies the
  // service. (required)
  string service_id = 2;
  // The name of the service, e.g. "Men's haircut". Possibly in several locales.
  // (required)
  Text localized_service_name = 26;
  // The user-visible description of the service, possibly in several locales.
  // Populating service description is strongly recommended, but not strictly
  // required.
  //
  // This field now supports both plain-text and HTML-like formatting rules to
  // display structural contents to end-users. Unlike plain text sections,
  // customized layouts can be created here using headings, paragraphs, lists
  // and some phrase tags. Please read the following instructions and notes
  // carefully to ensure you create the best user-experience.
  //
  // Supported HTML-like formatting tags:
  //
  // Heading tags: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
  //   Heading tags can be used to display titles and sub-titles. For example,
  //   <h1>Itinerary</h1> will display the inline text as the most important
  //   heading of the section. Note that any inner HTML tags, styles or
  //   attributes will be ignored. For example, <h1 style=".."> will be treated
  //   the same as <h1>. Only pure text wil be preserved.
  //
  // Paragraph tag: <p>:
  //   The paragraph tag can be used to highlight a detailed introduction or
  //   contents. Any inner tags, styles or attributes will be ignored, with a
  //   few exceptions: <br>, <strong> and <em>. Please see the phrase tag
  //   section below for more details.
  //
  // List tags: <ul>, <ol>, <li>
  //   The <ul> tag can be used with the <li> tag to display unordered lists,
  //   and the <ol> tag can be used with <li> to display ordered lists. This is
  //   a good way to display checklists, highlights, or any other lists that fit
  //   your use-cases.
  // Example: To show a list of features of a cruise trip:
  //   <ol>
  //     <li>Wonderful ocean view and chances to play with wildlife.</li>
  //     <li>Carefully designed travel arrangements and services.</li>
  //     <li>Guaranteed lowest price.</li>
  //   </ol>
  // Note that only <li> children under <ul> or <ol> tags will be converted. All
  // other children will be dropped. Also, any inner tags, attributes and styles
  // will be ignored; we only preserve pure text contents.
  //
  // Division tag: <div>
  //   All supported inner tags of the <div> tag will be parsed with the rules
  //   stated above, imply <div> tag itself does not mean any grouping or
  //   indenting here. Also, any inner attributes and styles will be ignored.
  //
  // Phrase tags: <br>, <strong>, <em>:
  //   Only the three tags mentioned above are supported. <br> can be used to
  //   break lines in paragraphs, and <strong>/<em> can be used to highlight
  //   important text. Any other phrase tags will be ignored.
  //
  // Unsupported tags:
  //   * <html>, <header>, and <body> tags are not allowed.
  //   * Any other tags not mentioned above are not supported (for example
  //     <table>, <td> ...).
  // Any URLs, anchors, and links will be stripped, and will never be displayed
  // to end-users. If you want to use photos to create a rich user experience,
  // please use the "related_media" field below to send your photo URLs.
  //
  // Important notes:
  //   * Try not to use other tags except for the supported ones mentioned
  //     above, because the contents within unsupported tags will be stripped,
  //     and may lead to an undesirable user experience.
  //   * Try avoid deep nested structures like more than 3 different heading
  //     levels or nested lists. Keeping the structure flat, simple, and
  //     straightforward, helps to create a better user experience.
  //   * If the currently supported layouts are not sufficient for your use
  //     cases, please reach out to the Reserve with Google team.
  //   * The recommended maximum size is 32,000 characters.
  //
  // <EPA: REQUIRED>
  Text localized_description = 27;
  // The price of the service. (optional, overridden when payment options or
  // ticket types present)
  // <EPA: REQUIRED>
  Price price = 5;
  // Describes how the price is interpreted and displayed to the user. Can be
  // used by any vertical except Dining and Things To Do to configure display of
  // the service price. (optional)
  // <EPA: REQUIRED>
  PriceInterpretation price_interpretation = 23;
  // Rules to book/cancel an appointment. (optional)
  SchedulingRules rules = 6;

  // An action link related to this service. If action link exists, type (see
  // below) must be set in the Service.
  // <EPA: REQUIRED>
  repeated ActionLink action_link = 14;

  enum ServiceType {
    SERVICE_TYPE_UNSPECIFIED = 0;
    // Service that provides dining reservation.
    SERVICE_TYPE_DINING_RESERVATION = 1;
    // Service that provides food ordering in general, could be either takeout
    // or delivery or both.
    SERVICE_TYPE_FOOD_ORDERING = 2;
    // Service that only provides food delivery.
    SERVICE_TYPE_FOOD_DELIVERY = 6;
    // Service that only provides food takeout.
    SERVICE_TYPE_FOOD_TAKEOUT = 7;

    // Services that provide event based ticketing (e.g. concerts, sporting
    // events, shows). Do not use for Reserve with Google integrations.
    SERVICE_TYPE_EVENT_TICKET = 3;
    SERVICE_TYPE_TRIP_TOUR = 4;

    // Service that provides appointments or classes. Recommended for (1) health
    // and fitness, (2) spa and beauty, and (3) financial consults and
    // evaluations services. Please see the supported service types:
    // https://developers.google.com/maps-booking/guides/end-to-end-integration/overview
    SERVICE_TYPE_APPOINTMENT = 5;
    // Service that provides appointment for an online class or session which
    // will be fully virtual. Must be set if enabling virtual service bookings.
    SERVICE_TYPE_ONLINE_APPOINTMENT = 8;

    // Service that allows users to shop from the given merchant. It could
    // either be delivery or pickup.
    SERVICE_TYPE_SHOPPING = 9;
  }

  // The predefined type of this service. (optional)
  ServiceType type = 15;

  // Photos related to this service. Google will crawl these media to ensure
  // that they are displayed correctly to end-users. (optional)
  repeated RelatedMedia related_media = 17;

  // Service attribute values that apply to this service.
  // Each Service may have zero or more values for each service attribute
  // defined in the corresponding Merchant.
  // <EPA: REQUIRED (Category)>
  repeated ServiceAttributeValueId service_attribute_value_id = 18;

  // Depth of integration we support for this service. (optional)
  // Irrelevant for partners with the starter integration. End to end will
  // always be disabled for these partners.
  IntegrationType integration_type = 24;

  // User rating for this service as an aggregate metric over all reviews.
  // <EPA: Optional>
  Rating rating = 30;

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

Price Definition

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

PriceInterpretation Definition

// Describes how a Price should be interpreted and displayed to the user.
enum PriceInterpretation {
  // Price interpretation unspecified, defaults to EXACT_AMOUNT.
  PRICE_INTERPRETATION_UNSPECIFIED = 0;

  // When the price should be interpreted as a specific value.
  //
  // Examples:
  //   $20 for a yoga class; $15 for a child haircut
  EXACT_AMOUNT = 1;

  // When the price of a service is variable but a minimum price is known and
  // displayed to consumers. Consumers may make choices which increase the
  // price.
  //
  // Note that any service that uses this PriceInterpretation must use
  // PrepaymentType NOT_SUPPORTED.
  //
  // Examples:
  //   $30 for dog grooming, but additional consumer choices may increase the
  //   price
  STARTS_AT = 2;

}

Text Definition

// A possibly-localized text payload. Some Text fields may contain marked-up
// content.
message Text {
  // Required. 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.
  string value = 1;

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

LocalizedString Definition

// 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/.
  string locale = 1;

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

SchedulingRules Definition

// The scheduling rules for a service.
message SchedulingRules {
  // The duration (in seconds) from when the last booking can be made to
  // when the availability slot starts or ends.
  //
  // If "min_advance_booking" is set, the last bookable time is calculated as
  // (<slot start time> - "min_advance_booking").
  // If "min_booking_buffer_before_end_time" is set, the last bookable time is
  // calculated as (<slot end time> - "min_booking_buffer_before_end_time").
  // Note that the value of "min_booking_buffer_before_end_time" must be
  // positive if set.
  // If both are unset, the slot is bookable until the slot begin time. If both
  // fields are set, only one value will be picked while the other value
  // ignored--we cannot reliably predict which value is chosen.
  //
  // Examples:
  //  * A haircut that needs to be booked at least 1 hour before the start time.
  //      'scheduling_rules{ min_advance_booking: 3600 ...}`
  //
  //  * A museum where the last ticket can be purchased 30 mins before closing:
  //     'scheduling_rules{ min_booking_buffer_before_end_time: 1800 ...}'
  //
  //  * A movie ticket that needs to be purchased before the start time.
  //        'scheduling_rules{ ...}' (leave this field empty)
  // (optional)
  oneof min_booking_buffer {
    // The duration (in seconds) from when the last booking can be made to
    // when the availability slot starts.
    int64 min_advance_booking = 1;

    // The duration (in seconds) from when the last booking can be made to
    // when the availability slot ends. If this field is set, the
    // "admission_policy" field must be set to TIME_FLEXIBLE to indicate that
    // users can use the purchased tickets after slots start.
    int64 min_booking_buffer_before_end_time = 6;
  }

  // The minimum advance notice in seconds required to cancel a booked
  // appointment online. (optional)
  int64 min_advance_online_canceling = 2;

  // The fee for canceling within the minimum advance notice period.
  Price late_cancellation_fee = 3 [deprecated = true];

  // The fee for no-show without canceling.
  Price noshow_fee = 4 [deprecated = true];

  // The admission policy of this service.
  enum AdmissionPolicy {
    // Unused.
    ADMISSION_POLICY_UNSPECIFIED = 0;

    // Customers are required to be present at the start time of the
    // availability slot, and the service is expected to finish at the
    // end time of the slot.
    // Examples of TIME_STRICT use cases:
    //   * A tour that starts at 9am that requires all attendees to arrive
    //     at the start time, and returns at around 12pm.
    //   * A haircut reservation at 3pm on Saturday that will take approximately
    //   30 minutes.
    //   * A fitness class from 6pm to 8pm.
    TIME_STRICT = 1;

    // Customers can arrive at any time between the start and end time of the
    // availability slot to use this booking.
    //
    // Examples of TIME_FLEXIBLE use cases:
    //   * A museum ticket that can be used during any time on the purchase
    //     date.
    //   * An afternoon admission to an amusement park that can be used from
    //     12pm to 9pm.
    TIME_FLEXIBLE = 2;

    // Customers need to arrive at the merchant at the start time of the
    // availability slot but can leave any time they want.
    //
    // For example, in the museum admission scenario, a timed entry ticket
    // for 10am requires the user to be at the museum at 10am. The start time of
    // availability slots for this service represents the designated entry
    // time. The end time, however, is used solely as a key to identify the
    // availability slot for booking.
    TIMED_ENTRY_WITH_FLEXIBLE_DURATION = 3;
  }

  // The admission policy that applied to this service. If unset, defaults to
  // TIME_STRICT. (optional)
  AdmissionPolicy admission_policy = 5;

  // Scheduling rules cancellation policy (required for Things-to-do).
  // Defaults to non-refundable.
  CancellationPolicy cancellation_policy = 7;
}

CancellationPolicy Definition

// Cancellation policy for a service.
message CancellationPolicy {
  // Defines a single refund condition. Multiple refund conditions could be
  // used together to describe "refund steps" as various durations before the
  // service start time.
  message RefundCondition {
    // Duration in seconds before the start time, until when the customer can
    // receive a refund for part of the service's cost specified in
    // `refund_percent`.
    // When set to 0 (default), the service can be cancelled at any time.
    int64 min_duration_before_start_time_sec = 1;

    // The percent that can be refunded, as long as the service booking is
    // cancelled at least `min_duration_before_start_time` before the service
    // start time, in the range of [0, 100]. When set to 0 (default), the
    // service is not refundable. When set to 100 this service is fully
    // refundable.
    uint32 refund_percent = 2;
  }
  // Zero or more refund conditions applicable to the policy.
  repeated RefundCondition refund_condition = 1;
}

Rating Definition

// Defines Rating for an entity.
message Rating {
  // Average rating value (required when number_of_ratings > 0).
  // The value must be in the range of [1, 5] and can be omitted if and only if
  // the number_of_ratings is zero.
  double value = 1;

  // Number of ratings used in calculating the value (required).
  uint64 number_of_ratings = 2;
}
// An action URL with associated language, list of countries restricted to, and
// optional platform that indicates which platform this action should be
// performed on.
message ActionLink {
  // The entry point URL for this action link.
  string url = 1;

  // The BCP-47 language tag identifying the language in which the content
  // from this URI is available.
  string language = 2;

  // An unordered list of ISO 3166-1 alpha-2 country codes. Leave empty for
  // unrestricted visibility.
  repeated string restricted_country = 3;

  // The platform that this action should be performed on. If this field is
  // unset, ACTION_PLATFORM_WEB_APPLICATION will be used as fallback.
  ActionPlatform platform = 4;

  // Predetermined type of action associated with an action link.
  enum ActionLinkType {
    // The action link type is unspecified.
    ACTION_LINK_TYPE_UNSPECIFIED = 0;
    // The action link type is booking an appointment.
    ACTION_LINK_TYPE_BOOK_APPOINTMENT = 1;
    // The action link type is booking an online appointment.
    ACTION_LINK_TYPE_BOOK_ONLINE_APPOINTMENT = 2;
    // The action link type is ordering food for delivery or takeout or both.
    ACTION_LINK_TYPE_ORDER_FOOD = 3;
    // The action link type is ordering food for delivery.
    ACTION_LINK_TYPE_ORDER_FOOD_DELIVERY = 4;
    // The action link type is ordering food for takeout.
    ACTION_LINK_TYPE_ORDER_FOOD_TAKEOUT = 5;
    // The action link type is making a dining reservation.
    ACTION_LINK_TYPE_MAKE_DINING_RESERVATION = 6;
    // The action link type allows users to shop from the given merchant. It
    // could either be delivery or pickup.
    ACTION_LINK_TYPE_SHOP_ONLINE = 7;
  }

  // Predetermined type of action associated with an action link.
  ActionLinkType action_link_type = 5;

  // Metadata for the order online link.
  // Supports action with ActionLinkType of ACTION_LINK_TYPE_SHOP_ONLINE.
  OrderOnlineMetadata order_online_metadata = 6;

  // Metadata for Food Ordering links.
  // Supports action type:
  //   *  `ACTION_LINK_TYPE_ORDER_FOOD_DELIVERY`
  //   *  `ACTION_LINK_TYPE_ORDER_FOOD_TAKEOUT`
  // Does NOT support `ACTION_LINK_TYPE_ORDER_FOOD`
  FoodOrderingMetadata food_ordering_metadata = 7
      // ...
      ;
}

ActionPlatform Definition

// The platform that the action is performed on. Web application is the general
// fallback. It is recommended to have at least one ActionLink with
// ACTION_PLATFORM_WEB_APPLICATION. Links with Android and iOS as platform are
// only used on the respective system.
enum ActionPlatform {
  // The platform is unspecified.
  ACTION_PLATFORM_UNSPECIFIED = 0;

  // The action platform is web in general.
  ACTION_PLATFORM_WEB_APPLICATION = 1;

  // The action platform is web on mobile devices.
  ACTION_PLATFORM_MOBILE_WEB = 2;

  // The action platform is Android OS.
  ACTION_PLATFORM_ANDROID = 3;

  // The action platform is iOS.
  ACTION_PLATFORM_IOS = 4;
}

ServiceAttributeValueId Definition

// Identifies a particular value of a service attribute to be applied to a
// Service.
message ServiceAttributeValueId {
  // ID of an attribute as defined in Merchant.service_attribute, e.g.
  // "service-type".
  string attribute_id = 1;

  // ID of the value for this attribute, e.g. "haircut". Must match a value_id
  // in the service attribute definition.
  string value_id = 2;
}

IntegrationType Definition

// Depth of integration supported.
enum IntegrationType {
  // Defaults to END_TO_END.
  INTEGRATION_TYPE_UNSPECIFIED = 0;
  // Complete integration that allows end to end booking through Google.
  INTEGRATION_TYPE_END_TO_END = 1;
  // Feed integration that does not allow end to end booking through Google.
  // Only merchants, services, and (optionally) availability data need
  // to be sent.
  INTEGRATION_TYPE_INVENTORY_ONLY = 2;
}

ServiceRankingHint Definition

// Ranking hints for a service.
message ServiceRankingHint {
  // Arbitrary partner or merchant assigned rank for this service.
  //
  // Services with a higher score will be shown more prominently (e.g. shown
  // higher in lists). Note that other factors may also influence ranking, such
  // as price, availability, user history, etc.
  //
  // Optional. Must be non-negative if set.
  optional float score = 1;
}