Feeds

Definitions

Note: The Offers feed spec is defined in protobuffer format below, however we recommend uploading the feeds in JSON format. You can reference our JSON sample feeds for more information.

OffersFeed Definition

message OffersFeed {
  repeated Offer data = 1;
}

Offers Definition

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

TimeRange Definition

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

Terms Definition

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

Samples

Merchants

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "total_shards": 1,
    "nonce": "11203880",
    "generation_timestamp": 1524606581
  },
  "merchant": [
    {
      "category": "restaurant",
      "merchant_id": "merch1",
      "name": "Dining Eats",
      "url": "www.merchantspublicsite.com",
      "telephone": "[phone]",
      "geo": {
        "latitude": 37.422113,
        "longitude": -122.084041,
        "address": {
          "locality": "Mountain View",
          "country": "USA",
          "region": "CA",
          "street_address": "1600 Amphitheatre Pkwy",
          "postal_code": "94043"
        }
      }
    }
  ]
}

Services

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "total_shards": 1,
    "nonce": "11203880",
    "generation_timestamp": 1524606581
  },
  "service": [
    {
      "merchant_id": "1",
      "localized_service_name": {
        "value": "Reservation",
        "localized_value": [
          {
            "locale": "en",
            "value": "Reservation"
          }
        ]
      },
      "service_id": "1000",
      "prepayment_type": "NOT_SUPPORTED"
    },
    {
      "merchant_id": "2",
       "localized_service_name": {
         "value": "Reservation",
         "localized_value": [
           {
             "locale": "en",
             "value": "Reservation"
           }
        ]
      },
      "service_id": "1000",
      "prepayment_type": "NOT_SUPPORTED"
    }
  ]
}

Offers

{
  "data": [
    {
      "merchant_id": "1",
      "service_id": ["1000"],
      "offer_id": "discount_apps",
      "unlocalized_title": "Half off appetizers",
      "valid_period": {
        "begin_sec": 1546300800,
        "end_sec": 1577836800
      },
      "valid_time_of_week": [
        {
          "day_of_week": "MON",
          "start": 43200,
          "end": 61200
        },
        {
          "day_of_week": "TUE",
          "start": 43200,
          "end": 61200
        },
        {
          "day_of_week": "WED",
          "start": 43200,
          "end": 61200
        },
        {
          "day_of_week": "THU",
          "start": 43200,
          "end": 61200
        }
      ]
    }
  ]
}