Protocol Documentation

Table of Contents

Top

engine/book/common/service/v1/error.proto

ActionNotAvailableError

An error indicating that an action attempted by the client is unavailable for the given BookingDetails.

Field Type Label Description
action_availability engine.common.v1.ActionAvailability   The availability of the attempted action.

BookingNeedsReviewError

An error that indicates a BookingDetails failed in an unknown state and needs to be manually reviewed to determine if it was completed successfully.

CannotCancelError

An error indicating that a BookingDetails cannot be canceled.

InvalidPaymentError

An error indicating that a Booking payment failed due to invalid PaymentInfo.

InvalidStateError

An error indicating that the requested BookingDetails is not in a valid state to perform the operation.

OfferNoLongerAvailableError

An error indicating that the OfferSummary is no longer available. This is likely due to the OfferSummary being sold out.

PaymentProcessingError

An error indicating that a Booking payment failed during processing. These errors are not safe to retry. Contact Member Support for assistance.

Top

engine/book/lodging/service/v1/book.proto

BookError

Error details of a failed LodgingBookingService.Book call.

Field Type Label Description
offer_no_longer_available engine.book.common.service.v1.OfferNoLongerAvailableError   Defined when the operation returns with a status of INVALID_ARGUMENT and the requested offer is no longer available for sale.
invalid_state engine.book.common.service.v1.InvalidStateError   Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated with the given continuation token is not in a valid state, e.g. It has already been booked or needs CS review.
needs_review engine.book.common.service.v1.BookingNeedsReviewError   Defined when the operation returns with a status of INTERNAL and the booking is in a non-retriable state that requires manual review to determine if it was completed successfully.
invalid_payment engine.book.common.service.v1.InvalidPaymentError   Defined when the operation returns with a status of INVALID_ARGUMENT and the provided payment information is invalid or insufficient to complete the booking.
payment_processing engine.book.common.service.v1.PaymentProcessingError   Defined when the operation returns with a status of INTERNAL and the payment failed to process.

BookRequest

A request to purchase and reserve an OfferSummary.

Field Type Label Description
continuation_token string   An continuation_token from LodgingBookingService.ConfirmOffer.
guests engine.book.lodging.v1.RoomGuests repeated The details of the guests staying on the ReservationDetails. The number of provided RoomGuests entries must match the number of rooms requested during shopping. Some Properties may not retain all of the provided guest names and may not honor more than one guest's loyalty per BookingDetails.
metadata engine.book.lodging.v1.BookingMetadata repeated Metadata to be stored and retrieved along with this BookingDetails.
payment_info engine.common.v1.PaymentInfo   Optionally, the PaymentInfo to be used for this booking.

BookResponse

The result of an attempt to purchase and reserve an OfferSummary.

Field Type Label Description
details engine.book.lodging.v1.BookingDetails   The recorded details of the BookingDetails and ReservationDetails.

Top

engine/book/lodging/service/v1/confirm_offer.proto

ConfirmOfferError

Error details of a failed LodgingBookingService.ConfirmOffer call.

Field Type Label Description
offer_no_longer_available engine.book.common.service.v1.OfferNoLongerAvailableError   Defined when the operation returns with a status of INVALID_ARGUMENT and the requested offer is no longer available for sale.
invalid_state engine.book.common.service.v1.InvalidStateError   Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated with the given continuation token is not in a valid state, e.g. It has already been booked or needs CS review.
booking_id string optional Optionally, the unique identifier for this booking if it is known when the error occurs.

ConfirmOfferRequest

A request to confirm final pricing and availability of an OfferSummary.

Field Type Label Description
continuation_token string   A continuation_token from LodgingShoppingService.FindBestOffers, LodgingShoppingService.FindBestOffersStreaming, or LodgingShoppingService.FindAvailability.
currency_code string   The currency code for this request. This field specifies the currency in which the requester expects to see prices. It must adhere to the ISO 4217 three-character alphabetic currency code ("USD", "EUR", etc.). https://www.iso.org/iso-4217-currency-codes.html

ConfirmOfferResponse

The result of a price and availability check.

Field Type Label Description
continuation_token string   An opaque token that may be used to book the stay via LodgingBookingService.Book. See LodgingBookingService.ConfirmOffer
quote engine.book.lodging.v1.Quote   The full details of the OfferSummary, RoomDescription, Dates of Travel, and any notices required for display during the confirmation process.

Top

engine/book/lodging/service/v1/generate_folio.proto

GenerateFolioError

Error information returned in the error details of failed GenerateFolio calls.

Field Type Label Description
invalid_state engine.book.common.service.v1.InvalidStateError   Defined when the operation returns with a status of FAILED_PRECONDITION and the booking associated with the given booking ID is not in a valid state, e.g. it has not been booked

GenerateFolioRequest

Generates a folio HTTP response for a Booking.

Field Type Label Description
booking_id string   The booking ID for which to generate the folio.

Top

engine/book/lodging/service/v1/get_bookings.proto

GetBookingError

Describes a failure to retrieve a single BookingDetails.

Field Type Label Description
booking_id string   The id of the BookingDetails that could not be retrieved.
error google.rpc.Status   If available, the reason the BookingDetails could not be retrieved.

GetBookingsError

Error details of a failed LodgingBookingService.GetBookings call.

Field Type Label Description
errors GetBookingError repeated If available, the individual BookingDetails that could not be retrieved, in no particular order.

GetBookingsRequest

A request to retrieve one or more BookingDetails.

Field Type Label Description
booking_ids string repeated The identifiers of the BookingDetails to retrieve. No more than 50 BookingDetails may be requested at a time.

GetBookingsResponse

The details of a single BookingDetails.

Field Type Label Description
bookings engine.book.lodging.v1.BookingDetails repeated The requested BookingDetails in no particular order.

Top

engine/book/lodging/service/v1/get_bookings_streaming.proto

GetBookingsStreamingError

Error details for a failed LodgingBookingService.GetBookingsStreaming call.

GetBookingsStreamingRequest

A request to retrieve a single BookingDetails.

Field Type Label Description
booking_id string    

GetBookingsStreamingResponse

A single BookingDetails or an error describing why that BookingDetails could not be retrieved.

Field Type Label Description
booking_details engine.book.lodging.v1.BookingDetails   A single BookingDetails.
error GetBookingError   Error details describing a failure to retrieve a single BookingDetails.

Top

engine/book/lodging/service/v1/preview_cancellation.proto

PreviewCancellationError

Error details of a failed LodgingBookingService.PreviewCancellation call.

Field Type Label Description
invalid_state engine.book.common.service.v1.InvalidStateError   Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated with the given booking ID is not in a valid state, e.g. It has not been booked, or is already cancelled.

PreviewCancellationRequest

Requests the expected result of a cancellation.

Field Type Label Description
booking_id string    

PreviewCancellationResponse

Returns the expected result and availability of a cancellation.

Field Type Label Description
available_actions engine.common.v1.AvailableActions   Details the means in which a cancellation could occur.
refund engine.common.v1.Refund   Optionally, the refund details if they can be determined. If cancellation is not possible or cannot be done through the API, this field will not be set. See ActionAvailability for more information.

Top

engine/book/lodging/service/v1/service.proto

LodgingBookingService

A service to support transactions on offer OfferSummary or one or more BookingDetails.

Method Name Request Type Response Type Description
ConfirmOffer ConfirmOfferRequest ConfirmOfferResponse

Given a continuation_token from LodgingShoppingService.FindBestOffers, LodgingShoppingService.FindBestOffersStreaming, or LodgingShoppingService.FindAvailability, confirm the availability of the offer and retrieve any additional information necessary to Book.

In case of error, the status will contain a ConfirmOfferError within the Status.details field.
Book BookRequest BookResponse

Given a continuation_token from LodgingBookingService.ConfirmOffer, purchase and reserve the Offer.

In case of error, the status will contain a BookError within the Status.details field.
GetBookings GetBookingsRequest GetBookingsResponse

Retrieve multiple BookingDetails given provided one or more BookingDetails.booking_id.

In case of error, the status will contain a GetBookingsError within the Status.details field.
GetBookingsStreaming GetBookingsStreamingRequest stream GetBookingsStreamingResponse stream

Stream a set of BookingDetails given a set of streamed BookingDetails.booking_id.

In case of fatal error that interrupts the stream, the status will contain a GetBookingsStreamingError within the Status.details field. In the case of non-fatal errors (such as an individual booking not found), the error details will be found in the response object.

This rpc is unavailable via the HTTP/JSON API.
PreviewCancellation PreviewCancellationRequest PreviewCancellationResponse

Get the availability, means, and expected refund for a booking cancellation.

In case of error, the status will contain a PreviewCancellationError within the Status.details field.
SubmitCancellation SubmitCancellationRequest SubmitCancellationResponse

Submit a cancellation for a specific booking.

In case of error, the status will contain a SubmitCancellationError within the Status.details field.
GenerateFolio GenerateFolioRequest google.api.HttpBody

Generate a folio for a specific booking.

In case of error, the status will contain a GenerateFolioError within the Status.details field.

Top

engine/book/lodging/service/v1/submit_cancellation.proto

SubmitCancellationError

Error information returned in the error details of failed SubmitCancellation calls.

Field Type Label Description
action_not_available engine.book.common.service.v1.ActionNotAvailableError   The cancellation action is not available for the booking.
cannot_cancel engine.book.common.service.v1.CannotCancelError   Defined when the operation returns with a status of INVALID_ARGUMENT and the requested booking is not cancellable.
invalid_state engine.book.common.service.v1.InvalidStateError   Defined when the operation returns with a status of INVALID_ARGUMENT and the booking associated with the given booking ID is not in a valid state, e.g. It has not been booked, or is already cancelled.

SubmitCancellationRequest

Requests cancellation of a Booking.

Field Type Label Description
booking_id string    

SubmitCancellationResponse

Returns the result of a requested cancellation.

Field Type Label Description
details engine.book.lodging.v1.CancellationDetails   The timestamp and refund details.

Top

engine/content/service/v1/get_properties.proto

GetPropertiesRequest

A request to retrieve specific Properties by their IDs.

Field Type Label Description
property_ids string repeated The list of Engine Property IDs. Maximum of 50 property IDs per request.

GetPropertiesResponse

A response containing Property information.

Field Type Label Description
properties engine.content.v1.lodging.Property repeated The list of available Property objects including phone numbers.
inaccessible_property_ids string repeated The list of Property IDs that were requested but not found.

Top

engine/content/service/v1/list_properties.proto

ListPropertiesCriteria

Criteria that define the properties that may be responsive to a ContentServiceV1.ListProperties request.

Field Type Label Description
radius RadiusSearch    
exclude_properties_without_hero_image bool optional Optionally, if true, properties that do not have a Property#hero_image_uri will not be returned. Excluded properties will not count against the page size or limit.
exclude_properties_without_description bool optional Optionally, if true, properties that do not have a Property#description will not be returned. Excluded properties will not count against the page size or limit.
sort_mode ListPropertiesSortMode optional The order in which the properties will be returned.

ListPropertiesRequest

A request to retrieve one page of properties.

Field Type Label Description
request ListPropertiesRequestDetails   The definition of this ListPropertiesRequest.
next_page_token string   Optionally, a next_page_token retrieved from a ListPropertiesResponse.

ListPropertiesRequestDetails

The request definition for a ListPropertiesRequest.

Field Type Label Description
criteria ListPropertiesCriteria   The criteria that defines responsive properties for a ListPropertiesRequest.
page_size int32 optional The maximum number of search results to be returned in a page. Default: 100 Minimum: 1 Maximum: 500

ListPropertiesResponse

A response to a ContentServiceV1.ListProperties request.

Field Type Label Description
properties ResponsiveProperty repeated Up to ListPropertiesRequest.page_size responsive to
next_page_token string optional Optionally, an opaque token to be passed into the next ListPropertiesRequest in order to retrieve the next page of results.

RadiusSearch

A search area in a perfect circle around a central point.

Field Type Label Description
coordinates engine.common.v1.GeoPoint   Latitude and Longitude coordinates to use as the center point of the search.
physical_address engine.common.v1.PostalAddress   A physical address to use as the center point of the search.
freeform_search_text string   A description of a point of interest, an unstructured address, etc. Freeform input will make a "best effort" match to a point of interest and its corresponding geo coordinates. If available, using coordinates or physical_address will yield better results.
radius engine.common.v1.Distance   The size of the search area. Default: 10 miles Minimum: 1 mile (~1.6 kilometers) Maximum: 50 miles (~80 kilometers)

ResponsiveProperty

A Property that meets the criteria of a ContentServiceV1.ListProperties request.

Field Type Label Description
property engine.content.v1.lodging.Property   The property details.
distance engine.common.v1.Distance   The distance between the center point of the ListProperties.inclusion_type and the property.

ListPropertiesSortMode

Controls the order in which Property results are returned from ContentServiceV1.ListProperties.

Name Number Description
PROPERTY_SORT_MODE_DISTANCE 0 Results are returned in ascending order from the center point of the ListProperties.inclusion_type.

Top

engine/content/service/v1/list_property_catalog.proto

ListPropertyCatalogRequest

A request to retrieve one page of the property catalog.

Field Type Label Description
request ListPropertyCatalogRequestDetails   The parameters and filters to retrieve the first page of the catalog.
page_token string   Optionally, a page_token retrieved from a previous call.

ListPropertyCatalogRequestDetails

Parameters and filters to be applied to a property catalog request.

Field Type Label Description
page_size int32 optional The maximum number of records to be returned in a page. Default: 100 Minimum: 1 Maximum: 250
updated_after string optional Optionally, return only properties updated after this timestamp. When omitted, the full catalog is returned. Conforms to ISO-8601, see https://en.wikipedia.org/wiki/ISO_8601

ListPropertyCatalogResponse

A response to a CatalogService.ListPropertyCatalog request.

Field Type Label Description
entries PropertyCatalogEntry repeated The catalog entries returned by the request. It will contain up to ListPropertyCatalogRequestDetails.page_size records.
next_page_token string optional Optionally, an opaque token to be passed into the next ListPropertyCatalogRequest to retrieve the next page.

PropertyCatalogEntry

A single entry in the property catalog, wrapping a Property together with its state.

Field Type Label Description
state PropertyCatalogState   The PropertyCatalogState of this entry within the catalog.
property engine.content.v1.lodging.Property   The Property content for this entry.

PropertyCatalogState

The state of a property within the catalog.

Name Number Description
PROPERTY_CATALOG_STATE_UNSPECIFIED 0 The state is unknown or unspecified.
PROPERTY_CATALOG_STATE_ACTIVE 1 The property is active within the catalog
PROPERTY_CATALOG_STATE_INACTIVE 2 The property is inactive within the catalog.

Top

engine/content/service/v1/service.proto

CatalogService

Method Name Request Type Response Type Description
ListPropertyCatalog .engine.content.service.v1.ListPropertyCatalogRequest .engine.content.service.v1.ListPropertyCatalogResponse Retrieves one page of the lodging properties catalog.

ContentService

Method Name Request Type Response Type Description
ListProperties .engine.content.service.v1.ListPropertiesRequest .engine.content.service.v1.ListPropertiesResponse  
GetProperties .engine.content.service.v1.GetPropertiesRequest .engine.content.service.v1.GetPropertiesResponse Retrieves details for the set of properties specified in the request.

Top

engine/notification/service/v1/delete_subscription.proto

DeleteSubscriptionError

Error information returned in the error details of failed NotificationManagementService.DeleteSubscription calls.

Field Type Label Description
subscription_not_found SubscriptionNotFound   The requested event subscription does not exist.

DeleteSubscriptionRequest

Requests deletion of an event subscription.

Field Type Label Description
subscription_id string   This identifies the subscription to remove as provided by Subscribe.

DeleteSubscriptionResponse

Confirms the requested deletion.

Top

engine/notification/service/v1/error.proto

InvalidCallbackUri

callback_uri is malformed or not an HTTPS URI.

Field Type Label Description
callback_uri string   The callback URI that failed validation.

InvalidDescription

The supplied description is missing, blank, or exceeds the accepted length.

Field Type Label Description
reason string   Why the description failed validation, e.g. "blank" or "too_long".

InvalidEntityType

entity_type was unspecified (ENTITY_TYPE_UNSPECIFIED) or is not a recognized entity domain.

InvalidEventType

event_types contained EVENT_TYPE_UNSPECIFIED or is not a recognized event.

InvalidSecret

The supplied secret is not valid base64 or decodes to a length outside the accepted range.

Field Type Label Description
reason string   Why the secret failed validation, e.g. "invalid_base64" or "length_out_of_range".

InvalidTimeWindow

The requested time window is invalid, e.g. window_end is not after window_start.

Field Type Label Description
window_start string optional Inclusive start of the query window in ISO 8601 timestamp format. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
window_end string optional Exclusive end of the query window in ISO 8601 timestamp format. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations

MissingNotificationType

No notification_type channel was provided in SubscribeRequest.

SecretRotationLimitReached

The subscription's secrets have already been rotated the maximum number of times within the rolling 24-hour window.

Field Type Label Description
retry_after string   ISO 8601 timestamp when the oldest 24-hour window rotation falls off and another rotation will be permitted. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations

SubscriptionNotFound

The requested event subscription does not exist. Reused across the endpoints that operate on an existing subscription (e.g. NotificationManagementService.UpdateSubscription, NotificationManagementService.DeleteSubscription, NotificationManagementService.RotateSecret, NotificationManagementService.ListSubscriptionEventAttempts).

Field Type Label Description
subscription_id string   The subscription id from the request that could not be found.

Top

engine/notification/service/v1/list_event_attempts.proto

ListSubscriptionEventAttemptsError

Error details of a failed NotificationManagementService.ListSubscriptionEventAttempts call.

Field Type Label Description
subscription_not_found SubscriptionNotFound   The requested event subscription does not exist.
invalid_time_window InvalidTimeWindow   The requested time window is invalid, e.g. window_end is not after window_start, or window_end is more than 7 days before the current time.

ListSubscriptionEventAttemptsRequest

Lists event delivery attempts for an event subscription. Attempt history is retained for 7 days.

Field Type Label Description
subscription_id string   The subscription id for which to pull event delivery attempts. See NotificationManagementService.Subscribe and NotificationManagementService.ListSubscriptions
window_start string optional Inclusive start of the query window, ISO 8601 timestamp (e.g. 2026-04-01T00:00:00Z). See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations If not set, will default to 24 hours before window_end. If set or calculated to include more than 7 days of history, will not throw an error but returned results will be limited to the history limit.
window_end string optional Exclusive end of the query window, ISO 8601 timestamp. See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations Must be after window_start when both are set. If not set, defaults to current time. If set more than 7 days before the current time, rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and a ListSubscriptionEventAttemptsError whose invalid_time_window field is set.
status engine.notification.v1.EventDeliveryAttemptStatus optional Filter by attempt outcome. Omitting or setting to the unspecified enum value will include all statuses.
limit int32 optional Maximum number of records to return. Defaults to 50; maximum is 100.
page_token string optional Opaque pagination token returned by a prior response. Omit to start from the first page.

ListSubscriptionEventAttemptsResponse

Paginated list of event delivery attempts for the requested subscription.

Field Type Label Description
attempts engine.notification.v1.EventDeliveryAttempt repeated Event delivery attempt records for the page, ordered by attempted_at (descending).
next_page_token string optional Opaque token used to fetch the next page of attempts. If omitted, there are no additional pages.

Top

engine/notification/service/v1/list_subscriptions.proto

ListSubscriptionsRequest

A request for a list of subscriptions. See NotificationManagementService.ListSubscriptions.

Field Type Label Description
limit int32 optional Maximum number of subscriptions to return. Defaults to 50; maximum is 100.
page_token string optional Opaque pagination token returned by a prior response. Omit to start from the first page.

ListSubscriptionsResponse

A paginated list of event subscriptions returned from NotificationManagementService.ListSubscriptions.

Field Type Label Description
subscriptions engine.notification.webhook.v1.Subscription repeated Event subscriptions for the current page. Paginate with [next_page_token].
next_page_token string optional Opaque token used to fetch the next page of subscriptions. If omitted, there are no additional pages.

Top

engine/notification/service/v1/rotate_secret.proto

RotateSecretError

Error details of a failed NotificationManagementService.RotateSecret call.

Field Type Label Description
subscription_not_found SubscriptionNotFound   The requested event subscription does not exist.
invalid_secret InvalidSecret   The supplied secret is not valid base64 or decodes to a length outside the accepted range.
secret_rotation_limit_reached SecretRotationLimitReached   The subscription's secrets have already been rotated the maximum number of times within the rolling 24-hour window.

RotateSecretRequest

Rotates the HMAC signing secret for an event subscription. The previous secret remains valid for 24 hours after rotation.

Field Type Label Description
subscription_id string   Opaque identifier of the event subscription whose secret is being rotated.
secret string optional Base64-encoded secret key used for HMAC signature verification. If not provided, the server will generate one and return it in RotateSecretResponse.secret. The decoded key must be 24-75 bytes (32-100 base64 characters).

RotateSecretResponse

Confirms rotation and returns the newly-active HMAC signing secret.

Field Type Label Description
subscription_id string   Opaque identifier of the event subscription whose secret was rotated.
secret string   Base64-encoded HMAC signing secret now in effect, generated by the server if not provided in the request. The prior secret remains valid for verification for 24 hours.

Top

engine/notification/service/v1/service.proto

NotificationManagementService

A service to register and manage event subscriptions for event notifications.

In case of error, failed calls return a per-endpoint error type (e.g. SubscribeError) within the Status.details field.

Method Name Request Type Response Type Description
Subscribe SubscribeRequest SubscribeResponse

Creates a new event subscription for one or more events.

In case of error, the status will contain a SubscribeError within the Status.details field.
UpdateSubscription UpdateSubscriptionRequest UpdateSubscriptionResponse

Update an existing subscription's details.

This method does not allow changing an existing subscription's entity type. To change an entity type you must create a new subscription and/or delete the old one.

In case of error, the status will contain an UpdateSubscriptionError within the Status.details field.
DeleteSubscription DeleteSubscriptionRequest DeleteSubscriptionResponse

Delete an event subscription. Once deleted, no further events will be delivered to this subscription. If the URI associated with this subscription is associated with any other event subscriptions, it will still receive events from those other subscriptions.

In case of error, the status will contain a DeleteSubscriptionError within the Status.details field.
ListSubscriptions ListSubscriptionsRequest ListSubscriptionsResponse Returns all event subscriptions.
RotateSecret RotateSecretRequest RotateSecretResponse

Rotate the HMAC signing secret for event payload signature verification.

The previous secret remains in-effect for 24 hours after rotation.

A subscription may be rotated at most 10 times within any rolling 24-hour window. Requests that exceed this cap fail with gRPC INVALID_ARGUMENT(3) / HTTP 400 and a RotateSecretError. The cap relaxes as prior rotations age past 24 hours.

In case of error, the status will contain a RotateSecretError within the Status.details field.
ListSubscriptionEventAttempts ListSubscriptionEventAttemptsRequest ListSubscriptionEventAttemptsResponse

Lists event delivery attempts for a subscription over a time window of up to 7 days.

In case of error, the status will contain a ListSubscriptionEventAttemptsError within the Status.details field.

Top

engine/notification/service/v1/subscribe.proto

SubscribeError

Error details of a failed NotificationManagementService.Subscribe call.

Field Type Label Description
invalid_entity_type InvalidEntityType   entity_type was unspecified or is not a recognized entity domain.
invalid_callback_uri InvalidCallbackUri   callback_uri is missing, malformed, or not an HTTPS URI.
invalid_secret InvalidSecret   The supplied secret is not valid base64 or decodes to a length outside the accepted range.
missing_notification_type MissingNotificationType   No notification_type channel was provided.
invalid_event_type InvalidEventType   event_types contained EVENT_TYPE_UNSPECIFIED or is not a recognized event.
invalid_description InvalidDescription   description was missing, blank, or exceeded the accepted length.

SubscribeRequest

Subscribe to receive notifications for one or more event types for a given entity at a webhook URI.

Field Type Label Description
entity_type engine.notification.v1.EntityType   Entity domain this subscription applies to. Required: a request with ENTITY_TYPE_UNSPECIFIED is rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and a SubscribeError whose invalid_entity_type field is set.
event_types engine.notification.v1.EventType repeated Events that trigger delivery for the given entity type. Omit or send an empty list to subscribe to all event types for this entity_type. When present, the list must not contain EVENT_TYPE_UNSPECIFIED; if it does, the call is rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and a SubscribeError whose invalid_event_type field is set.
webhook SubscribeWebhookNotification   Delivery via an HTTPS webhook endpoint.
description string   Text associated to provide more context about the given subscription. This information can help provide additional context about the intent of this particular subscription as part of a larger set of subscriptions, for example. The description can be updated in UpdateSubscriptionRequest. Required: Must be non-blank after trimming whitespace. Limited to 120 characters. Rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and a SubscribeError whose invalid_description field is set.
enabled bool optional Whether the subscription is enabled for delivery. Defaults to true when omitted. While disabled, the subscription is retained but receives no deliveries until re-enabled via NotificationManagementService.UpdateSubscription. Re-enabling resumes delivery for new events only; events that occurred while disabled are not automatically sent.

SubscribeResponse

Subscribe response from NotificationManagementService.Subscribe

Field Type Label Description
subscription_id string   Opaque identifier for this event subscription.
webhook SubscribeResponseWebhookNotification   Details for a subscription delivered via an HTTPS webhook endpoint.

SubscribeResponseWebhookNotification

Webhook-specific fields returned from a NotificationManagementService.Subscribe request.

Field Type Label Description
secret string  

The Base64-encoded HMAC signing secret used to sign request payloads to the subscription's webhook URI. If a secret was provided in SubscribeWebhookNotification this will be the same value. If the secret was omitted this will be a generated secret from the server.

This secret is only available in this response and cannot be fetched later. It must be stored by the caller in order to verify inbound webhook deliveries.

SubscribeWebhookNotification

Webhook-specific fields for a NotificationManagementService.Subscribe request.

Field Type Label Description
callback_uri string   The HTTPS URI Engine will POST signed webhook payloads to. Must be reachable from Engine infrastructure. This URI must be an HTTPS endpoint and start with "https://".
secret string optional Base64-encoded secret key used for HMAC signature verification on inbound webhook deliveries. If not provided, the server will generate one and return it in SubscribeResponseWebhookNotification.secret. The decoded key must be 24-75 bytes (32-100 base64 characters).

Top

engine/notification/service/v1/update_subscription.proto

EventTypeUpdate

A replacement set of event types for [UpdateSubscriptionRequest.event_types]. Wrapping the repeated field lets the request distinguish "leave unchanged" (field omitted) from "replace with this set" (field present), including replacing with all event types (empty values).

Field Type Label Description
values engine.notification.v1.EventType repeated Event types that trigger delivery for the subscription. An empty list delivers all event types. Must not contain EVENT_TYPE_UNSPECIFIED; if it does, the call is rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and an UpdateSubscriptionError whose invalid_event_type field is set.

UpdateSubscriptionError

Error details of a failed NotificationManagementService.UpdateSubscription call.

Field Type Label Description
subscription_not_found SubscriptionNotFound   The requested event subscription does not exist.
invalid_callback_uri InvalidCallbackUri   callback_uri was provided but is malformed or not an HTTPS URI.
invalid_event_type InvalidEventType   event_types contained EVENT_TYPE_UNSPECIFIED or is not a recognized event.
invalid_description InvalidDescription   description was blank or exceeded the accepted length.

UpdateSubscriptionRequest

The request object for NotificationManagementService.UpdateSubscription.

Field Type Label Description
subscription_id string   The subscription to update using the subscription_id returned from NotificationManagementService.Subscribe or NotificationManagementService.ListSubscriptions.
event_types EventTypeUpdate optional Replaces the event types this subscription delivers. Omit to leave the existing event types unchanged. When present, the supplied set fully replaces the prior set (it is not merged). Provide the message with an empty values list to deliver all event types for the subscription's entity type.
webhook UpdateWebhookNotification   Updates to a subscription delivered via an HTTPS webhook endpoint.
description string optional Text associated to provide more context about the given subscription. This information can help provide additional context about the intent of this particular subscription as part of a larger set of subscriptions, for example. If omitted, will leave the existing subscription description unchanged. If present, must be non-blank after trimming whitespace. Limited to 120 characters. Rejected with gRPC INVALID_ARGUMENT(3) / HTTP 400 and an UpdateSubscriptionError whose invalid_description field is set.
enabled bool optional Whether the subscription is enabled for delivery. While disabled, the subscription is retained but receives no deliveries. Re-enabling resumes delivery for new events only; events that occurred while disabled are not automatically sent. If omitted, will leave the existing subscription value unchanged.

UpdateSubscriptionResponse

Acknowledges a successful update; no payload is returned.

UpdateWebhookNotification

Webhook-specific fields for a NotificationManagementService.UpdateSubscription request.

Field Type Label Description
callback_uri string optional The HTTPS URI Engine will POST signed webhook payloads to. Must be reachable from Engine infrastructure. This URI must be an HTTPS endpoint and start with "https://". If omitted or an empty string, will leave the existing subscription URI unchanged.

Top

engine/service/common/v1/error.proto

InvalidSortError

An error indicating that the requested sorting option provided is not valid for the given search criteria.

Top

engine/shop/lodging/service/v1/find_availability.proto

FindAvailabilityPropertyRequest

A request to find availability for a single Property.

Field Type Label Description
property_id string   The Engine Property ID
check_in_date string   An ISO-8601-compliant date on which you will check in to the property. See https://en.wikipedia.org/wiki/ISO_8601#Dates
check_out_date string   An ISO-8601-compliant date on which you will check out of the property. See https://en.wikipedia.org/wiki/ISO_8601#Dates
num_rooms int32   The number of rooms to book. May not exceed 8
currency_code string   The 3-character ISO-4217 alphabetic currency code to be used to convey pricing information. https://www.iso.org/iso-4217-currency-codes.html
travelers engine.common.v1.AnonymousTraveler repeated Describes the travelers for whom you are searching. Changes to the quantity or age of travelers has an impact on the Offer price. Failure to properly identify your travelers may incur additional charges at checkin or cancellation of the booking.
sales_channel engine.common.v1.SalesChannel optional If available, the sales channel for the customer

FindAvailabilityRequest

Field Type Label Description
continuation_token string   A [BestOffer.continuation_token]. Passing a continuation_token allows you to continue the shopping flow from a BestOffers search with the necessary search context preserved.
single_property FindAvailabilityPropertyRequest   A request to find availability for a Property directly, skipping the BestOffers search.

FindAvailabilityResponse

A response to a LodgingShoppingService.FindBestOffers call.

Field Type Label Description
room_groups RoomGroup repeated A list of available OfferSummary, grouped by RoomDescription.

Offer

A bookable Offer representing a set of amenities and a price for the booking.

Field Type Label Description
continuation_token string   An opaque token that may be passed to LodgingBookingService.ConfirmOffer to begin the booking process.
summary engine.shop.lodging.v1.OfferSummary   The details of the Offer to book.

RoomGroup

A grouping of bookable Offers, collected by the RoomDescription to which they apply.

Field Type Label Description
room_description engine.shop.lodging.v1.RoomDescription   A description of the rooms for which the Offer applies. For example, "Standard 1 King Bed", "Standard 2 Queen Beds", or "Suite 1 King Bed".
offers Offer repeated A list of bookable Offers for the room.

Top

engine/shop/lodging/service/v1/find_best_offers.proto

BestOffer

The details of the Best Offer available for a property given the search criteria and aggregated data about other Offers that are available at the same property. A BestOffer is not an exhaustive representation of all amenities and options available at a Property. For example, it is possible that a BestOffer might indicate no loyalty is available because it cannot be known until full availability has been pulled. To retrieve the full availability for a Property, see LodgingShoppingService.FindAvailability.

Field Type Label Description
continuation_token string   An opaque token that may be used to see all available Offers for the property, or to book the offer directly. See LodgingShoppingService.FindAvailability See LodgingBookingService.ConfirmOffer
best_offer engine.shop.lodging.v1.OfferSummary   The specific details of the Best Offer available for a Property.
is_refundable_available bool   True if it is known that at least one refundable Offer is available for the property.
is_loyalty_available bool   True if it is known that at least one Offer is available that earns loyalty points.
is_free_parking_available bool   True if it is known that at least one Offer is available that has free parking included. Please note: this value will be false if it is known that the Property offers free parking to all guests.
is_free_breakfast_available bool   True if it is known that at least one Offer is available that has free breakfast included. Please note: this value will be false if it is known that the Property offers free breakfast to all guests.
is_loyalty_membership_rate_available bool   True if it is known that at least one Offer is available that requires a loyalty membership id to book.

FindBestOffersError

Error details of a failed LodgingShoppingService.FindBestOffers call.

Field Type Label Description
invalid_sort engine.service.common.v1.InvalidSortError   Defined when the operation returns with a status of INVALID_ARGUMENT and [FindBestOffersRequest.sort_mode] is not valid for the given search criteria.

FindBestOffersRequest

A request that defines the criteria of a "Best Offers" search. See LodgingShoppingService.FindBestOffers

Field Type Label Description
criteria FindBestOffersRequestCriteria   The criteria to be used to identify and filter Properties and Offers.
include_properties_with_no_availability bool   By default, only Properties that have rooms matching your criteria will be returned. This differs from LodgingShoppingService.FindBestOffersStreaming which returns all considered properties. You may wish to set this to true if you are building a shopping experience that indicates availability may differ with different criteria, such as dates, but streaming is not viable.
sort_mode FindBestOffersSortMode   The order in which the results will be returned.

FindBestOffersRequestCriteria

Defines the base criteria used in a "Best Offers" search.

Field Type Label Description
point_and_radius RadiusSearch   Check the availability of up to max_property_candidates hotels nearest the center of the provided radius.
property_id PropertyIdSearch   Check the availability of properties as identified by the provided Engine Property IDs.
check_in_date string   An ISO-8601-compliant date on which you will check in to the property. See https://en.wikipedia.org/wiki/ISO_8601#Dates
check_out_date string   An ISO-8601-compliant date on which you will check out of the property. See https://en.wikipedia.org/wiki/ISO_8601#Dates
num_rooms int32   The number of rooms to book. May not exceed 8
currency_code string   The 3-character ISO-4217 alphabetic currency code to be used to convey pricing information. https://www.iso.org/iso-4217-currency-codes.html
travelers engine.common.v1.AnonymousTraveler repeated Describes the travelers for whom you are searching. Changes to the quantity or age of travelers has an impact on the Offer price. Failure to properly identify your travelers may incur additional charges at checkin or cancellation of the booking.
sales_channel engine.common.v1.SalesChannel optional If available, the sales channel for the customer
max_property_candidates int32 optional The maximum number of properties to be considered for Offers. Properties with no availability will count against this limit, but may not be returned if there is no availability. May not exceed 250. This limit is not honored when Property IDs are provided via [property_ids].

FindBestOffersResponse

The results of a LodgingShoppingService.FindBestOffers search.

Field Type Label Description
offers PropertyBestOffer repeated The full list of offers responsive your search.

PropertyBestOffer

A Property and the BestOffer available for that Property given the provided search criteria.

Field Type Label Description
property ResponsiveProperty   Details of the Property for which this BestOffer applies.
best_offer BestOffer   The details of the available BestOffer.

PropertyIdSearch

A list of Engine Property IDs to shop for Best Offers.

Field Type Label Description
property_ids string repeated The list of Engine Property IDs. Minimum: 1 Maximum: 250

RadiusSearch

A search area in a perfect circle around a central point.

Field Type Label Description
coordinates engine.common.v1.GeoPoint   Latitude and Longitude coordinates to use as the center point of the search.
radius engine.common.v1.Distance   The size of the search area. Default: 10 miles Minimum: 1 mile (~1.6 kilometers) Maximum: 50 miles (~80 kilometers)

ResponsiveProperty

A Property that is responsive to the current shopping search.

Field Type Label Description
property engine.content.v1.lodging.Property   The details of the returned property.
distance engine.common.v1.Distance   The distance from the center point of the search area, if appropriate.

FindBestOffersSortMode

Describes the various ways a LodgingShoppingService.FindBestOffers search maybe sorted.

Name Number Description
FIND_BEST_OFFERS_SORT_MODE_UNSPECIFIED 0 No specific sort criteria will be used.
FIND_BEST_OFFERS_SORT_MODE_DISTANCE 1 Properties are returned in order of increasing distance. In case of ties, Property names are sorted lexically. Only valid when candidate properties are identified via RadiusSearch (point_and_radius).

Top

engine/shop/lodging/service/v1/find_best_offers_streaming.proto

FindBestOffersStreamingRequest

A request that defines the criteria of a "Best Offers" streaming search. See LodgingShoppingService.FindBestOffersStreaming.

Field Type Label Description
criteria FindBestOffersRequestCriteria   The criteria to be used to identify and filter Properties and Offers.

FindBestOffersStreamingResponse

An alternation to support multi-message-type streaming of BestOffers.

Field Type Label Description
property ResponsiveProperty   A property that will be used as a candidate for Offer retrieval. Not every property sent will have a BestOffer associated with it if there is no availability within your specified parameters. While it is possible for Properties and BestOffers to be interleaved, the ResponsiveProperty for a BestOffer will always be sent and received first.
offer BestOffer   A BestOffer candidate for a Property. A BestOffer will never be sent for a property before its responsive property is sent. A single property may have multiple BestOffers returned if a better offer is encountered after the first has already been sent. If multiple BestOffers are received for a single Property, the last always wins.

Top

engine/shop/lodging/service/v1/service.proto

LodgingShoppingService

Service and methods to support shopping for lodging.

Method Name Request Type Response Type Description
FindBestOffers FindBestOffersRequest FindBestOffersResponse Identifies a set of candidate Properties that match the provided criteria. Once the appropriate properties have been identified, the Best Offer available for each property is selected and augmented with the details of other available Offers. Best Offers are not exhaustive of all available offers for a property. In case of error, the status will contain a FindBestOffersError within the Status.details field.
FindBestOffersStreaming FindBestOffersStreamingRequest FindBestOffersStreamingResponse stream

Identifies a set of candidate Properties that match the provided criteria. All ResponsiveProperties are returned regardless of availability. BestOffers for candidate Properties will be returned as soon as they are available. It is possible for there to be multiple BestOffers for a single candidate property if we discover a better Offer or additional available amenities after the first is sent. The last BestOffer received for a ResponsiveProperty always supersedes any previously received Offers.

FindBestOffersStreaming is not offered via the HTTP/JSON API.
FindAvailability FindAvailabilityRequest FindAvailabilityResponse Finds availability for a given property, broken down by individual room type. RoomGroups describe the various rooms available to book. Offers describe the cheapest OfferSummary along various dimensions like refundability and loyalty eligible within the RoomGroup.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double   double double float float64 double float Float
float   float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool   bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)