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"
      }
    }
  }
}

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