Reservations End-to-End Querying Merchant Status via the API

  • The Google Maps Booking API offers methods to programmatically retrieve the status of individual merchants for various integrations or Local Services Ads inventory.

  • Use cases for the Merchant Status API include enhancing CRM tools, building status dashboards, and improving data quality by fixing incorrect information.

  • The merchant status contains inventory status, matching status (including matched business listing details and Local Services Ads information), and URLs to show how the merchant is surfaced on Google.

  • You can look up the status of a single merchant using inventory.partners.merchants.getStatus with a GET request to a specific URL.

  • Merchant statuses can be retrieved in bulk using inventory.partners.merchants.status.list, allowing filtering by inventory or matching conditions.

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.

Previous
Matching Guidelines
Next
Maps URL Merchant Matching