Querying merchant status via the API

AI-generated Key Takeaways

• The Google Maps Booking API offers two methods to retrieve the status of individual merchants for Actions Center and Local Services Ads integrations.

• The MerchantStatus object provides details on merchant inventory status, matching status, matched service provider for Local Services Ads, and Reserve with Google URLs.

• You can get the status of a single merchant using the getStatus method with a specific partner and merchant ID.

• The list method allows you to retrieve the statuses of multiple merchants based on various filtering conditions.

• It is recommended to cache retrieved merchant statuses and update them periodically to avoid excessive requests and potential throttling.

Use cases

Google Maps Booking API provides two methods, which can be used to programmatically retrieve a status of the individual merchants for various Actions Center 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 the Actions Center platform.
• 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 via Reserve with 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.