7. Call Google APIs for real-time updates (you)

  1. Use the Inventory Update API to provide real-time updates as your merchants' availability changes. This API provides up-to-date information on top of the feeds (step 3), which provide a complete snapshot of their inventory. Real-time updates also help ensure the freshness of your inventory with minimal latency.

    You must use the Inventory Update API to provide availability updates in the following use-cases:

    • When a user books a reservation on your system and therefore the availability slot is no longer available.
    • When a merchant changes their schedule (availability) on your system
    • When a user books a reservation through Google and the availability slot is no longer available.

    Here is a tutorial on how to structure real-time updates.

    For a general code sample you can refer to our Git repository Java client for real-time updates.

    1. APIs vs. Feeds API updates are used to notify Google of inventory changes as they occur in real time. Changes shouldn't be delayed, and shouldn't subsequently be sent in a batch via API.

      API updates can be used for Merchants and Services, but are most useful for Availability updates.

      We prefer feeds over API updates for batch jobs that synchronize large portions of inventory, for the following reasons:

      • Feeds are more efficient in this case.
      • Missing API calls can result in stale inventory which may never updated again. In particular deleting inventory is difficult to do reliably. In contrast, complete feeds will reliably delete any portion of inventory not present in the feed.
    2. API quotas API updates have a quota of 2500 requests every 100 seconds, or 25 requests per second on average.

      When a quota is exceeded, Google responds with the following message:

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

      To handle such a message, retry with exponential backoff (retrying the call again at exponentially larger intervals until it succeeds). If the quotas get reached regularly while doing ReplaceServiceAvailability, it is recommended that you switch to BatchReplaceServiceAvailabily to reduce the number of API calls.

    3. Setting start_time_restrict and end_time_restrict When working with ExtendedServiceAvailbility, you must set the start_time_restrict and the end_time_restrict values to only replace availability within a particular time range. If you leave out one or both of these values, availability will be replaced from the beginning of time to the end of time, respectively. All inventory will be deleted except for what is provided in that particular call. You can set only one of these values to replace only availability before or after a particular date and time.

  2. Use the Booking Notification API to notify Google of changes to an existing booking (e.g. cancellations).

    When sending an update about cancellation, send only the essential information in the request and most importantly use updateMask query parameter:

    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"}
    
  3. Create a service account

    Using the "Credentials" tab in the Developers Console, create a service account and store the private key in JSON format in a safe place. See the image below that shows how to do this. Optionally, you can set the role for the service account to be "Owner".

  4. Use RESTful calls or download the client library

    We recommend making RESTful calls directly to the Maps Booking API with JSON payloads. Please see the REST API in the reference section.

    However, you can also download a client library to build a client for connecting to our API:

    Language Download link
    Java Java client library and see Java client instructions
    Ruby Ruby client library, Ruby auth library. Use API generator with Discovery document.
    Other Please contact our team for recommendations

    In addition, support libraries are available for download that handle authorization and other aspects of calling Google APIs for you.

  5. Fetch the Discovery document

    With some client libraries, e.g. Ruby, it is necessary to fetch the Discovery document for the API, a description of all its methods and parameters.

    Create an API key in the Developers Console and fetch the Discovery document using

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

    where [YOUR_API_KEY] is replaced with the API key you obtained in the Developers Console.

  6. Make calls to the API

    When making calls to the API, refer to this guide to authorize using your service account, private key and the OAuth scope https://www.googleapis.com/auth/mapsbooking.

  7. ** Sandbox vs Production **

    You can make calls to both the sandbox and production environments through the API. Be sure that you have enabled both APIs in your Google Cloud project. Both of these APIs use the same scope, but have a different endpoint. Here 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.sandbox.googleapis.com/") // <---- you add this to change the endpoint to use partnerdev.
          .build()
    

Have questions?

Be sure to check out our FAQs.

Next step

NEXT STEP: End-to-end testing (you)