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
Required |
currency |
string
Required |
user_country |
string
Optional |
device_type |
string
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
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
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
Required |
AvailabilityError
Parameters | |
---|---|
type |
string
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
The value can be set with the assumption that the reservation is made
in advance of the Required |
cancellation_deadline |
string
If the summary is If the summary is 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 |
unstructured_policy |
Required unless rules is fully specified in each RoomRate using this
|
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
Required, unless rule is in effect from the time of booking. |
penalty |
Fee charged if the reservation is canceled after the deadline, or if
the deadline is 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
Required |
cvc_required |
boolean
Required |
Customer
Parameters | |
---|---|
first_name |
string
Required |
last_name |
string
Required |
phone_number |
string
Required |
email |
string
Required |
country |
string
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
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
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 |
array.
Accepted card types (can be empty if cards are not accepted). Required |
unstructured_policies |
array.
Optional |
Payment
Parameters | |
---|---|
type |
string
Required |
payment_token |
string
Required if type is |
payment_card_parameters |
Required if type is |
billing_address |
Required if type is |
PaymentCardParameters
Parameters | |
---|---|
card_type |
string
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 |
Photo
Parameters | |
---|---|
url |
string
Required |
description |
Optional |
Price
Parameters | |
---|---|
amount |
number
Required |
currency |
string
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 Required |
name |
Required |
description |
Optional |
basic_amenities |
Optional |
guarantee_type |
string
Required |
cancellation_policy |
Required |
unstructured_policies |
array.
Optional |
rate_restrictions |
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 in the partner's reservation systems. Required unless error |
hotel_locators |
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 |
Maximum occupancy allowed for this room rate. If not specified, the
room rate must accommodate the party in the
Optional |
total_price_at_booking |
Total price at booking, should equal the sum of Required if an amount is due at booking |
total_price_at_checkout |
Total price at checkout, should equal the sum of Required if an amount is due at checkout |
line_items |
array.
Will not be populated in Required for |
cancellation_rules |
array.
Preferred instead of or in addition to Optional |
unstructured_policies |
array.
Will not be populated in 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 Optional |
RoomType
Parameters | |
---|---|
code |
string
Identifier for the room type, should correspond to Required |
name |
Required |
description |
Optional |
basic_amenities |
Optional |
photos |
array.
Photos of the room Optional |
capacity |
Maximum occupants that the room is capable of accommodating. If not
specified, the room type must accommodate the party in the
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
Required |
message |
string
For debugging. Required |
Enums
Parameters | |
---|---|
AvailabilityErrorType |
|
CancellationSummary |
|
CardType |
|
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 |
|
GuaranteeType |
|
Language |
Hotel Ads language code (e.g., de, en, es, fr, pt-BR, ...) |
LineItemType |
|
Status |
|
SubmitErrorType |
|
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 |
|
November 19, 2019 |
|
September 24, 2019 |
|