Step 5: 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.

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

Availability Replace API RTU

Use the Availability Replace 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:

• Tutorial: how to structure real-time updates
• Java client example for real-time updates using RESTful calls
• Inventory update API reference page

Booking Notification API RTU

The Booking 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."

Authenticate the Maps Booking APIs

After creating a service account, authenticate the following APIs:

• Google Maps Booking API
• Google Maps Booking API (Dev)

For a step-by-step guide on how to do this, refer to the Authenticating with Maps Booking API tutorial.

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.

Additional support libraries are available for download that handle authorization and other aspects of calls to Google APIs. If needed, take a look at these samples.

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 fetch the Discovery document:

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

For more information on accessing the API from Ruby, follow these links: Ruby API Client and Ruby Auth Library.

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 1,500 requests every 60 seconds, or 25 requests per second on average. When a quota is exceeded (which can occur when you haven't added the correct Google Cloud Project number in your Partner Portal), 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()