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.

    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.

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

  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.

  4. Download the client library

    While it is possible to make RESTful calls to the Maps Booking API with JSON payloads, we recommend downloading a client library:

    Language Download link
    Java Java client library
    C# C# client library
    PHP PHP client library
    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.

Have questions?

Be sure to check out our FAQs.

Next step

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