Book on Google API Specification

This document lists Booking Availability and Booking Submit request and response formats, API Object references, and Enum values for Book on Google API.

Booking Availability

Request

Parameters
api_version integer

API version that is specified in the request and is supported by the server.

Required

transaction_id string

Unique ID for the request.

Required

tracking Tracking

Campaign ID and landing page URL are used to pass information of parameters that bring users to the Book on Google checkout page.

Optional

hotel_id string

Partner hotel ID.

Required

start_date string

Check-in date (format YYYY-MM-DD).

Required

end_date string

Check-out date (format YYYY-MM-DD).

Required

party Occupancy

Required

language string

Language enum.

Required

currency string

Currency enum.

Required

user_country string

Country enum.

Optional

device_type string

DeviceType enum.

Optional

Response

Parameters
api_version integer

Required

transaction_id string

Echo

Required

hotel_id string

Echo

Required

start_date string

Echo

Required

end_date string

Echo

Required

party Occupancy

Echo

Required

room_types RoomType array.

Required

rate_plans RatePlan array.

Required

room_rates RoomRate array.

Required

hotel_details HotelDetails

Required: true, unless error.

policies PartnerPolicies

Optional

error AvailabilityError

Optional

Booking Submit

Request

Parameters
api_version integer

Required

transaction_id string

Unique ID for the request.

Required

tracking Tracking

Optional

hotel_id string

Partner hotel ID.

Required

start_date string

Check-in date (format YYYY-MM-DD).

Required

end_date string

Check-out date (format YYYY-MM-DD).

Required

ip_address string

IP address of the user.

Optional

language string

Language enum.

Required

customer Customer

Required

traveler Traveler

Required

room_rate RoomRate

Required

payment Payment

Required

Response

Parameters
api_version integer

Required

transaction_id string

Echo

Required

status string

Status enum.

Required

reservation Reservation

Required

error SubmitError

Optional

API Objects

Address

Parameters
address1 string

Primary street address.

Required

address2 string

Secondary street address, if necessary.

Optional

address3 string

Third portion of the street address, if necessary.

Optional

city string

Name of the state, region, or province.

Required

province string

Name of the state, region, or province.

Optional

postal_code string

Postal code.

Required except for within HotelDetails

country string

Country enum.

Required

AvailabilityError

Parameters
type string

AvailabilityErrorType enum.

Required

message string

For debugging.

Required

BasicAmenities

Parameters
free_breakfast boolean

Optional

free_wifi boolean

Optional

free_parking boolean

Optional

BedTypes

Parameters
total_beds integer

Optional

king_beds integer

Optional

queen_beds integer

Optional

double_beds integer

Optional

single_or_twin_beds integer

Optional

murphy_beds integer

Optional

sofa_beds integer

Optional

bunk_beds integer

Optional

other_beds integer

Optional

CancellationPolicy

Parameters
summary string

CancellationSummary enum.

The value can be set with the assumption that the reservation is made in advance of the cancellation_deadline, and the policy displayed to the user will be adjusted as needed if the cancellation_deadline has already passed.

Required

cancellation_deadline string

If the summary is FREE_CANCELLATION, this is the date and time after which it is no longer possible to cancel the reservation without a penalty. If a penalty is only charged in the case of a no show, this value should be set to NO_SHOW. If there is never a penalty for cancellation or no show, this field should be set to an empty string.

If the summary is PARTIAL_REFUND, this is the date and time after it is no longer possible to cancel the reservation without a penalty less than the total amount paid, if there was a deposit, or less than the total amount of the reservation, if there was not a deposit. If a penalty of at least the total amount paid, if there was a deposit, or at least the total amount of the reservation, if there was not a deposit, is only charged in the case of a no show, this value should be set to NO_SHOW. If there is never a penalty for cancellation or no show of at least the total amount paid, if there was a deposit, or at least the total amount of the reservation, if there was not a deposit, this field should be set to an empty string.

If the value is a date and time, this field is in ISO 8601 format YYYY-MM-DDThh:mm:ss+/-hh:mm.

Required if summary is FREE_CANCELLATION or PARTIAL_REFUND

unstructured_policy DisplayString

Required unless rules is fully specified in each RoomRate using this RatePlan.

CancellationRule

Parameters
deadline string

Date and time after which the cancellation rule takes effect, or empty if the rule is in effect from the time of booking (ISO 8601 format YYYY-MM-DDThh:mm:ss+/-hh:mm), or NO_SHOW for a no show fee charged if the user neither cancels nor shows up for the reservation.

Required, unless rule is in effect from the time of booking.

penalty Price

Fee charged if the reservation is canceled after the deadline, or if the deadline is NO_SHOW, the fee charged if user does not show up. If the fee is less than the deposit, a refund will be issued, and if it is greater than the deposit, the additional balance will be collected.

Required

Capacity

Parameters
adults string

If only a total person capacity is known, consider all to be adults.

Required

children integer

Number of children allowed per room.

Optional

CardOption

Parameters
card_type string

CardType enum.

Required

cvc_required boolean

Required

Customer

Parameters
first_name string

Required

last_name string

Required

phone_number string

Phone format

Required

email string

Required

country string

Country enum.

Required

DisplayString

Parameters
text string

Required

language string

Language enum, should match language in request if possible.

Required, unless language is not known.

Geolocation

Parameters
latitude number

Decimal representation with positive for north of the equator and negative for south of the equator.

Required

longitude number

Decimal representation with positive for east of the prime meridian and negative for west of the prime meridian.

Required

HotelDetails

Parameters
name string

Name of the hotel property.

Required

address Address

Address of the hotel property.

Required

geolocation Geolocation

Represents a latitude and longitude coordinate location.

Optional

phone_number string

The phone number customers can use to reach the hotel.

Optional

email string

The email address customers can use to reach the hotel.

Optional

homepage_url string

The url for the hotel's home page.

Optional

policies HotelPolicies

Optional

photos Photo array.

Photos of the hotel.

Optional

HotelPolicies

Parameters
check_in_time string

Check-in time in the hotel's local time zone including the time zone if possible (ISO 8601 format hh:mm or hh:mm+/-hh:mm).

Optional

check_out_time string

Check-out time in the hotel's local time zone including the time zone if possible (ISO 8601 format hh:mm or hh:mm+/-hh:mm).

Optional

max_child_age integer

Maximum age for a guest to be considered a child.

Optional

unstructured_policies DisplayString array.

Optional

LineItem

Parameters
price Price

Price should be for the reservation and for the stay, unless stay_date is specified, in which case it should be for the particular night of the stay.

Required

type string

LineItemType enum.

Required

paid_at_checkout boolean

True if the price is paid at checkout, false if the price is paid at booking.

Required

description DisplayString

Optional

stay_date string

Date for which the price applies, used for nightly price breakdown (format YYYY-MM-DD).

Optional

Locator

Parameters
id string

Unique identifier for the reservation.

Required

pin string

Password needed to access the reservation.

Optional

Occupancy

.
Parameters
adults integer

If only a total person occupancy is known, consider all to be adults.

Required

children integer array.

One element per child occupant with value equal to the child's age in years.

Optional

PartnerPolicies

Parameters
card_options CardOption array.

Accepted card types (can be empty if cards are not accepted).

Required

unstructured_policies DisplayString array.

Optional

Payment

Parameters
type string

GuaranteeType enum.

Required

payment_token string

Required if type is PAYMENT_CARD and tokenized payments are being used.

payment_card_parameters PaymentCardParameters

Required if type is PAYMENT_CARD unless tokenized payments are being used, in which case payment_token will be populated instead.

billing_address Address

Required if type is PAYMENT_CARD unless tokenized payments are being used.

PaymentCardParameters

Parameters
card_type string

CardType enum

Required

card_number string

Required

cardholder_name string

Required

expiration_month string

2-digit month (format MM).

Required

expiration_year string

4-digit year (format YYYY).

Required

cvc string

Required if cvc_required in the CardOption is true.

Photo

Parameters
url string

Required

description DisplayString

Optional

Price

Parameters
amount number

Required

currency string

Currency enum

Should match currency that user will be charged in (requested currency if possible, but typically hotel currency for amounts due at hotel).

Required

RatePlan

Parameters
code string

Identifier for the rate plan should correspond to PackageID in the RoomBundle.

Required

name DisplayString

Required

description DisplayString

Optional

basic_amenities BasicAmenities

Optional

guarantee_type string

GuaranteeType enum.

Required

cancellation_policy CancellationPolicy

Required

unstructured_policies DisplayString array.

Optional

Reservation

Parameters
locator Locator

Locator in the partner's reservation systems.

Required unless error

hotel_locators Locator array.

Locator in the hotel's reservation system, with either one element for the reservation or one element for each room.

Optional

hotel_id string

Echo

Required

start_date string

Echo

Required

end_date string

Echo

Required

customer Customer

Echo

Required

traveler Traveler

Echo

Required

room_rate RoomRate

Echo

Required

RoomRate

Parameters
code string

Identifier for the room rate.

Required

room_type_code string

Identifier for the associated room type.

Required

rate_plan_code string

Identifier for the associated rate plan.

Required

maximum_allowed_occupancy Capacity

Maximum occupancy allowed for this room rate. If not specified, the room rate must accommodate the party in the BookingAvailabilityRequest.

Optional

total_price_at_booking Price

Total price at booking, should equal the sum of line_items for which paid_at_checkout is false.

Required if an amount is due at booking

total_price_at_checkout Price

Total price at checkout, should equal the sum of line_items for which paid_at_checkout is true.

Required if an amount is due at checkout

line_items LineItem array.

Will not be populated in BookingSubmitRequest.

Required for BookingAvailabilityResponse

cancellation_rules CancellationRule array.

Preferred instead of or in addition to CancellationPolicy/unstructued_policy when available. Will not be populated in BookingSubmitRequest.

Optional

unstructured_policies DisplayString array.

Will not be populated in BookingSubmitRequest.

Optional

partner_data string array.

Arbitrary data to be echoed back in the booking submission.

Optional

room_count integer

Number of rooms that can be booked with this room rate. Will not be populated in BookingSubmitRequest.

Optional

RoomType

Parameters
code string

Identifier for the room type, should correspond to RoomID in the RoomBundle.

Required

name DisplayString

Required

description DisplayString

Optional

basic_amenities BasicAmenities

Optional

photos Photo array.

Photos of the room

Optional

capacity Capacity

Maximum occupants that the room is capable of accommodating. If not specified, the room type must accommodate the party in the BookingAvailabilityRequest.

Optional

bed_types BedTypes

Optional

unstructured_policies DisplayString array

Optional

Tracking

Parameters
campaign_id string

Optional

pos_url string

Landing page (point of sale) URL, a deep link to the partner's website that may contain tracking parameters.

Optional

Traveler

Parameters
first_name string

Required

last_name string

Required

occupancy Occupancy

Required

SubmitError

Parameters
type string

SubmitErrorType enum

Required

message string

For debugging.

Required

Enums

Parameters
AvailabilityErrorType
  • UNKNOWN_ERROR (error type is unknown)
  • API_VERSION_UNSUPPORTED (API version specified in the request is not supported by the server)
  • DATE_SELECTION_INVALID (specified dates are invalid or in the past)
  • HOTEL_NOT_FOUND (a hotel with the specified ID could not be found)
  • NETWORK_ERROR (network error while communicating with a third-party system)
  • RECOVERABLE_ERROR (service is temporarily unavailable)
  • REQUEST_DATA_INVALID (request contains a field with data in an invalid format)
  • REQUEST_INCOMPLETE (request is missing a required field)
  • REQUEST_NOT_PARSABLE (request cannot be parsed other than a field containing data in an invalid format or missing a required field)
  • SUPPLIER_ERROR (error returned by a supplier system that does not fit into a recognized error type)
CancellationSummary
  • UNKNOWN_CANCELLATION_POLICY (cancellation policy is unknown)
  • FREE_CANCELLATION (there is a period of time during which the reservation can be canceled without penalty and full refund of any deposit)
  • NON_REFUNDABLE (there is no period of time during which the reservation can be canceled with a penalty less than the total amount paid, if there was a deposit, or less than the total amount of the reservation, if there was not a deposit)
  • PARTIAL_REFUND (there is no period of time during which the reservation can be canceled without penalty, but there is a period of time during which it can be canceled with a penalty less than the total amount paid if there was a deposit, or less than the total amount of the reservation, if there was not a deposit)
CardType
  • AX (American Express)
  • DC (Diners Club)
  • DS (Discover)
  • JC (JCB)
  • MC (Mastercard)
  • VI (Visa)
Country ISO 3166 country code (e.g., CA, DE, ES, FR, GB, IE, US, …)
Currency ISO 4217 currency code (e.g., CAD, EUR, GBP, USD, …)
DeviceType
  • UNKNOWN_DEVICE_TYPE
  • DESKTOP
  • MOBILE
  • TABLET
GuaranteeType
  • NO_GUARANTEE (payment information is not required at the time of booking)
  • PAYMENT_CARD (the user provides a credit or debit card when booking the reservation)
Language Hotel Ads language code (e.g., de, en, es, fr, pt-BR, ...)
LineItemType
  • BASE_RATE (base room rate)
  • UNKNOWN_TAXES_AND_FEES (taxes and/or fees that cannot be separated or are of an unknown type)
  • UNKNOWN_TAXES (taxes that cannot be separated or of an unknown type)
  • TAX_MUNICIPAL (tax applied by a city or municipality, such as a sales or tourism tax)
  • TAX_VAT (VAT or GST)
  • TAX_OTHER (tax that does not fall into another defined type)
  • UNKNOWN_FEES (fees that cannot be separated or of an unknown type)
  • FEE_BOOKING (fee applied by the advertiser or booking partner)
  • FEE_HOTEL (fee applied by the hotel that does not fall into another defined type)
  • FEE_RESORT (fee applied by the hotel for resort-type accommodations or other amenities)
  • FEE_TRANSFER (fee applied by the hotel for transportation, such as transfers or connections)
  • FEE_OTHER (fee that does not fall into another defined type)
Status
  • SUCCESS
  • FAILURE
SubmitErrorType
  • UNKNOWN_ERROR (error type is unknown)
  • API_VERSION_UNSUPPORTED (API version specified in the request is not supported by the server)
  • CHECKIN_TOO_CLOSE (the partner or hotel cannot support this booking as it is too close to the check-in date or time)
  • CUSTOMER_NAME_INVALID (the customer name is invalid)
  • DATE_SELECTION_INVALID (specified dates are invalid or in the past)
  • DUPLICATE_BOOKING (the booking appears to be a duplicate of an existing reservation)
  • HOTEL_NOT_FOUND (a hotel with the specified ID could not be found)
  • NETWORK_ERROR (network error while communicating with a third-party system)
  • PAYMENT_BILLING_ADDRESS_INVALID (billing address invalid or missing information)
  • PAYMENT_CARD_CARDHOLDER_NAME_INVALID (payment card cardholder name is invalid)
  • PAYMENT_CARD_CVC_INVALID (payment card CVC is missing or invalid)
  • PAYMENT_CARD_EXPIRATION_INVALID (payment card expiration date is invalid or has expired)
  • PAYMENT_CARD_NUMBER_INVALID (payment card number is not valid for the card type)
  • PAYMENT_CARD_TYPE_NOT_SUPPORTED (payment card type is unrecognized or not supported for this reservation)
  • PAYMENT_DECLINED (payment declined by the processor or by partner risk assessment)
  • PAYMENT_INVALID (error processing the payment that does not fit into a recognized error type)
  • PAYMENT_INSUFFICIENT (payment does not have sufficient funds or credit to cover the transaction)
  • PAYMENT_PROCESSOR_ERROR (error returned by a payment processor that does not fit into a recognized error type)
  • PAYMENT_TYPE_NOT_ACCEPTED (payment type is unrecognized or not accepted for this reservation)
  • RATE_PLAN_UNAVAILABLE (rate plan code is unrecognized or not available)
  • RECOVERABLE_ERROR (service is temporarily unavailable)
  • REQUEST_DATA_INVALID (request contains a field with data in an invalid format)
  • REQUEST_INCOMPLETE (request is missing a required field)
  • REQUEST_NOT_PARSABLE (request cannot be parsed other than a field containing data in an invalid format or missing a required field)
  • ROOM_RATE_MISMATCH (room rate details are invalid or out of date other than pricing)
  • ROOM_RATE_PRICE_MISMATCH (room rate pricing details are out of date)
  • ROOM_RATE_UNAVAILABLE (room rate code is unrecognized or not available)
  • ROOM_TYPE_UNAVAILABLE (room type code is unrecognized or not available)
  • TRAVELER_NAME_INVALID (the traveler name is invalid)
  • SUPPLIER_ERROR (error returned by a supplier system that does not fit into a recognized error type)

Notes

  • JSON format is used.
  • Security: HTTP basic authentication with HTTPS connections are required, whitelisting of Google IP blocks is encouraged.
  • Currency: Google will convert transaction currency to user currency if they don't match and show both to the user.
  • To match room rates between the BookingAvailabilityResponse and the RoomBundle data, the RoomType/code should match the RoomID in the RoomBundle and the RatePlan/code should match the PackageID in the RoomBundle.
  • Latency target is no more than 20 seconds for the 90th percentile. Timeout is after 60 seconds.

Messaging Flows

  • Room Booking Module (RBM) data comes from Room Bundles provided by the Hotel Prices and Hotel Ads APIs and cached by Google.
  • Selecting a room from the RBM takes the user to the Book on Google checkout page. When this page loads, a Booking Availability request is issued to the partner to confirm the current room rates that are available for the hotel and get additional details about the room types and rate plans than is provided in the Room Bundles.
  • After the user confirms their room selection, enters guest details and payment information, and clicks the reserve button, a Booking Submit request is issued to the partner to complete the reservation in the partner's system.
  • Upon a successful response, the user is shown a confirmation page.

Hotel Booking - API Validator Utility

The Hotel Booking API Validator utility will send a request body you specify for any of the service endpoints and validate the response. The validator will verify that the request and response bodies have valid schema according to the v1 API proto file and will also validate the response body correctly echoes the criteria provided in the request body.

Refer to Google hotel booking api validator.

Sample Request / Response Documents

Refer to Google hotel booking api validator data.

Revision History

Date Changes
November 19, 2019
  • Changed Address/province to be optional.
  • Added Payment/payment_token to support tokenized payments and updated the conditions under which Payment/payment_card_parameters and Payment/billing_address are required.
September 24, 2019
  • Changed Address/postal_code to be optional when within HotelDetails.