Reservations Redirect Querying Merchant Status via the API

AI-generated Key Takeaways

• The Google Maps Booking API offers two methods to retrieve individual merchant statuses for various integrations or Local Services Ads inventory.

• The merchant status information includes inventory and matching statuses, details on the matched business listing, service provider information (for Local Services Ads), and URLs showing how the merchant is surfaced on Google.

• You can look up the status of a single merchant using the inventory.partners.merchants.getStatus method.

• You can retrieve the statuses of multiple merchants in bulk using the inventory.partners.merchants.status.list method, with options to filter based on inventory or matching conditions.

• It is recommended to cache merchant statuses and retrieve updates periodically (e.g., every few hours) to avoid excessive requests.

Use cases

Google Maps Booking API provides two methods, which can be used to programmatically retrieve a status of the individual merchants for various integrations or Local Services Ads inventory.

Use cases for Merchant Status API:

• Enhance existing customer relation management tools to demonstrate your customers how their inventory is surfaced on Google.
• Build a dashboard to track the inventory status and matching status of your merchants.
• Programmatically retrieve matching and bookable statuses of your merchants and fix any incorrect information to improve data quality.

What does the merchant status contain

The MerchantStatus contains the following information:

• Merchant inventory status: applies to both booking and/or waitlist merchants.
• Merchant matching status: includes details on the matched business listing
• For Google Local Services Ads only) Matched merchant service provider: includes the customer ID and service categories.
• The URLs to demonstrate how the merchant is surfaced on Google.

Look up a single merchant status

You can get the status of a single merchant using inventory.partners.merchants.getStatus:

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}/status

Here is a Python code sample (see examples in more languages here):

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    './your_key.json')
scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/mapsbooking'])
authed_session = AuthorizedSession(scoped_credentials)

response = authed_session.get('https://partnerdev-mapsbooking.googleapis.com' +
    '/v1alpha/inventory/partners/123456789/merchants/001/status')

An example MerchantStatus response looks like:

  {
    "name": "partners/123456789/merchants/001/status",
    "merchantName": "Foo Bar Restaurant",
    "inputGeoInfo": {
      "unstructured_address": "123 Foo Bar Street, Mountain View"
    },
    "processingStatus": "COMPLETED",
    "bookingStatus": {
      "hasValidFutureInventory": true
    },
    "waitlistStatus": {
      "hasValidWaitlistService": true
    }
    "geoMatch": {
      "name": "Foo Bar Restaurant",
      "formattedAddress": "123 Foo Bar St, Mountain View, CA 94043",
      "placeId": "ChIAAAAAAAAABBBBBBBB"
    },
    "directUrls": [
      {
        "type": "BOOKING",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/dine/m/Nwaaaaa"
      },
      {
        "type": "WAITLIST",
        "url": "https://reserve-partnerdev.sandbox.google.com/maps/reserve/v/wait/c/iDbbbbb"
      }
    ]
  }

Retrieve merchant statuses in bulk

You can retrieve statuses of all merchants, or a group of merchants satisfying certain inventory/matching conditions, using inventory.partners.merchants.status.list. For example, you can make this call to get all unmatched merchants with valid future-dated booking inventory:

GET https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/status?pageSize=50&bookingInventoryStatusRestrict=HAS_VALID_FUTURE_INVENTORY&geoMatchRestrict=GEO_UNMATCHED

A sample response would look like this:

  {
    "merchantStatuses": [
      {
        "name": "partners/123456789/merchants/002/status",
        "merchantName": "Bar Foo Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "234 Bar Foo Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {},
      },
      ...
      {
        "name": "partners/123456789/merchants/080/status",
        "merchantName": "Baz Restaurant",
        "inputGeoInfo": {
          "unstructured_address": "345 Baz Street, Mountain View"
        },
        "processingStatus": "COMPLETED",
        "bookingStatus": {
          "hasValidFutureInventory": true
        },
        "waitlistStatus": {
          "hasValidWaitlistService": true
        },
      },
    ],
    "nextPageToken": "AAABBBB"
  }

This response will contain 50 MerchantStatus that satisfy the filtering conditions and ordered by merchant_id. The response also contains a page token (if it is not the last page) to query the next page.

Please note: the filtering conditions should be consistent across all pages.

Best Practices

Since merchant statuses do not change frequently in most times, it is encouraged to cache the retrieved results and periodically (e.g. every few hours) retrieve them via new queries. The Actions Center may throttle your queries if the number of requests per second deem to be excessively high.