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.

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.

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.

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.

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/service.proto

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/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.

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.
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.

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.

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.

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.
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)

Back to top

Copyright © 2025 HotelEngine, Inc., d/b/a Engine
Documentation generated: August 06, 2025
Version: 2.0.0-pre.5