Availability Feed Samples and Definitions

Availability Feed sample

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 1,
    "nonce": "11203880",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 6
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 5
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 4
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
         {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 3
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
         {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 2
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535853600,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 1
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 6
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 5
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
       {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 4
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 3
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 2
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "reservation",
          "start_sec": 1535855400,
          "merchant_id": "dining-1",
          "resources": {
            "party_size": 1
          },
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

Definitions

Note: Upload a complete availability inventory Feed every day. Mark this feed as PROCESS_AS_COMPLETE.

Note: The Availability Feed specification is defined in the following protocol buffer format. However, we recommend you to upload the feeds in JSON format. For more information, see JSON sample Feeds.

AvailabilityFeed definition

message AvailabilityFeed {
  FeedMetadata metadata = 1;
  repeated ServiceAvailability service_availability = 2;
}

ServiceAvailability definition

message ServiceAvailability {
  // If provided, we will consider the Availability entities provided to be a
  // complete snapshot from [start_timestamp_restrict, end_timestamp_restrict).
  // That is, all existing availability will be deleted if the following
  // condition holds true:
  //
  //    start_timestamp_restrict <= Availability.start_sec &&
  //    Availability.start_sec < end_timestamp_restrict
  //
  // If a duration message is set, the condition is further restricted:
  //   Availability.duration == duration_restrict_sec
  //
  // If a resource_restrict message is set, the condition is further restricted:
  //
  //    Availability.resource.staff_id == resource_restrict.staff_id &&
  //    Availability.resource.room_id == resource_restrict.room_id
  //
  // These fields are typically used to provide a complete update of
  // availability in a given time range.
  //
  // Setting start_timestamp_restrict while leaving end_timestamp_restrict unset
  // is interpreted to mean all time beginning at start_timestamp_restrict.
  //
  // Setting end_timestamp_restrict while leaving start_timestamp_restrict unset
  // is interpreted to mean all time up to the end_timestamp_restrict.
  //
  // In Unix time format (seconds since the epoch) from UTC. (both optional)
  int64 start_timestamp_restrict = 1;
  int64 end_timestamp_restrict = 2;

  // If provided, the timestamp restricts will be applied only to the given
  // merchant or service.
  //
  // These fields are typically used to provide complete snapshot of
  // availability in a given range (defined above) for a specific merchant or
  // service.
  //
  // Leaving these fields unset, or setting these to the empty string or null,
  // is interpreted to mean that no restrict is intended. (both optional)
  string merchant_id_restrict = 3;
  string service_id_restrict = 4;

  // Setting duration further restricts the scope of the update to just the
  // availability with matching duration.
  //
  // In seconds. (optional)
  int64 duration_restrict_sec = 7;

  // Setting resources_restrict further restricts the scope of the update to
  // just this set of resources. All id fields of the resources must match
  // exactly. (optional)
  Resources resources_restrict = 6;

  // All Availability Slots included in this Service Availability (required)
  repeated Availability availability = 5;
}

Availability definition

// An availability of the merchant's service, indicating time and number
// of spots.
// The availability feed should be a list of this message.
// Please note that it's up to the partner to call out all the possible
// availabilities.
// If a massage therapist is available 9am-12pm, and they provide
// one-hour massage sessions, the aggregator should provide the feed as
//   availability {start_sec: 9am, duration: 60 minutes, ...}
//   availability {start_sec: 10am, duration: 60 minutes, ...}
//   availability {start_sec: 11am, duration: 60 minutes, ...}
// instead of
//   availability {start_sec: 9am, duration: 180 minutes, ...}
//
message Availability {
  // An opaque string from an aggregator to identify a merchant. (required)
  string merchant_id = 1;

  // An opaque string from aggregator to identify a service of the
  // merchant. (required)
  string service_id = 2;

  // Start time of this availability, using epoch time in seconds in UTC.
  //(required)
  int64 start_sec = 3;

  // Duration of the service in seconds, e.g. 30 minutes for a chair massage.
  // (required)
  int64 duration_sec = 4;

  // Number of total spots and open spots of this availability.
  // E.g. a party_size of 4 of 10 spots with 3 booked.
  //   availability {spots_total: 10, spots_open: 7 ...}
  // E.g. a party_size of 10 which was already booked.
  //   availability {spots_total: 1, spots_open: 0 ...}
  //
  int64 spots_total = 5;
  int64 spots_open = 6;

  // An optional opaque string to identify this availability slot. If set, it
  // will be included in the requests that book/update/cancel appointments.
  // (optional)
  string availability_tag = 7;

  // Optional resources used to disambiguate this availability slot from
  // others when different room or party_size values are part
  // of the service.
  //
  // E.g. party size of 2 with different seating sections.
  //  availability { resources { party_size: 2 room_id: "patio" room_name: "Garden Patio" }
  //                 spots_total: 10 spots_open: 7 }
  //  availability { resources { party_size: 2 }
  //                 spots_total: 5 spots_open: 2 }
  // (optional)
  Resources resources = 8;

  // Availability level scheduling rules.
  message SchedulingRuleOverrides {
    // The last time (in seconds) that this slot is able to be booked. This
    // timestamp must be before the start_sec of the slot to be respected
    // (if users should be able to book after the start time, use service level
    // SchedulingRules.min_booking_buffer_before_end_time). If present, will
    // override anything specified in the min_booking_buffer of the
    // corresponding Service's SchedulingRules.
    int64 last_bookable_sec = 1;

    // The first time (in seconds) that this slot is able to be booked.
    int64 first_bookable_sec = 2;

    // If set, the last time (in seconds since the Unix epoch) that this
    // specific appointment slot can be cancelled through Reserve with Google.
    // This field will override any service-level cancellation rules. (optional)
    int64 last_online_cancellable_sec = 3;
  }

  // Availability scheduling rules. If fields are populated, they will override
  // any corresponding scheduling rules on the service-level SchedulingRules.
  SchedulingRuleOverrides scheduling_rule_overrides = 16;

  // This enum indicates what requirements exist for the user to
  // acknowledge or view the requested slots duration/end time.
  enum DurationRequirement {
    // The handling of the end time is not specified. This is the default.
    DURATION_REQUIREMENT_UNSPECIFIED = 0;

    // The end time is not shown to the user.
    DO_NOT_SHOW_DURATION = 1;

    // The end time has to be shown to the user before an appointment can be
    // made.
    MUST_SHOW_DURATION = 2;
  }

  // The requirement to show the slots duration and/or endtime.
  // This field will be ignored if the slot is unavailable. Not used in the
  // Things-To-Do vertical. (optional)
  DurationRequirement duration_requirement = 18;

  // The confirmation modes used when booking availabilities.
  enum ConfirmationMode {
    // The confirmation mode was not specified.
    // Synchronous confirmation will be assumed.
    CONFIRMATION_MODE_UNSPECIFIED = 0;
    // Bookings for this availability will be confirmed synchronously.
    CONFIRMATION_MODE_SYNCHRONOUS = 1;
    // Bookings for this availability will be confirmed asynchronously.
    CONFIRMATION_MODE_ASYNCHRONOUS = 2;
  }
  // The confirmation mode that will be used when booking this availability.
  // Attempts to create bookings for availabilities with a confirmation mode
  // of CONFIRMATION_MODE_SYNCHRONOUS must be immediatlely confirmed or denied.
  // Attempts to create bookings for availabilities with confirmation mode
  // of CONFIRMATION_MODE_ASYNCHRONOUS must be either immediately denied
  // or created with status PENDING. Populating confirmation_mode is strongly
  // recommended, but not strictly required. (optional)
  ConfirmationMode confirmation_mode = 17;

  }

Resources definition

// A resource is used to disambiguate availability slots from one another when
// different staff, room or party_size values are part of the service.
// Multiple slots for the same service and time interval can co-exist when they
// have different resources.
message Resources {
  // party_size is required
  // room_id and room_name are optional

  // An optional ID for the room the service is located in. This field
  // identifies the room across all merchant, services, and availability
  // records. It also needs to be stable over time to allow correlation with
  // past bookings. (optional but required if room_name is present)
  string room_id = 3;

  // An optional name for the room the service is located in. This
  // field will be displayed to users making a booking, and should be human
  // readable, as opposed to an opaque identifier. (optional but required if
  // room_id is present)
  // In dining a room name should only be used for seating areas such as the
  // bar or patio and should not be used for fixed price menus, special
  // activities, or any other non-room value (such as reservation or dinner).
  // It is strongly recommended that the default seating area not have a room
  // associated with it. (used with room_id)
  string room_name = 4;

  // Applicable only for Dining: The party size that can be accommodated
  // during this time slot. A restaurant can be associated with multiple Slots
  // for the same time, each specifying a different party_size, if for instance
  // 2, 3, or 4 people can be seated with a reservation. (required)
  int32 party_size = 5;

}

SchedulingRuleOverrides

SchedulingRuleOverrides lets you set a duration that prevents an availability slot from being shown in the booking flow before or after the duration has passed.

The minimum booking buffer lets you to set durations as follows:

Field	Description
last_bookable_sec	The duration in seconds when you can make the last booking for the slot.
first_bookable_sec	The duration in seconds when you can make the first booking for the slot.
last_online_cancellable_sec	The minimum advance notice in seconds required to cancel a booked appointment online.

Resource definition policies

For Dining Reservations End-to-End integrations, you must define the resources for each available slot. This is the standard party_size of the slot which is required, but it can also include room names. Room names surface to the booking flow and let you distinguish between a party of four in the main seating area of a venue versus the outside patio. You can make the dining seating section for group reservation distinguishable either by room name or by experience. For more information, see Add dining seating sections.

Note: If you need to define a room_name, then you need to set a room_id.