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
join_loyalty_program boolean

The customer has requested to join the loyalty program

Optional
loyalty_member_id string

Membership identifier in the loyalty program

Optional

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
rate_restrictions RateRestriction array.

Conditions or restrictions for booking with this RatePlan.

Optional

RateRestriction

Parameters
requires_loyalty_membership boolean

Indicates the rate requires the user to either be a loyalty program member, or to agree to join the loyalty program.

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)
  • LOYALTY_IDENTIFIER_INVALID (the loyalty identifier is invalid or required but missing)
  • LOYALTY_IDENTIFIER_MISMATCH (the loyalty identifier is found but the accompanying information, such as last name or email address, does not match records)
  • LOYALTY_SIGNUP_FAILED (error occurred during loyalty sign-up)
  • 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.

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
July 27, 2020
  • Added RateRestrictions to RatePlan. This provides the capability to specific Loyalty Rates.
  • Added loyalty membership ID and option to join loyalty program to BookingSubmitRequest.
  • Added loyalty-related entries to SubmitErrorType.
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.