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

| Real-time update (RTU) APIs |||
|---|---|---|
| BookingNotification | **Mandatory** | Send BookingNotification RTUs any time there is a change to the booking (e.g. modifications or cancellations). |
| Availability Replace RTU | **Conditionally required\[1\]** | Send either [batch replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.availability/replace) or [single replace](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/inventory.partners.merchants.services.availability/replace) RTUs to send updates to inventory availability. Changes may take several minutes to propagate and reflect. |
| Merchant RTU | Optional | Send Merchant RTUs if you would like to make changes to merchant information in real-time. Changes may take several hours to propagate and reflect. |
| 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. Changes may take several hours to propagate and reflect. |

> [!NOTE]
> **Note:** The requirement for this endpoint changes based on your integration. Please check with your Google contact to determine which endpoints are required.

## 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](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/real-time-updates-rest/rtu)
- [Java client example for real-time updates using RESTful calls](https://maps-booking.googlesource.com/java-maps-booking-api-example/)
- [Inventory update API reference page](https://developers.google.com/maps-booking/reference/maps-booking-api/rpc#google.maps.booking.v1alpha.inventoryupdate)

## 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](https://developers.google.com/maps-booking/reference/maps-booking-api/rest/v1alpha/notification.partners.bookings/patch#query-parameters). 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](https://cloud.google.com/docs/authentication/getting-started). 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](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/tutorials/authenticate-with-mapsbooking-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](https://developers.google.com/maps-booking/reference/maps-booking-api/rest).

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

| Language | Download link |
|---|---|
| Java | [Java client library](https://dl.google.com/mapsbooking/apiclients/v1alpha/mapsbooking_java_public.zip). For more information, see the [Java client instructions](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/real-time-updates-rest/java-rest). |

Additional
[support libraries](https://developers.google.com/api-client-library) are available for download that
handle authorization and other aspects of calls to Google APIs. If needed,
take a look at
[these samples](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/real-time-updates-rest/code-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](https://github.com/google/google-api-ruby-client) and
[Ruby Auth Library](https://github.com/google/google-auth-library-ruby).

### Make authorized calls to the API

When you make calls to the API, refer to
[Preparing to make an authorized API call](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#authorizingrequests) 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`](https://developers.google.com/maps-booking/reference/maps-booking-api/rpc#google.maps.booking.v1alpha.inventoryupdate) 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()
```