Book on Google API

The booking feature of Book on Google (BoG) enables users to:

  • Book a hotel room.
  • View room photos.
  • Check prices and amenities.

The Book on Google program allows Google partners in the travel industry to use a Google-hosted reservation and payment page.

When users click a booking link for a partner who has enabled the Book on Google feature, they enter the Book on Google path where they can check information already stored in their Google profile with their credit card.

Partner requirements for BoG API integration

To begin BoG integration, partners need to have the following:

  • Certification of PCI compliance and proof of third-party penetration testing. PCI compliance can be waived if using tokenized payments.
  • A compatible Hotels Booking Availability and Booking Submit API supporting shopping requests and booking requests with payments.
  • Hotel Ads account with sufficient properties and bids.
  • Localized room descriptions for localized target market.
  • Localized self-service and/or telephone support for customer support and reservation changes after booking.

To use Tokenized Payments, partners need to have the following:

BoG Standard API

The BoG Standard API consists of two calls: Booking Availability and Booking Submit.

Google Hotel Ads has enabled users to find available hotels and book a hotel reservation on the Book hotels on Google feature using mobile and desktop. Users don’t need to leave the Google landing page to book rooms. Google makes the reservation, takes the billing and customer information, and then passes the information to the partner after the transaction is complete.

Booking Availability request example

{
  "api_version": 1,
  "transaction_id": "641e10d1-0b50-4872-b05a-26630a69b42c",
  "tracking": {
    "campaign_id": "20190401",
    "pos_url": "https://example.com/book?track=gb2019CA&track2=bookongoogle"
  },
  "hotel_id": "123",
  "start_date": "2019-04-03",
  "end_date": "2019-04-05",
  "party": {
    "adults": 2,
    "children": [
      7
    ]
  },
  "language": "en",
  "currency": "USD",
  "user_country": "US",
  "device_type": "DESKTOP"
}

Booking Availability response example

{
   "api_version":1,
   "transaction_id":"641e10d1-0b50-4872-b05a-26630a69b42c",
   "hotel_id":"123",
   "start_date":"2019-04-03",
   "end_date":"2019-04-05",
   "party":{
      "adults":2,
      "children":[
         7
      ]
   },
   "room_types":[
      {
         "code":"MSTE",
         "name":{
            "text":"Master Suite",
            "language":"en"
         },
         "description":{
            "text":"The Master Suite of the Grand Budapest Hotel complete has
             spacious living area for you and your family",
            "language":"en"
         },
         "basic_amenities":{
            "free_breakfast":true,
            "free_wifi":true,
            "free_parking":true
         },
         "photos":[
            {
               "url":"https://example.com/photos/970cdb64-613e-413b-a664-4b249509c4bd.jpg",
               "description":{
                  "text":"A sumptous hand-woven rug adorns the entry to the master suite",
                  "language":"en"
               }
            },
            {
               "url":"https://example.com/photos/aa94add5-bae2-41b0-9de7-6e19d408697b.jpg",
               "description":{
                  "text":"The master suite features 3 bedrooms with ensuite bathrooms",
                  "language":"en"
               }
            }
         ],
         "capacity":{
            "adults":2,
            "children":3
         }
      },
      {
         "code":"DBLQ",
         "name":{
            "text":"Double Queen Beds",
            "language":"en"
         },
         "description":{
            "text":"Two queen-sized beds and a desk with a stylish reading lamp",
            "language":"en"
         },
         "basic_amenities":{
            "free_breakfast":true,
            "free_wifi":true,
            "free_parking":true
         },
         "photos":[
            {
               "url":"https://example.com/photos/c2d3a318-d43f-4c23-a003-e495d8167f7b.jpg",
               "description":{
                  "text":"Two queen-sized beds with designer comforters",
                  "language":"en"
               }
            },
            {
               "url":"https://example.com/photos/8ffb38a7-0db6-4ad7-b2bf-8b08d102fab0.jpg",
               "description":{
                  "text":"Personal reading lamp for guest use",
                  "language":"en"
               }
            }
         ],
         "capacity":{
            "adults":2,
            "children":2
         }
      }
   ],
   "rate_plans":[
      {
         "code":"BEST",
         "name":{
            "text":"Best Price Guarantee",
            "language":"en"
         },
         "description":{
            "text":"The best possible price for our rooms, or your money back",
            "language":"en"
         },
         "guarantee_type":"PAYMENT_CARD",
         "cancellation_policy":{
            "summary":"FREE_CANCELLATION",
            "cancellation_deadline":"2019-03-28T12:00:00+00:00"
         }
      }
   ],
   "room_rates":[
      {
         "code":"RATE1",
         "room_type_code":"MSTE",
         "rate_plan_code":"BEST",
         "maximum_allowed_occupancy":{
            "adults":2
         },
         "total_price_at_checkout":{
            "amount":562,
            "currency":"USD"
         },
         "line_items":[
            {
               "price":{
                  "amount":50,
                  "currency":"USD"
               },
               "type":"UNKNOWN_TAXES_AND_FEES",
               "paid_at_checkout":true,
               "description":{
                  "text":"Standard foreign reservation fee",
                  "language":"en"
               }
            },
            {
               "price":{
                  "amount":384,
                  "currency":"USD"
               },
               "type":"BASE_RATE",
               "paid_at_checkout":true
            },
            {
               "price":{
                  "amount":128,
                  "currency":"USD"
               },
               "type":"TAX_VAT",
               "paid_at_checkout":true
            }
         ],
         "cancellation_rules":[
            {
               "deadline":"2019-03-28T12:00:00+00:00",
               "penalty":{
                  "amount":100,
                  "currency":"USD"
               }
            }
         ]
      },
      {
         "code":"RATE2",
         "room_type_code":"DBLQ",
         "rate_plan_code":"BEST",
         "maximum_allowed_occupancy":{
            "adults":2
         },
         "total_price_at_checkout":{
            "amount":178,
            "currency":"USD"
         },
         "line_items":[
            {
               "price":{
                  "amount":50,
                  "currency":"USD"
               },
               "type":"UNKNOWN_TAXES_AND_FEES",
               "paid_at_checkout":true,
               "description":{
                  "text":"Standard foreign reservation fee",
                  "language":"en"
               }
            },
            {
               "price":{
                  "amount":96,
                  "currency":"USD"
               },
               "type":"BASE_RATE",
               "paid_at_checkout":true
            },
            {
               "price":{
                  "amount":32,
                  "currency":"USD"
               },
               "type":"TAX_VAT",
               "paid_at_checkout":true
            }
         ],
         "cancellation_rules":[
            {
               "deadline":"2019-03-28T12:00:00+00:00",
               "penalty":{
                  "amount":100,
                  "currency":"USD"
               }
            }
         ]
      }
   ],
   "hotel_details":{
      "name":"The Grand Budapest Hotel",
      "address":{
         "address1":"78 Rue du Grand Hotel",
         "city":"Zubrowka City",
         "province":"Grand Zubrowka",
         "postal_code":"ZK-2014",
         "country":"US"
      },
      "geolocation":{
         "latitude":59.940715,
         "longitude":30.32543
      },
      "phone_number":"+1-(555)-1234-567",
      "policies":{
         "check_in_time":"14:00",
         "check_out_time":"11:00"
      },
      "photos":[
         {
            "url":"https://example.com/photos/948c7584-cfc7-496d-890e-99fa637983fe.jpg",
            "description":{
               "text":"The entrance to the Grand Budapest Hotel",
               "language":"en"
            }
         },
         {
            "url":"https://example.com/photos/b9576abf-b516-4e29-93cd-1ffb3531a1b0.jpg",
            "description":{
               "text":"Enjoy our pool and spa",
               "language":"en"
            }
         }
      ]
   },
   "policies":{
      "card_options":[
         {
            "card_type":"AX",
            "cvc_required":true
         },
         {
            "card_type":"VI",
            "cvc_required":true
         },
         {
            "card_type":"MC",
            "cvc_required":true
         },
         {
            "card_type":"DS",
            "cvc_required":true
         }
      ]
   }
}

Booking Submit request example

{
  "api_version": 1,
  "transaction_id": "641e10d1-0b50-4872-b05a-26630a69b42c",
  "tracking": {
    "campaign_id": "gb2019CA",
    "pos_url": "https://example.com/book?track=gb2019CA&track2=bookongoogle"
  },
  "hotel_id": "123",
  "start_date": "2019-04-03",
  "end_date": "2019-04-05",
  "ip_address": "123.234.345.456",
  "language": "en",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "555-444-3333",
    "email": "email@example.com",
    "country": "US"
  },
  "traveler": {
    "first_name": "John",
    "last_name": "Doe",
    "occupancy": {
      "adults": 2,
      "children": [
        7
      ]
    }
  },
  "room_rate": {
    "code": "RATE1",
    "room_type_code": "MSTE",
    "rate_plan_code": "BEST",
    "maximum_allowed_occupancy": {
      "adults": 2
    },
    "total_price_at_checkout": {
      "amount": 562,
      "currency": "USD"
    }
  },
  "payment": {
    "type": "PAYMENT_CARD",
    "payment_card_parameters": {
      "card_type": "VI",
      "card_number": "4111111111111111",
      "cardholder_name": "John Doe",
      "expiration_month": "12",
      "expiration_year": "21"
    },
    "billing_address": {
      "address1": "123 Main St.",
      "city": "Chicago",
      "province": "IL",
      "postal_code": "60607",
      "country": "US"
    }
  }
}

Booking Submit request example (tokenized payments)

For partners using tokenized payments, the BookingSubmitRequest will supply the payment_token instead of the payment_card_parameters and billing_address.

{
  "api_version": 1,
  "transaction_id": "641e10d1-0b50-4872-b05a-26630a69b42c",
  "tracking": {
    "campaign_id": "gb2019CA",
    "pos_url": "https://example.com/book?track=gb2019CA&track2=bookongoogle"
  },
  "hotel_id": "123",
  "start_date": "2019-04-03",
  "end_date": "2019-04-05",
  "ip_address": "123.234.345.456",
  "language": "en",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "555-444-3333",
    "email": "email@example.com",
    "country": "US"
  },
  "traveler": {
    "first_name": "John",
    "last_name": "Doe",
    "occupancy": {
      "adults": 2,
      "children": [
        7
      ]
    }
  },
  "room_rate": {
    "code": "RATE1",
    "room_type_code": "MSTE",
    "rate_plan_code": "BEST",
    "maximum_allowed_occupancy": {
      "adults": 2
    },
    "total_price_at_checkout": {
      "amount": 562,
      "currency": "USD"
    }
  },
  "payment": {
    "type": "PAYMENT_CARD",
    "payment_token": "----REDACTED----"
  }
}

Booking Submit response example

{
  "api_version": 1,
  "transaction_id": "641e10d1-0b50-4872-b05a-26630a69b42c",
  "status": "SUCCESS",
  "reservation": {
    "locator": {
      "id": "googleapi-e7fafbb0a132fb519d0e1b82b23dc794"
    },
    "hotel_locators": [
      {
        "id": "GB123-02ae0db95944feac57e4ee56be661975"
      }
    ],
    "hotel_id": "123",
    "start_date": "2019-04-03",
    "end_date": "2019-04-05",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": "555-444-3333",
      "email": "email@example.com",
      "country": "US"
    },
    "traveler": {
      "first_name": "John",
      "last_name": "Doe",
      "occupancy": {
        "adults": 2,
        "children": [
          7
        ]
      }
    },
    "room_rate": {
      "code": "RATE1",
      "room_type_code": "MSTE",
      "rate_plan_code": "BEST",
      "maximum_allowed_occupancy": {
        "adults": 2
      },
      "total_price_at_checkout": {
        "amount": 562,
        "currency": "USD"
      }
    }
  }
}

Room and rate matching

Room Booking Module (RBM) data is generated from Room Bundles provided by the Hotel Prices and Hotel Ads APIs and cached by Google.

When a user selects a room from the RBM, the Book on Google checkout page loads. When the Book on Google 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.

To match rooms and rates between the RBM and the Book on Google checkout flow, the RoomType/code field from the Booking Availability response should match the RoomID field in the RoomBundle, and the RatePlan/code field from the Booking Availability response should match the PackageID in the Room Bundle.

After users confirm their room selection, they enter guest details and payment information. When they click 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 gets a confirmation page. When a partner sends requests, Google redirects the users to a confirmation page hosted by the partner instead of our confirmation page. Their confirmation page must include the same information provided on our confirmation page.

The single-partner carousel groups rooms from each partner separately under different tabs.

Partners are ranked by their bid and quality score (after smart pricing adjustment).

Room bundles for each partner are first ranked by price, then alphabetically, and are deduped as follows to prevent repetition:

  • If multiple room bundles only differ by occupancy (same title, inclusions, etc.), and are the same price, only the highest occupancy bundle displays.
  • If the room photo for a bundle is the same as the room photo for the previous bundle, the second bundle does not show.

All room bundles (even those that are deduped) are visible at later stages of the flow (for example, the checkout flow or room details page).