Local Services Ads End-to-End Querying Merchant Status via the API

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.