Feeds

message OffersFeed {
  repeated Offer data = 1;
}

// Definition of offers provided by merchants for their services.
message Offer {

  // An opaque string from an aggregator partner which uniquely identifies a
  // merchant. (required)
  // This merchant_id should match with the merchant_ids sent as part of
  // Merchant feed/Real Time Update (RTU).
  string merchant_id = 1;


  // An opaque string from an aggregator partner to identify a service of the
  // merchant where this offer applies.
  repeated string service_id = 3;

  // An opaque string from an aggregator partner to uniquely identify an offer.
  // (required)
  string offer_id = 4;

  // One sentence unlocalized, unstructured offer title (eg. 10% off food and
  // drink). (required)
  string unlocalized_title = 5;

  // Url associated with the offer. It should point to the webpage where this
  // offer is present in the most detailed way.
  string url = 6;

  // The image to be shown with the offer. The url should point directly to a
  // specific image, which almost always ends with jpg, gif, png, or bmp, rather
  // than pointing to an entire index or website.
  // The image should be at least 250 pixels in both width and height.
  string image_url = 7;

  // The specific offer's Terms and Conditions displayed to user.
  Terms terms = 8;

  // True if the offer is only redeemable only by a restricted group of users
  // (eg: paid members, certain credit card holders, etc.).
  bool restricted_to_certain_users = 9;

  // Valid_period and valid_time_of_week fields are used to specify the regular
  // availability of the offer. Valid_period represents the overarching date
  // range when the offer is valid, whereas valid_time_of_week fields represent
  // the recurring weekly schedule.
  // Then, valid_time_exception fields are used to represent special
  // schdule for times where the offer has alternative availability than the
  // regular schedule, such as special availability schedule during holidays.
  // To illustrate the relationship among these fields, we consider
  //   a time T is valid if and only if
  //      T is in valid_period AND
  //      ((T is in valid_time_of_week AND
  //        (valid_time_exception is not specified OR
  //         T is NOT in valid_time_exception)) OR
  //       T is in valid_time_exception)

  // TimeRange message is used to represent the overarching valid period of the
  // offer. It is a closed-open time range in seconds of UTC time since Unix
  // epoch. It should have the second of the date when the offer starts to be
  // valid as the start, and the second of the date when the offer starts to be
  // invalid as the end. Example: To specify that the offer is valid for the
  // entire year of 2019,
  //   valid_period { begin_sec: 1546300800 end_sec: 1577836800 }
  //
  // Note that because the valid period is closed-open, the end second is not
  // considered as within the valid period of this offer.
  // (required)
  TimeRange valid_period = 10;

  // This message stores the start and end time of a continuous valid time
  // interval of the offer at a given day of the week. It is used to
  // specify the recurrence availability of the offer on a weekly basis.
  // This time interval is a closed-open interval, i.e. [start, end)
  message ValidTimeOfWeek {
    // The day of week where the following valid time applies. (required)
    enum DayOfWeek {
      DAY_OF_WEEK_UNSPECIFIED = 0;
      MON = 1;
      TUE = 2;
      WED = 3;
      THU = 4;
      FRI = 5;
      SAT = 6;
      SUN = 7;
    }

    DayOfWeek day_of_week = 1;

    // Start time (inclusive) of this offer valid time interval, using seconds
    // from Midnight, in merchant's local timezone. Must be in the range
    // [0,86400). (required)
    int64 start = 2;

    // End time (exclusive) of this offer valid time interval, using seconds
    // from Midnight, in merchant's local timezone. Must be in the range
    // (0,86400]. (required)
    int64 end = 3;
  }

  // The valid time of the offer in merchant's local timezone, specified with
  // multiple continuous time intervals using the message above. For example, if
  // an offer is valid on Mondays from 11:30-13:00 plus 16:00-20:00, and on
  // Tuesdays from 12:00-23:00, you can specify the valid hours as follows:
  //   valid_time_of_week { day_of_week: MON start: 41400 end: 46800 }
  //   valid_time_of_week { day_of_week: MON start: 57600 end: 72000 }
  //   valid_time_of_week { day_of_week: TUE start: 43200 end: 82800 }
  //
  // Note that it is a close-open interval. It means that the offer would be
  // available for all booking slots whose start time is from, for example,
  // Monday 11:30 up to the last starting time before 13:00, but the offer would
  // not be available for the slot starting at Monday 13:00.
  //
  // If valid_time_of_week is not present, we consider the offer to be valid at
  // all time within the valid_period time range specified above.
  repeated ValidTimeOfWeek valid_time_of_week = 11;

  // This message represents the time periods when the offer has alternative
  // availability schedule than the regular one, such as special schedule during
  // holidays.
  message ValidTimeException {
    // The overarching time range of the exception in the same format
    // as the regular valid_period field above. It is a closed-open interval
    // specifying when the expectional_time_of_week below would apply, replacing
    // the regular valid_time_of_week schedule. (required)
    TimeRange exceptional_period = 1;

    // The weekly availability schedule to be applied for the time range
    // specified in the exceptional period above. It should be in the same
    // format as the regular valid_time_of_week field above. If not present, all
    // times within the exceptional_period will be considered as valid for the
    // offer.
    repeated ValidTimeOfWeek exceptional_time_of_week = 2;
  }

  // Exceptions to the regular recurring valid_time_of_week availability
  // schedule. If set, any regular valid_time_of_week within this
  // exceptional_period are ignored and replaced by the exceptional_time_of_week
  // specified.
  repeated ValidTimeException valid_time_exception = 12;

  // A number from 1-100 indicating the priority of the offer under the
  // specified merchant and service. 1 is the most important and 100 is the
  // least important. Offers with smaller priority numbers will be shown before
  // offers with larger priority numbers when they are equally available.
  int64 priority = 13;
}

// A closed-open time range, i.e. [begin_sec, end_sec)
message TimeRange {
  // Seconds of UTC time since Unix epoch (required)
  int64 begin_sec = 1;

  // Seconds of UTC time since Unix epoch (required)
  int64 end_sec = 2;
}

// A set of rules and guidelines that are displayed to the
// user in order to make a booking through Reserve with Google.
message Terms {
  // The URL to the Terms and Conditions. (optional)
  string url = 1;

  // The unlocalized text to be displayed to the user. (required)
  string unlocalized_text = 2;
}