// API v3 public interface declaration
syntax = "proto3";
package ext.maps.booking.partner.v3;
// +------+------------------------------+----------------------------------+
// | Verb | HTTP Path | Request/Response Body |
// +------+------------------------------+----------------------------------+
// | GET | /v3/HealthCheck | - |
// | | | - |
// +------+------------------------------+----------------------------------+
// | POST | /v3/BatchGetWaitEstimates | BatchGetWaitEstimatesRequest |
// | | | BatchGetWaitEstimatesResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/CreateWaitlistEntry | CreateWaitlistEntryRequest |
// | | | CreateWaitlistEntryResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/GetWaitlistEntry | GetWaitlistEntryRequest |
// | | | GetWaitlistEntryResponse |
// +------+------------------------------+----------------------------------+
// | POST | /v3/DeleteWaitlistEntry | DeleteWaitlistEntryRequest |
// | | | google.protobuf.Empty |
// +------+------------------------------+----------------------------------+
// BatchGetWaitEstimates method
// Batch request for the wait estimates for the specified merchant, service and
// party sizes.
message BatchGetWaitEstimatesRequest {
// Required. Partner-provided ID for the merchant.
string merchant_id = 1;
// Required. Partner-provided ID for the service.
string service_id = 2;
// Required. The different party sizes WaitEstimates are requested for.
// WaitEstimates may differ with the number of people in the party. A single
// request will not include duplicate party sizes.
repeated int32 party_size = 3;
}
// Response for the BatchGetWaitEstimates RPC with the wait estimates of the
// specified merchant, service and party sizes.
message BatchGetWaitEstimatesResponse {
// Required. A status for the waitlist that indicates whether new users can
// join and what the reason is if they can’t join. If the waitlist is not
// open, all other fields in the BatchGetWaitEstimatesResponse are expected to
// be unset.
WaitlistStatus waitlist_status = 1;
// The wait estimates for each party size requested. The response should
// contain exactly one wait estimate for each party size sent in the request.
// If a party size is not available for some reason, prefer ommitting it
// instead of returning an error so that the user will have some options to
// choose from.
repeated WaitEstimate wait_estimate = 2;
}
// A status for the waitlist that determines if new users can join and what
// the reason is if they can’t join.
enum WaitlistStatus {
WAITLIST_STATUS_UNSPECIFIED = 0;
// The waitlist is open and is accepting new users.
OPEN = 1;
// There is currently no wait and users should arrive at the merchant
// without joining the waitlist.
CLOSED_NO_WAIT = 2;
// The waitlist is not currently accepting new users because it is full
// or closed for other reasons.
CLOSED_OTHER = 3;
}
// The range of time for the current estimated seat time for the user. Estimated
// seat time range must change over time when the merchant or partner updates
// their estimates.
message EstimatedSeatTimeRange {
// Required. The lower bound for the range. Expressed as the number of seconds
// since the Unix epoch.
int64 start_seconds = 1;
// Required. The upper bound for the range. Expressed as the number of seconds
// since the Unix epoch.
int64 end_seconds = 2;
}
// Contains fields measuring how long (in time or # of people) until the
// user is ready to leave the waitlist and be seated.
message WaitLength {
// The count of how many other parties are ahead of the user in the waitlist.
// parties_ahead_count must change over time as parties ahead
// in the waitlist are seated or leave the waitlist. Either
// parties_ahead_count or estimated_seat_time_range must be populated. Both
// should be populated.
int32 parties_ahead_count = 1;
// The range of time that the user is estimated to be seated in. Either
// parties_ahead_count or estimated_seat_time_range must be populated. Both
// should be populated.
EstimatedSeatTimeRange estimated_seat_time_range = 2;
}
// The confirmation modes used when joining the waitlist.
enum WaitlistConfirmationMode {
// The confirmation mode was not specified.
// Synchronous confirmation will be assumed.
WAITLIST_CONFIRMATION_MODE_UNSPECIFIED = 0;
// Waitlist entries will be confirmed synchronously.
WAITLIST_CONFIRMATION_MODE_SYNCHRONOUS = 1;
// Waitlist entries will be confirmed asynchronously.
WAITLIST_CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}
// The wait estimate for a particular party size, merchant and service.
message WaitEstimate {
// Required. The party size this wait estimate applies to.
int32 party_size = 1;
// Required. Contains fields measuring how long (in time or # of people) until
// the user is ready to leave the waitlist and be seated.
WaitLength wait_length = 2;
// Required. Indicates whether waitlist entries for this wait estimate will be
// confirmed synchronously or asynchronously. An UNSPECIFIED value will be
// interpreted as synchronous.
WaitlistConfirmationMode waitlist_confirmation_mode = 3;
}
// CreateWaitlistEntry method
// Request for a user to join the waitlist.
//
// Reserve with Google may retry REST HTTP requests if no response is
// received. If the exact same CreateWaitlistEntry is received a second time,
// then the same CreateWaitlistResponse must be returned. A second waitlist
// entry must not be created.
message CreateWaitlistEntryRequest {
// Required. Partner-provided ID for the merchant.
string merchant_id = 1;
// Required. Partner-provided ID for the service.
string service_id = 2;
// Required. The party size requested for the waitlist entry.
int32 party_size = 3;
// Required. Personal information of the user joining the waitlist.
UserInformation user_information = 4;
// A string from the user which contains any special requests or additional
// information that they would like to notify the merchant about.
// This will be populated when the user submits an additional request to
// Reserve with Google. The partner can disable this functionality at the
// service level by setting supports_additional_request to false in the
// service feed.
string additional_request = 5;
// Required. Used to differentiate retries from separate requests. If the
// exact same CreateWaitlistEntry is received a second time, (including
// idempotency_token) then the same CreateWaitlistResponse must be returned.
string idempotency_token = 6;
}
// Response for the CreateWaitlistEntry RPC with the waitlist entry ID or any
// failing business logic information.
message CreateWaitlistEntryResponse {
// Unique partner-provided ID for the newly created entry in the waitlist.
// Required if the waitlist entry was created successfully. Unique for all
// time.
string waitlist_entry_id = 1;
WaitlistBusinessLogicFailure waitlist_business_logic_failure = 2;
}
// GetWaitlistEntry method
// Get the waitlist entry corresponding to the provided waitlist entry ID.
message GetWaitlistEntryRequest {
// Required. The partner-provided waitlist entry ID to request info for.
string waitlist_entry_id = 1;
}
// Response with the waitlist entry corresponding to the provided
// waitlist entry ID.
message GetWaitlistEntryResponse {
// Required. The partner-provided information about a user’s waitlist entry.
WaitlistEntry waitlist_entry = 1;
}
// DeleteWaitlistEntry method
// Cancel the user's entry in the waitlist.
message DeleteWaitlistEntryRequest {
// Required. The partner-provided ID for the waitlist entry to be deleted.
string waitlist_entry_id = 1;
}
// WaitlistEntry specification
enum WaitlistEntryState {
WAITLIST_ENTRY_STATE_UNSPECIFIED = 0;
// The waitlist entry was created and the user is currently waiting in the
// waitlist.
WAITING = 1;
// The waitlist entry is awaiting confirmation by the merchant.
PENDING_MERCHANT_CONFIRMATION = 8;
// The waitlist entry has been canceled by the user. Cancellation for no-shows
// should use the NO_SHOW state.
CANCELED = 2;
// The waitlist entry has been declined by the merchant.
DECLINED_BY_MERCHANT = 7;
// The merchant is ready to serve the user.
SERVICE_READY = 3;
// The user has checked in with the host and is waiting to be seated.
CHECKED_IN = 4;
// The user has arrived and been seated by the merchant.
SEATED = 5;
// The user did not arrive at the merchant in time and lost their space.
NO_SHOW = 6;
}
// The times at which the waitlist entry changed state.
message WaitlistEntryStateTimes {
// Required. The time at which the waitlist entry was created.
// In seconds since Unix epoch.
int64 created_time_seconds = 1;
// The time that the waitlist entry was cancelled. Must be populated
// when the waitlist entry has been canceled but not before.
// In seconds since Unix epoch.
int64 canceled_time_seconds = 2;
// The time the merchant was ready to serve the user.
// service_readied_time_seconds must be populated after the merchant is
// ready to serve the user but not before.
// In seconds since Unix epoch.
int64 service_readied_time_seconds = 3;
// The actual time the user checked in with the host. checked_in_time must be
// populated after the user has checked in with the merchant but not before.
// In seconds since Unix epoch.
int64 checked_in_time_seconds = 4;
// The seated time for the user. seated_time_seconds must be populated
// when the user has been seated but not before.
// In seconds since Unix epoch.
int64 seated_time_seconds = 5;
// The time that the user was marked as a no-show. marked_no_show_time_seconds
// must be populated when the user has been marked a no-show but not before.
// In seconds since Unix epoch.
int64 marked_no_show_time_seconds = 6;
}
// An entry in the waitlist.
message WaitlistEntry {
// Required.
WaitlistEntryState waitlist_entry_state = 1;
// Required. The times at which the waitlist entry changed state.
WaitlistEntryStateTimes waitlist_entry_state_times = 2;
// Required. Contains fields measuring how long (in time or # of people) until
// the user is ready to leave the waitlist and be seated.
WaitEstimate wait_estimate = 3;
}
// WaitlistBusinessLogicFailure specification
// Status data that conveys why creating a waitlist entry fails.
// If there is a business logic error that is not captured here, please
// reach out to the Reserve with Google team to add it to this list. Other
// errors should be returned using standard HTTP error codes.
message WaitlistBusinessLogicFailure {
enum Cause {
// Default value: Don't use; amounts to an "unknown error"
// Unexpected errors must be returned using standard HTTP error codes.
CAUSE_UNSPECIFIED = 0;
// The user has already booked a waitlist entry with the partner.
EXISTING_WAITLIST_ENTRY = 1;
// The requested party size is below the merchant’s minimum.
BELOW_MIN_PARTY_SIZE = 2;
// The requested party size is above the merchant’s maximum.
ABOVE_MAX_PARTY_SIZE = 3;
// The requested merchant is currently closed.
MERCHANT_CLOSED = 4;
// There is currently no wait and the user should walk in without joining
// the waitlist.
NO_WAIT = 5;
// The waitlist is at capacity and new users are not being accepted at this
// time.
WAITLIST_FULL = 6;
// The country of the phone number is not supported.
PHONE_NUMBER_COUNTRY_UNSUPPORTED = 7;
// The waitlist is closed and not accepting new users. This is expected when
// the waitlist enters state CLOSED_OTHER after the user has already seen a
// wait estimate.
WAITLIST_CLOSED = 8;
}
// Required. The reason why the booking failed.
Cause cause = 1;
// This optional field is used for the partner to include additional
// information for debugging purposes only.
string description = 2;
}
// User specification
// Personal information about the person taking action (e.g. making a
// booking, an order, or creates a parking session).
message UserInformation {
// Unique ID of the user to the partner, chosen by Reserve with Google.
// (required)
string user_id = 1;
// Given name of the user (maximum 40 characters) (required)
string given_name = 2;
// Family name of the user (maximum 40 characters) (required)
string family_name = 3;
// Address of the user (optional)
PostalAddress address = 4;
// Phone number of the user (required)
// Consistent with the international definition in ITU-T E.123 recommendation.
// However, local conventions are also followed, such as using '-' instead of
// a space as separator. For example, a phone number in the US can be
// written as '+1 415-736-0000'
string telephone = 5;
// Email address of the user (required except for waitlists)
string email = 6;
// User's language code, in IETF BCP 47 format. It is sent only if a partner
// is allowed to use this feature. Please contact Reserve with Google team
// to be added to the allowlist and receive this code. (optional)
string language_code = 7;
reserved 8;
}
// The postal address for a merchant.
message PostalAddress {
// The country, using ISO 3166-1 alpha-2 country code, e.g. "US" (required)
string country = 1;
// The locality/city, e.g. "Mountain View". (required)
string locality = 2;
// The region/state/province, e.g. "CA". This field is only required in
// countries where region is commonly a part of the address. (optional)
string region = 3;
// The postal code, e.g. "94043". (required)
string postal_code = 4;
// The street address, e.g. "1600 Amphitheatre Pkwy". (required)
string street_address = 5;
}
