Real-time API updates

Inventory in your system fluctuates throughout the day due to new bookings, cancellations, and schedule changes from your merchants. The real-time update API is a mechanism to notify Google about these changes in inventory availability. You can also use real-time API updates to notify Google of changes that are made to existing bookings.

Real-time updates aren't necessary if the following is true:

API real-time updates and feeds

API real-time updates are used to notify Google of incremental changes to inventory availability and bookings as they occur in real-time. In addition to real-time API updates, send complete Availability feeds daily to ensure that Google has the most accurate and current knowledge of availability as it exists in your system. Complete feeds act as a snapshot of the current state of inventory availability in your system.

Although API updates can be used to update any information that is provided by feeds, such as information about merchants and services, they are typically used only to update availability information.

Required Real-time update APIs

Real-time update (RTU) APIs
InventoryUpdate RTU Conditionally required[1] Send either batch replace or single replace Inventory Update RTUs to send updates to inventory availability.
BookingNotification or OrderNotification RTU Mandatory Send BookingNotification or OrderNotification RTUs any time there is a change to the booking or order (e.g. modifications or cancellations) Please implement OrderNotification RTU if you have followed the Order based implementation.
Merchant RTU Optional Send Merchant RTUs if you would like to make changes to merchant information in real-time.
Service RTU Optional Send Service RTUs if you would like to make changes to service information in real-time. A common use case is if service prices fluctuate dramatically during the day, implementing Service RTUs is recommended to avoid order failures due to price mismatch.

Inventory Update API RTU

Use the Inventory Update API to provide availability updates in the following use cases:

  • A user books a reservation on your system, so the availability slot is no longer available.
  • A merchant changes their availability in your system.
  • A user books a reservation through Google, so the availability slot is no longer available.
  • A reservation made through Google is cancelled on your side, for example, by the merchant directly. You need to update the booking as well as the availability, because the original slot is now available again.
  • A booking server BatchAvailabilityLookup call returns inventory that doesn't match the actual inventory.

For more information, refer to the following resources:

Booking/Order Notification API RTU

The Booking Notification or Order Notification APIs notifies Google about updates to existing bookings. When you send an update about cancellations, send only the essential information in the request with the updateMask query parameter. Here is an example:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Accessing the API

Create a service account

Use the Credentials tab in the Google API Console to create a service account. Store the private key in JSON format in a safe place. When you create the account, you have the option to set the role to "Owner."

Use RESTful calls or download the client library

We recommend that you make RESTful calls directly to the Maps Booking API with JSON payloads. For more information, see the REST API documentation.

You can also use client libraries to connect to the API.

Language Download link
Java Java client library. For more information, see the Java client instructions.

Additional support libraries are available for download that handle authorization and other aspects of calls to Google APIs.

Fetch the Discovery document

For some client libraries such as Ruby, it's necessary to fetch the Discovery document for the API, which describes its methods and parameters.

Use the following command to create an API key in the Google API console and fetch the Discovery document:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha&key=[YOUR_API_KEY]'

Make authorized calls to the API

When you make calls to the API, refer to Preparing to make an authorized API call to authorize your service account with your private key and the following OAuth scope: https://www.googleapis.com/auth/mapsbooking.

API quotas

API updates have a quota of 2,500 requests every 100 seconds, or 25 requests per second on average. When a quota is exceeded, Google responds with the following error message:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

To handle this, retry the call again at exponentially larger intervals until it succeeds. If you regularly exhaust the quota with ReplaceServiceAvailability, switch to BatchReplaceServiceAvailabily to reduce the number of API calls. This method allows you to update multiple services in a single API call.

Sandbox and Production Endpoints

You can make calls to both the sandbox and production environments through the API. Be sure that you've enabled both APIs in your Google Cloud project. Both of these APIs use the same scope, but they have different endpoints.

Production endpoint: https://mapsbooking.googleapis.com/

Sandbox endpoint: https://partnerdev-mapsbooking.googleapis.com/

The following is an example in Java of how to switch endpoints:

    // This block of code is for OAuth and is the same for prod and sandbox.
      GoogleCredential
        .fromStream(new FileInputStream(...))

    .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)

      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // <---- you add this to change the endpoint to use partnerdev.
        .build()