DEV Community: Hello Nakama

Auditing How Your Locations Appear on Google Maps with the Places API

Hello Nakama — Mon, 28 Sep 2026 21:45:17 +0000

To audit what customers actually see on Google Maps, look up each location's Place ID with Places API (New) Place Details, request only the fields you care about with a field mask, and compare phone, website, business status, and hours against your own records. Flag every mismatch for a human to fix in Google Business Profile.

Updated September 2026.

The Business Profile APIs tell you what you submitted and, through getGoogleUpdated, where Google's version differs. The Places API answers a simpler question from the outside: what does the public place record say right now? It is useful when you manage many locations, when some are managed by franchisees or agencies you do not control, or when you want an audit that does not depend on write access.

What is the Places API (New)?

Places API (New) is Google Maps Platform's current web service for place data. For an audit, two methods matter:

Place Details returns one place by ID: GET https://places.googleapis.com/v1/places/PLACE_ID.
Text Search finds places from a text query: POST https://places.googleapis.com/v1/places:searchText.

Both require a field mask. Google's documentation says there is no default list of returned fields, and omitting the mask returns an error. That is a feature. You pay for, and receive, only what you ask for.

How do you get the Place ID for each location?

Two options:

From your Business Profile data. The Business Information API's location metadata includes a placeId. If you have API access, this is the cleanest join.
From Text Search. Search for "Brand name, street, city" and request places.id. Google's Text Search page lists places.id under its ID Only SKU, the lowest tier.

curl -X POST "https://places.googleapis.com/v1/places:searchText" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: $PLACES_API_KEY" \
  -H "X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress" \
  -d '{"textQuery": "Example Hardware, 1200 S Lamar Blvd, Austin, TX"}'

Check the returned name and address by hand before saving the ID. Google's Places API policies say place IDs are exempt from caching restrictions, so you can store them in your location records indefinitely.

Which fields should the audit request?

Only the ones you would act on:

Field	What it catches
`nationalPhoneNumber`	Wrong or old phone numbers, call tracking numbers you did not intend
`websiteUri`	Homepage links instead of location pages, broken redirects, dropped UTM tags
`businessStatus`	A store showing `CLOSED_TEMPORARILY` or `CLOSED_PERMANENTLY` by mistake
`regularOpeningHours`	Hours that differ from your records
`displayName`, `formattedAddress`	Name or address drift, and a quick sanity check on the match

Watch the billing tier. On the Text Search page, Google lists phone numbers, website, and opening hours under a higher SKU than basic fields like address and display name. Place Details uses a similar tiered model. Check current pricing before running this across thousands of locations every day.

How do the hours come back?

regularOpeningHours.periods is a list of open and close points. The Places API reference says day is an integer from 0 to 6 where 0 is Sunday, with separate hour and minute fields. A place open 24 hours can have a period with no close.

There is also currentOpeningHours, which the reference describes as hours for the next seven days, including special hours. Run the audit with that field in the week before a holiday to confirm your holiday exceptions are live.

What does the input file look like?

A CSV exported from your location records:

store_code,place_id,phone,website,status,hours
TX-AUSTIN-014,ChIJ...,+15125550142,https://example.com/locations/texas/austin/south-lamar/,open,mon=08:00-20:00|tue=08:00-20:00|wed=08:00-20:00|thu=08:00-20:00|fri=08:00-20:00|sat=09:00-18:00|sun=closed

What does the audit script look like?

# audit_places.py
# pip install requests
import csv
import os
import re
import sys
from urllib.parse import urlsplit

import requests

API_KEY = os.environ["PLACES_API_KEY"]
FIELDS = ",".join([
    "id", "displayName", "formattedAddress", "nationalPhoneNumber",
    "websiteUri", "businessStatus", "regularOpeningHours",
])
DAY_INDEX = {"sun": 0, "mon": 1, "tue": 2, "wed": 3, "thu": 4, "fri": 5, "sat": 6}
STATUS = {"open": "OPERATIONAL", "temporarily_closed": "CLOSED_TEMPORARILY",
          "permanently_closed": "CLOSED_PERMANENTLY"}


def place_details(place_id: str) -> dict:
    resp = requests.get(
        f"https://places.googleapis.com/v1/places/{place_id}",
        headers={"X-Goog-Api-Key": API_KEY, "X-Goog-FieldMask": FIELDS},
        timeout=20,
    )
    resp.raise_for_status()
    return resp.json()


def digits(phone: str) -> str:
    d = re.sub(r"\D", "", phone or "")
    return d[-10:]  # compare US numbers on the last 10 digits


def clean_url(url: str) -> str:
    parts = urlsplit(url or "")
    return f"{parts.netloc.lower().removeprefix('www.')}{parts.path.rstrip('/')}"


def parse_hours(spec: str) -> set:
    # "mon=08:00-20:00|tue=08:00-20:00|sun=closed"
    out = set()
    for chunk in filter(None, spec.split("|")):
        day, value = chunk.split("=")
        if value == "closed":
            continue
        start, end = value.split("-")
        out.add((DAY_INDEX[day], start, end))
    return out


def google_hours(place: dict) -> set:
    out = set()
    for p in place.get("regularOpeningHours", {}).get("periods", []):
        o, c = p["open"], p.get("close")
        if c is None:  # open 24 hours
            out.add((o["day"], "00:00", "24:00"))
            continue
        out.add((o["day"], f"{o['hour']:02d}:{o['minute']:02d}", f"{c['hour']:02d}:{c['minute']:02d}"))
    return out


def audit_row(row: dict, place: dict) -> list[str]:
    issues = []
    if digits(place.get("nationalPhoneNumber")) != digits(row["phone"]):
        issues.append(f"phone: google={place.get('nationalPhoneNumber')} ours={row['phone']}")
    if clean_url(place.get("websiteUri")) != clean_url(row["website"]):
        issues.append(f"website: google={place.get('websiteUri')} ours={row['website']}")
    expected_status = STATUS.get(row["status"])
    if expected_status and place.get("businessStatus") != expected_status:
        issues.append(f"status: google={place.get('businessStatus')} ours={row['status']}")
    ours, theirs = parse_hours(row["hours"]), google_hours(place)
    if ours != theirs:
        missing = sorted(ours - theirs)
        extra = sorted(theirs - ours)
        issues.append(f"hours: missing_on_google={missing} unexpected_on_google={extra}")
    return issues


def main(path: str) -> int:
    failures = 0
    with open(path, newline="") as f:
        for row in csv.DictReader(f):
            try:
                place = place_details(row["place_id"])
            except requests.HTTPError as exc:
                print(f"{row['store_code']}: lookup failed ({exc.response.status_code})")
                failures += 1
                continue
            issues = audit_row(row, place)
            if issues:
                failures += 1
                print(f"{row['store_code']} ({place.get('displayName', {}).get('text')}):")
                for issue in issues:
                    print(f"  - {issue}")
            else:
                print(f"{row['store_code']}: ok")
    return 1 if failures else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

Sample output:

TX-AUSTIN-014 (Example Hardware):
  - hours: missing_on_google=[(6, '09:00', '18:00')] unexpected_on_google=[(6, '09:00', '17:00')]
TX-AUSTIN-022: ok

A few deliberate simplifications. Phones compare on the last 10 digits, which suits US numbers. URLs compare host and path and ignore query strings, so UTM tags do not cause false alarms. Overnight hours compare on the opening day only. Tighten any of these for your data.

What should you do with the results?

Treat the output as a work queue, not a dataset. Google's Places API policies say you must not pre-fetch, cache, or store Places content beyond the allowed exceptions, so keep the report short-lived and act on it rather than building a stored copy of Google's data. Review the Google Maps Platform terms for your own use case.

For each flagged location:

Confirm your own record is right. Sometimes the store changed and nobody told HQ.
Fix the listing in Google Business Profile, directly or through your listing tool.
If Google keeps reverting a field, check getGoogleUpdated for that location and accept or reject the update there.
Rerun the audit for that store after the edit is reviewed.

How often should you run it?

Weekly for most brands, daily in the two weeks before major US holidays, and immediately after any bulk change such as a phone system migration or a rebrand.

Run it in CI or a scheduled job and send failures to a channel someone actually watches. An audit nobody reads is just a bill.

Does this replace a listing platform?

No. It checks one platform from the outside. Listing platforms handle publishing to many platforms and usually include their own sync status. Synup, for example, reports per-location sync issues across its publishers. A script like this is a useful second opinion on Google specifically, because it reads the public place record directly instead of trusting any tool's internal status.

FAQ

Do I need Business Profile API access to run this?

No. The Places API uses a standard Google Maps Platform API key. You need Business Profile access only to fix what you find through the API.

Can I store the Places responses for trend reports?

Google's policies restrict caching and storing Places content, with place IDs as the main exception. Store your own pass or fail results and check the terms for anything more.

Why do my hours match in Business Profile but not in the Places API?

Edits can still be in review, or Google may be serving an update from another source. Check getGoogleUpdated for the location.

Does this work for service-area businesses?

Partly. Google's Text Search docs say pure service-area businesses do not include a formattedAddress, so compare phone, website, and hours instead.

Designing a Location Data Model That Works as a Single Source of Truth

Hello Nakama — Mon, 28 Sep 2026 21:38:13 +0000

A location single source of truth is one internal record per location, with a strict schema, that every output is generated from: Google Business Profile, other listings, store pages, and structured data. Define it with JSON Schema, validate every change against it plus a few business rules, and write mappers that translate it into each platform's format.

Updated September 2026.

Most multi-location data problems are not API problems. They are "which spreadsheet is right" problems. The website team has one set of hours, the listings team has another, and the store manager changed a third directly in Google. This post shows a data model that makes one record authoritative, with working code for validation and mapping.

What should a location record contain?

Only the facts you publish, plus the IDs that connect the record to each platform. A practical minimum:

Field group	Examples	Why it exists
Identity	internal `id`, `store_code`, `name`	Stable keys that never change when the store name does
Status	`open`, `temporarily_closed`, `permanently_closed`, `coming_soon`	Drives what every output shows
Address and phone	US address parts, E.164 phone	The fields that must match everywhere
Hours	regular periods and dated special hours	The most frequently wrong field on any listing
Categories	Google category ID	Brand-level decision, stored once
External IDs	Google location name, Place ID	Joins your record to each platform

Keep an internal id separate from the store code. Store codes get reused after closures and renumbered after acquisitions. Your primary key should outlive both.

How do you define the schema?

Use JSON Schema draft 2020-12. It is language-neutral, so the same file can validate records in a Python pipeline, a Node admin tool, and a CI check.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/location.json",
  "type": "object",
  "required": ["id", "store_code", "name", "status", "address", "phone", "timezone", "hours"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string", "pattern": "^loc_[a-z0-9]+$" },
    "store_code": { "type": "string", "minLength": 1 },
    "name": { "type": "string", "minLength": 1 },
    "status": { "enum": ["open", "temporarily_closed", "permanently_closed", "coming_soon"] },
    "address": {
      "type": "object",
      "required": ["lines", "city", "state", "postal_code", "country"],
      "additionalProperties": false,
      "properties": {
        "lines": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 2 },
        "city": { "type": "string" },
        "state": { "type": "string", "pattern": "^[A-Z]{2}$" },
        "postal_code": { "type": "string", "pattern": "^[0-9]{5}(-[0-9]{4})?$" },
        "country": { "const": "US" }
      }
    },
    "phone": { "type": "string", "pattern": "^\\+1[0-9]{10}$" },
    "website_url": { "type": "string", "format": "uri" },
    "timezone": { "type": "string", "examples": ["America/Chicago"] },
    "categories": {
      "type": "object",
      "properties": {
        "google_primary": { "type": "string", "pattern": "^gcid:[a-z0-9_]+$" }
      }
    },
    "hours": {
      "type": "object",
      "required": ["regular"],
      "properties": {
        "regular": { "type": "array", "items": { "$ref": "#/$defs/period" } },
        "special": { "type": "array", "items": { "$ref": "#/$defs/special" } }
      }
    },
    "external_ids": {
      "type": "object",
      "properties": {
        "google_location": { "type": "string", "pattern": "^locations/[0-9]+$" },
        "google_place_id": { "type": "string" }
      }
    },
    "updated_at": { "type": "string", "format": "date-time" }
  },
  "$defs": {
    "time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" },
    "period": {
      "type": "object",
      "required": ["day", "open", "close"],
      "additionalProperties": false,
      "properties": {
        "day": { "enum": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"] },
        "open": { "$ref": "#/$defs/time" },
        "close": { "$ref": "#/$defs/time" }
      }
    },
    "special": {
      "type": "object",
      "required": ["date", "closed"],
      "additionalProperties": false,
      "properties": {
        "date": { "type": "string", "format": "date" },
        "closed": { "type": "boolean" },
        "open": { "$ref": "#/$defs/time" },
        "close": { "$ref": "#/$defs/time" }
      },
      "if": { "properties": { "closed": { "const": false } } },
      "then": { "required": ["open", "close"] }
    }
  }
}

A few choices worth explaining:

Phone as E.164. +15125550142 is unambiguous. Format it for display at the edge, not in storage.
Times as HH:MM strings. Easy to read and diff. The mappers convert them to each platform's format.
Special hours require open and close when closed is false. The if/then block enforces that.
additionalProperties: false. Typos like postal_cod fail loudly instead of being ignored.

The Google category pattern follows the gcid:... form that Google uses in the category examples in its location data guide, such as gcid:software_company.

What does a valid record look like?

{
  "id": "loc_014",
  "store_code": "TX-AUSTIN-014",
  "name": "Example Hardware",
  "status": "open",
  "address": {
    "lines": ["1200 S Lamar Blvd"],
    "city": "Austin",
    "state": "TX",
    "postal_code": "78704",
    "country": "US"
  },
  "phone": "+15125550142",
  "website_url": "https://example.com/locations/texas/austin/south-lamar/",
  "timezone": "America/Chicago",
  "hours": {
    "regular": [
      { "day": "MONDAY", "open": "08:00", "close": "20:00" },
      { "day": "FRIDAY", "open": "08:00", "close": "20:00" },
      { "day": "SATURDAY", "open": "09:00", "close": "18:00" }
    ],
    "special": [
      { "date": "2026-11-26", "closed": true },
      { "date": "2026-12-24", "closed": false, "open": "08:00", "close": "15:00" }
    ]
  },
  "external_ids": { "google_location": "locations/1234567890123456789" },
  "updated_at": "2026-09-20T14:05:00Z"
}

Short, boring, and reviewable in a pull request. That is the point.

How do you validate beyond the schema?

JSON Schema checks shape. It cannot easily check that two periods on Monday overlap or that last year's holiday is still in the file. Add a small rules layer.

# validate.py
# pip install jsonschema
import json
import sys
from datetime import date

from jsonschema import Draft202012Validator, FormatChecker

schema = json.load(open("location.schema.json"))
Draft202012Validator.check_schema(schema)
validator = Draft202012Validator(schema, format_checker=FormatChecker())


def business_rules(loc: dict) -> list[str]:
    errors = []
    by_day = {}
    for p in loc["hours"]["regular"]:
        by_day.setdefault(p["day"], []).append(p)
    for day, periods in by_day.items():
        periods.sort(key=lambda p: p["open"])
        for prev, nxt in zip(periods, periods[1:]):
            if prev["close"] > prev["open"] and nxt["open"] < prev["close"]:
                errors.append(f"{day}: overlapping periods {prev['open']} and {nxt['open']}")
    for p in loc["hours"]["regular"]:
        if p["open"] == p["close"]:
            errors.append(f"{p['day']}: open equals close, use a 24-hour flag instead")
    seen = set()
    for s in loc["hours"].get("special", []):
        if s["date"] in seen:
            errors.append(f"{s['date']}: duplicate special-hours date")
        seen.add(s["date"])
        if date.fromisoformat(s["date"]) < date.today():
            errors.append(f"{s['date']}: special hours in the past, prune them")
    if loc["status"] == "permanently_closed" and loc["hours"]["regular"]:
        errors.append("closed location still has regular hours")
    return errors


def main(path: str) -> int:
    loc = json.load(open(path))
    problems = [f"schema: {e.json_path}: {e.message}" for e in validator.iter_errors(loc)]
    if not problems:
        problems = [f"rule: {m}" for m in business_rules(loc)]
    for p in problems:
        print(p)
    return 1 if problems else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1]))

Run it in CI on every change to the location files, and in the admin tool before a save. A failing check blocks the change instead of publishing it. Note that the jsonschema library only enforces some formats, like uri, when optional extra packages are installed. Check the library's format documentation for the formats you rely on.

How do you map one record to many outputs?

Write one small function per destination. Here are two: a Business Information API Location body and a schema.org LocalBusiness block.

# mappers.py
DAYS = ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"]


def _tod(hhmm: str) -> dict:
    h, m = (int(x) for x in hhmm.split(":"))
    return {"hours": h, "minutes": m}


def _next_day(day: str) -> str:
    return DAYS[(DAYS.index(day) + 1) % 7]


def _date(iso: str) -> dict:
    y, m, d = (int(x) for x in iso.split("-"))
    return {"year": y, "month": m, "day": d}


def to_gbp(loc: dict) -> dict:
    """Map an internal record to a Business Information API Location body."""
    periods = []
    for p in loc["hours"]["regular"]:
        overnight = p["close"] <= p["open"]
        periods.append({
            "openDay": p["day"],
            "openTime": _tod(p["open"]),
            "closeDay": _next_day(p["day"]) if overnight else p["day"],
            "closeTime": _tod(p["close"]),
        })
    special = []
    for s in loc["hours"].get("special", []):
        item = {"startDate": _date(s["date"]), "closed": s["closed"]}
        if not s["closed"]:
            item["openTime"] = _tod(s["open"])
            item["closeTime"] = _tod(s["close"])
        special.append(item)
    a = loc["address"]
    body = {
        "storeCode": loc["store_code"],
        "title": loc["name"],
        "phoneNumbers": {"primaryPhone": loc["phone"]},
        "storefrontAddress": {
            "regionCode": a["country"],
            "administrativeArea": a["state"],
            "locality": a["city"],
            "postalCode": a["postal_code"],
            "addressLines": a["lines"],
        },
        "regularHours": {"periods": periods},
        "specialHours": {"specialHourPeriods": special},
    }
    if "website_url" in loc:
        body["websiteUri"] = loc["website_url"]
    return body


def to_jsonld(loc: dict, page_url: str) -> dict:
    """Map the same record to schema.org LocalBusiness JSON-LD."""
    spec = [
        {"@type": "OpeningHoursSpecification", "dayOfWeek": p["day"].title(),
         "opens": p["open"], "closes": p["close"]}
        for p in loc["hours"]["regular"]
    ]
    for s in loc["hours"].get("special", []):
        spec.append({
            "@type": "OpeningHoursSpecification",
            "opens": "00:00" if s["closed"] else s["open"],
            "closes": "00:00" if s["closed"] else s["close"],
            "validFrom": s["date"],
            "validThrough": s["date"],
        })
    a = loc["address"]
    return {
        "@context": "https://schema.org",
        "@type": "LocalBusiness",
        "@id": f"{page_url}#location",
        "name": loc["name"],
        "url": page_url,
        "telephone": loc["phone"],
        "address": {
            "@type": "PostalAddress",
            "streetAddress": ", ".join(a["lines"]),
            "addressLocality": a["city"],
            "addressRegion": a["state"],
            "postalCode": a["postal_code"],
            "addressCountry": a["country"],
        },
        "openingHoursSpecification": spec,
    }

The Google mapper follows the Business Information API Location reference: regularHours.periods with openDay, openTime, closeDay, and closeTime, and specialHours.specialHourPeriods with a startDate and either times or closed: true. Overnight regular hours set closeDay to the next day.

The JSON-LD mapper follows Google's LocalBusiness structured data guide, which says to mark a business closed all day by setting both opens and closes to "00:00", and to use validFrom and validThrough for date-limited hours.

This version does not handle overnight special hours. Google's special hours rules require splitting a period that runs past midnight into two sets, so add that before you rely on it for late-night locations.

How do you push changes safely?

Send only what changed. The Business Information API's locations.patch takes an updateMask, so compute a field-level diff between the last published version and the new record, and patch only those fields. It also accepts validateOnly=true, which is useful because Google offers no sandbox.

A simple flow:

A change lands in the location record through a pull request or admin tool.
Schema and rule validation run.
A diff job builds the update mask for each destination.
Writes go out, with validateOnly first for risky fields.
A read-back job compares what each platform now serves against the record.

Who should be allowed to edit which fields?

Put ownership in the model, not in people's heads. A common split for brands:

Brand team: name, categories, website URL pattern, standard services.
Location or franchisee: special hours, local phone, accessibility details, photos.
Nobody directly on the platform: anything the pipeline publishes, or the next sync overwrites it.

Enforce it with per-field permissions in your admin tool, and with CODEOWNERS rules if the records live in Git.

Should you build this or use a platform?

Build it if you have engineering capacity and many custom outputs. Use a listing platform if the main outputs are listings and pages. Many platforms already keep a location record like this one. Synup, for example, stores one record per location and publishes it to its publisher network, and it offers an API. In that setup, treat the platform record as the source of truth and use a schema like this to validate what you send into it or pull out of it.

FAQ

Why JSON Schema instead of a database schema?

Use both if you have a database. JSON Schema gives you one portable contract that CI, admin tools, and import scripts can all enforce.

Should hours be stored in local time or UTC?

Local time with an IANA timezone per location. Listings and store pages display local hours, and daylight saving changes make UTC storage error-prone.

Where should the Google Place ID live?

In external_ids. Google's Places API policies say place IDs are exempt from caching restrictions, so you can store them indefinitely.

How do I handle a store that is closing?

Change status, keep the record, and let each mapper decide what to publish. Deleting the record loses history and external IDs.

Monitoring Google's Edits to Your Business Profiles with Pub/Sub Notifications

Hello Nakama — Mon, 28 Sep 2026 21:31:17 +0000

To monitor Google's changes to your Business Profiles, subscribe your account to GOOGLE_UPDATE notifications through the My Business Notifications API and Cloud Pub/Sub. When one arrives, call locations.getGoogleUpdated to see which fields changed in the diffMask, compare them with your source of truth, then accept or reject each change with locations.patch.

Updated September 2026.

Google does not only show what you submit. Its developer guide on managing Google updates says Google uses sources like user reports and licensed content, and notifies listing owners when their information is reported as incorrect. If nobody is watching, a wrong phone number suggested by a stranger can sit on a profile for weeks.

This post builds a small monitoring loop using only documented Google features.

What notifications can the Business Profile APIs send?

The NotificationSetting reference lists the types. The ones useful for monitoring listing data are:

Type	What it means
`GOOGLE_UPDATE`	The location has Google updates for review
`DUPLICATE_LOCATION`	The duplicate location field in location metadata changed
`VOICE_OF_MERCHANT_UPDATED`	The location's Voice of Merchant status changed
`NEW_CUSTOMER_MEDIA`	A Google Maps user added a photo or video
`NEW_REVIEW`, `UPDATED_REVIEW`	Review activity

Skip the question and answer types. The reference marks NEW_QUESTION, UPDATED_QUESTION, NEW_ANSWER, and UPDATED_ANSWER as deprecated, because Google discontinued the Q&A API on November 3, 2025.

VOICE_OF_MERCHANT_UPDATED is worth including. The reference describes Voice of Merchant as whether the location is in good standing and the merchant has control over the business on Google. Losing it is often the first sign of a verification or suspension problem.

How do you set up the Pub/Sub topic?

Google's real-time notifications guide lists the steps: create a topic, give mybusiness-api-pubsub@system.gserviceaccount.com at least publish permission, create a subscription, then link your Business Profile account to the topic.

PROJECT=my-gcp-project
gcloud config set project "$PROJECT"

gcloud pubsub topics create gbp-notifications

gcloud pubsub topics add-iam-policy-binding gbp-notifications \
  --member="serviceAccount:mybusiness-api-pubsub@system.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

gcloud pubsub subscriptions create gbp-notifications-worker \
  --topic=gbp-notifications

How do you link the Business Profile account?

Call accounts.updateNotificationSetting. There is one notification setting per account, and one topic per setting. If you manage several accounts, repeat this for each.

# link_notifications.py
# pip install google-auth requests
from google.auth.transport.requests import AuthorizedSession
from google.oauth2.credentials import Credentials

SCOPES = ["https://www.googleapis.com/auth/business.manage"]
ACCOUNT = "accounts/1234567890"
TOPIC = "projects/my-gcp-project/topics/gbp-notifications"

session = AuthorizedSession(Credentials.from_authorized_user_file("token.json", SCOPES))

resp = session.patch(
    f"https://mybusinessnotifications.googleapis.com/v1/{ACCOUNT}/notificationSetting",
    params={"updateMask": "pubsubTopic,notificationTypes"},
    json={
        "name": f"{ACCOUNT}/notificationSetting",
        "pubsubTopic": TOPIC,
        "notificationTypes": [
            "GOOGLE_UPDATE",
            "DUPLICATE_LOCATION",
            "VOICE_OF_MERCHANT_UPDATED",
        ],
    },
)
resp.raise_for_status()
print(resp.json())

To stop notifications later, the reference says to send an empty notificationTypes list or an empty pubsubTopic.

What does a notification contain?

Very little, by design. It tells you the type and which location, not the new value. Google's guide says the locationName field on a GOOGLE_UPDATE notification provides the resource name of the location. Log the raw payload during your first test so you can confirm the exact field names your subscription receives, and normalize the location name to the locations/{id} form the Business Information API expects.

How do you see what Google changed?

Call locations.getGoogleUpdated with a readMask. The response has three parts:

location: the Google-updated version of the location.
diffMask: the fields where what customers see differs from your preferred values.
pendingMask: fields where your own edit is still processing.

Google's guide says you must accept or reject the fields in diffMask, and you do not need to act on pendingMask.

What does the worker look like?

This worker pulls messages, fetches the Google-updated location, compares the changed fields with your own records, and writes a review item. It does not change anything on its own.

# worker.py
# pip install google-cloud-pubsub google-auth requests
import json

from google.auth.transport.requests import AuthorizedSession
from google.cloud import pubsub_v1
from google.oauth2.credentials import Credentials

SCOPES = ["https://www.googleapis.com/auth/business.manage"]
BIZ = "https://mybusinessbusinessinformation.googleapis.com/v1"
READ_MASK = "name,title,phoneNumbers,storefrontAddress,websiteUri,regularHours,categories"
WATCHED = ("title", "phoneNumbers", "storefrontAddress", "websiteUri", "regularHours", "categories")

session = AuthorizedSession(Credentials.from_authorized_user_file("token.json", SCOPES))


def normalize(name: str) -> str:
    # accept "accounts/1/locations/2" or "locations/2"
    return name[name.index("locations/"):]


def source_of_truth(location_name: str) -> dict:
    # Replace with a lookup in your own location database.
    return {}


def handle(payload: dict) -> None:
    raw = payload.get("locationName") or payload.get("location")
    if not raw:
        print("unrecognized payload", payload)
        return
    loc = normalize(raw)
    resp = session.get(f"{BIZ}/{loc}:getGoogleUpdated", params={"readMask": READ_MASK})
    resp.raise_for_status()
    body = resp.json()
    changed = [f for f in body.get("diffMask", "").split(",") if f]
    watched = [f for f in changed if f.startswith(WATCHED)]
    if not watched:
        return
    ours = source_of_truth(loc)
    review_item = {
        "location": loc,
        "fields": watched,
        "google_value": {f.split(".")[0]: body["location"].get(f.split(".")[0]) for f in watched},
        "our_value": {f.split(".")[0]: ours.get(f.split(".")[0]) for f in watched},
        "pending": body.get("pendingMask", ""),
    }
    print(json.dumps(review_item, indent=2))  # send to your ticket queue instead


def callback(message) -> None:
    try:
        payload = json.loads(message.data.decode("utf-8"))
        if payload.get("type", "GOOGLE_UPDATE") == "GOOGLE_UPDATE":
            handle(payload)
        else:
            print("other notification", payload)
        message.ack()
    except Exception as exc:
        print("failed, will retry:", exc)
        message.nack()


subscriber = pubsub_v1.SubscriberClient()
path = subscriber.subscription_path("my-gcp-project", "gbp-notifications-worker")
future = subscriber.subscribe(path, callback=callback)
print("listening on", path)
future.result()

Two design notes. The nack on failure lets Pub/Sub redeliver, so a temporary API error does not lose an event. And the worker only reports. Deciding is a human job.

How do you accept or reject a change?

Both use locations.patch with an updateMask covering the fields you are resolving. Google's guide is explicit:

Accept: patch the location with the new value from getGoogleUpdated.
Reject: patch the location with your original preferred value.

def resolve(loc: str, field: str, value) -> dict:
    resp = session.patch(f"{BIZ}/{loc}", params={"updateMask": field}, json={field: value})
    resp.raise_for_status()
    return resp.json()

Afterward, call getGoogleUpdated again. Google's guide says a successful patch shows "diffMask": "" and the hasGoogleUpdated flag in metadata as false or absent, and it recommends building logic to verify both.

What if you cannot use notifications?

Poll instead. Google's guide notes that locations.get returns a metadata.hasGoogleUpdated flag. A nightly job that checks the flag for every location, then calls getGoogleUpdated only where it is true, is slower but simple.

Where does this fit with a listing platform?

If a listing platform is your source of truth, keep the platform in charge of writes and use this loop as a separate check on what Google is actually serving. Synup, for example, holds location records and flags per-location sync issues, and your worker's source_of_truth function can read from that record instead of a spreadsheet. Make sure only one system writes each field, or the two will fight.

FAQ

Does a GOOGLE_UPDATE notification include the new value?

No. It identifies the location. Call getGoogleUpdated to see the Google-updated values and the diffMask.

Should I auto-reject every Google update?

No. Some updates are correct, such as a fixed pin or a real hours change a manager forgot to report. Route them to a person.

How many topics can one account use?

One. The reference says each account has one notification setting and one Pub/Sub topic.

Can I monitor Q&A this way?

No. The Q&A notification types are deprecated because the Q&A API was discontinued on November 3, 2025.

Tracking Google Business Profile Clicks in GA4 with UTM Parameters

Hello Nakama — Mon, 28 Sep 2026 21:24:29 +0000

To track Google Business Profile clicks in GA4, add UTM parameters to each location's website URL, using utm_source=google, utm_medium=organic, and a campaign name such as gbp_listing. GA4 keeps that traffic in Organic Search while letting you isolate it by campaign. For many locations, update the websiteUri field through the Business Profile API.

Updated September 2026.

Without tagging, a click from a Business Profile usually lands in GA4 as ordinary google / organic, mixed in with every other organic visit. This post covers a naming scheme that behaves well in GA4's default channel rules, a Python script that tags every location with a dry run first, and a way to compare GA4 sessions with the click counts Google reports.

Why do GBP clicks disappear into organic traffic?

Because the referrer is Google, and GA4 treats Google as a search source. Nothing in the default setup tells you whether the visit came from a blue link, an AI Overview, or the website button on a Business Profile.

UTM parameters solve that. Google Analytics Help describes them in its guide to collecting campaign data with custom URLs, and recommends always setting utm_source, utm_medium, and utm_campaign together.

Which UTM values should you use?

Pick values that still match GA4's Organic Search rule. GA4's default channel group puts a session in Organic Search when the source matches its list of search sites, or when the medium exactly matches organic.

If you invent a medium like gbp or local, and the source does not match GA4's list of search sites, the traffic can land in Unassigned unless you build a custom channel group. So keep the medium boring:

Parameter	Value	Why
`utm_source`	`google`	Keeps the source consistent with other Google traffic
`utm_medium`	`organic`	Matches the Organic Search channel rule exactly
`utm_campaign`	`gbp_listing`	The field you filter on to isolate profile clicks
`utm_content`	store code, for example `tx-austin-014`	Splits results by location

GA4 treats values as case sensitive, and its help page recommends lowercase. Google and google become two rows.

A tagged URL looks like this:

https://example.com/locations/austin-south-lamar/?utm_source=google&utm_medium=organic&utm_campaign=gbp_listing&utm_content=tx-austin-014

Point each profile at its own location page, not the homepage. The Business Information API reference says websiteUri should, if possible, represent the individual location rather than the brand.

How do you tag hundreds of locations at once?

Use the Business Information API. It exposes locations.list for reading and locations.patch for writing, with an updateMask so you touch only websiteUri. Access requires an approved Google Cloud project, and Google's basic setup guide notes there is no sandbox. Use the validateOnly flag to test.

The script below:

Lists locations for an account, reading only name, title, storeCode, and websiteUri.
Builds a tagged URL while preserving any existing query parameters.
Skips locations that are already tagged correctly.
Sends each patch with validateOnly=true unless you pass --apply.

# tag_gbp_urls.py
# pip install google-auth requests
import argparse
from urllib.parse import urlsplit, urlunsplit, parse_qsl, urlencode

from google.auth.transport.requests import AuthorizedSession
from google.oauth2.credentials import Credentials

SCOPES = ["https://www.googleapis.com/auth/business.manage"]
BASE = "https://mybusinessbusinessinformation.googleapis.com/v1"

UTM = {"utm_source": "google", "utm_medium": "organic", "utm_campaign": "gbp_listing"}


def tagged(url: str, store_code: str) -> str:
    parts = urlsplit(url)
    query = dict(parse_qsl(parts.query, keep_blank_values=True))
    query.update(UTM)
    if store_code:
        query["utm_content"] = store_code.lower()
    return urlunsplit(parts._replace(query=urlencode(query)))


def list_locations(session, account):
    params = {"readMask": "name,title,storeCode,websiteUri", "pageSize": 100}
    while True:
        resp = session.get(f"{BASE}/{account}/locations", params=params)
        resp.raise_for_status()
        data = resp.json()
        yield from data.get("locations", [])
        token = data.get("nextPageToken")
        if not token:
            break
        params["pageToken"] = token


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("account", help="accounts/1234567890")
    parser.add_argument("--apply", action="store_true", help="write changes")
    args = parser.parse_args()

    creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    session = AuthorizedSession(creds)

    for loc in list_locations(session, args.account):
        current = loc.get("websiteUri")
        if not current:
            print(f"SKIP  {loc['title']}: no website set")
            continue
        new = tagged(current, loc.get("storeCode", ""))
        if new == current:
            print(f"OK    {loc['title']}")
            continue
        params = {"updateMask": "websiteUri"}
        if not args.apply:
            params["validateOnly"] = "true"
        resp = session.patch(f"{BASE}/{loc['name']}", params=params, json={"websiteUri": new})
        status = "APPLY" if args.apply else "CHECK"
        print(f"{status} {loc['title']}: {resp.status_code} {new}")


if __name__ == "__main__":
    main()

Run it without --apply first and read every line of output. Then run it on a small group of locations before the full account.

Should you worry about tagged URLs on a profile?

Google's Business Profile guidelines prohibit URLs that redirect or refer users to landing pages other than the actual business. A UTM parameter does not redirect anywhere. It is a query string on your own URL.

Two practical cautions:

Make sure your site does not strip or redirect query strings in a way that drops the tags.
If you use canonical tags, point them at the clean URL so the tagged version does not compete in search.

How do you find the traffic in GA4?

Open Reports, then Acquisition, then Traffic acquisition. Google's help page says campaign values show up in dimensions like Session source/medium and Session campaign.

For a location view, build an exploration:

Add the dimension Session campaign and filter it to gbp_listing.
Add the dimension Session manual ad content, which holds your utm_content store codes.
Add metrics such as Sessions and Key events.

That gives you sessions and conversions per location from profile clicks alone.

How do you check the numbers against Google's own counts?

The Business Profile Performance API reports website clicks per location per day through locations.fetchMultiDailyMetricsTimeSeries. It is a good sanity check.

PERF = "https://businessprofileperformance.googleapis.com/v1"

def website_clicks(session, location_name, start, end):
    params = {
        "dailyMetrics": "WEBSITE_CLICKS",
        "dailyRange.start_date.year": start.year,
        "dailyRange.start_date.month": start.month,
        "dailyRange.start_date.day": start.day,
        "dailyRange.end_date.year": end.year,
        "dailyRange.end_date.month": end.month,
        "dailyRange.end_date.day": end.day,
    }
    resp = session.get(f"{PERF}/{location_name}:fetchMultiDailyMetricsTimeSeries", params=params)
    resp.raise_for_status()
    total = 0
    for multi in resp.json().get("multiDailyMetricTimeSeries", []):
        for series in multi.get("dailyMetricTimeSeries", []):
            for point in series.get("timeSeries", {}).get("datedValues", []):
                total += int(point.get("value", 0))  # value is omitted when zero
    return total

Here location_name is the locations/{id} value from the listing call. Expect clicks and sessions to differ. A click is not a session, consent settings and ad blockers remove some sessions, and one person can click twice. Watch the ratio over time per location. A sudden drop in the ratio at one location often means the website link was changed or the tags were removed.

What breaks this setup?

Someone edits the link by hand. A manager pastes a clean URL into the profile and the tags vanish. Rerun the script monthly as an audit.
Listing tools overwrite the field. If a listing platform manages your website URL, set the tagged URL there instead, or the next sync undoes your work. Synup and similar platforms hold the website field in their location record, so that record becomes the place to store the tagged version.
Mixed case values. GBP_Listing and gbp_listing split into two rows.

FAQ

Will UTM tags hurt my local rankings?

There is no Google documentation saying they do. The tags do not change the destination page. Use a canonical tag on the location page to keep search signals on the clean URL.

Why not use `utm_medium=gbp`?

GA4's default Organic Search rule looks for a search source or a medium of exactly organic. A custom medium can push traffic into Unassigned unless you create a custom channel group.

Can I tag appointment or menu links too?

Yes, the same scheme works for any URL you control. Use a different utm_content or campaign value so you can tell the links apart.

How often should I audit the tags?

Monthly is reasonable. Run the script in dry-run mode and look for locations reported as changed.

Guardrails for Letting an AI Agent Edit Your Business Listings

Hello Nakama — Sun, 27 Sep 2026 20:43:48 +0000

An AI agent can safely manage business listings only if it cannot change live data on its own. Give it read tools freely, make every write produce a diff first, send that diff to a human approval queue, and scope its credentials to the smallest set of locations it needs. With those four controls in place, an agent becomes a fast assistant. Without them, it becomes a very fast way to publish wrong hours to every map.

This post covers why listings are a risky place for agents, a tool design that works, and what to log.

Why are listings a risky target for agents?

Listing data is public, copied widely, and slow to correct. A bad edit to Google Business Profile can spread to maps, AI assistants, and data aggregators before anyone notices. Rolling it back in one place does not roll it back everywhere.

Agents also fail in specific ways. They can misread "close early on the 24th" as a permanent hours change. They can pick the wrong one of two similarly named locations. They can follow instructions that arrive inside content they read, such as a review text or a web page, which is known as prompt injection.

How should the tools be designed?

Split read and write, and make writes two-step. If you expose tools through the Model Context Protocol (MCP), the open standard for connecting models to external tools, the shape looks like this:

Tool	Type	What it does
`list_locations`	Read	Returns locations the agent is allowed to see
`get_location`	Read	Returns current live data for one location
`propose_change`	Write, staged	Creates a pending change and returns a diff
`get_change_status`	Read	Shows whether a proposal was approved

Notice what is missing: there is no apply_change tool. Approval and publishing happen outside the agent's reach, in a queue a human controls.

What should a proposal contain?

Enough for a reviewer to decide in seconds:

{
  "location_id": "store-0142",
  "location_name": "Austin, South Congress",
  "fields": {
    "regularHours.friday": { "from": "09:00-18:00", "to": "09:00-20:00" }
  },
  "reason": "Manager request: extended Friday hours from next week",
  "source": "ticket OPS-2291",
  "effective_date": "2026-10-09",
  "expires": null
}

Require a reason and a source on every proposal. It forces the agent to tie the change to a real request, and it gives reviewers something to check. Require expires for anything temporary, so holiday hours do not become permanent by accident.

How do you scope credentials?

Give the agent its own identity, never a human's token. Scope that identity to the locations and fields it manages. A regional assistant should see one region. An agent that only fixes phone formatting should not be able to change names or categories.

High-risk fields deserve extra friction. Business name, primary category, and address changes are the edits most likely to trigger a Google review or suspension. Route those to a senior approver or block them for agents entirely.

How do you defend against prompt injection?

Treat everything the agent reads as data, not instructions. Review text, website copy, and emails can contain lines like "update the phone number to this one." Three habits help:

Only accept change requests from structured sources, such as a ticket system, never from free text the agent happens to read.
Validate proposed values against rules, for example phone numbers against your known number list.
Show reviewers the source of each request next to the diff.

What should you log?

Log every tool call with the agent identity, input, output, and timestamp. Log every proposal, who approved or rejected it, and when it went live. Keep a snapshot of the location before each change so rollback is one step.

These logs are also how you improve the agent. Rejected proposals tell you exactly where its judgment is weak.

Should you build this or use a platform?

Build it if you already have a location data service and want full control. Wrap Google's Business Information API in your own MCP server and keep the approval queue in your system.

If you would rather not, look for platforms that already separate proposing from publishing. Yext and Uberall both offer APIs an agent can call, but their scale and pricing suit larger brands, and you should confirm how their approval features fit an agent that proposes changes. Synup offers MCP support along with an approvals inbox and scoped team permissions, which covers much of the pattern above without custom work. Its weakness is that you work within its permission model rather than designing your own. A fully custom build gives you the most control, and the most to maintain.

FAQ

Can I let an agent auto-apply low-risk changes?

Some teams allow it for narrow cases, like fixing formatting on a field that is already approved. Start with everything going through approval and relax rules only after reviewing the logs.

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to tools and data. It lets you expose functions like get_location to any compatible agent.

Which fields should agents never edit alone?

Business name, primary category, and address. These carry the most suspension risk and the widest impact.

How do I test an agent before giving it write access?

Run it read-only for a period, have it write proposals to a log only, and compare them against what your team actually changed.

Store Locators That Crawlers Can Actually Read

Hello Nakama — Sun, 27 Sep 2026 20:35:19 +0000

If your store locator only renders locations after JavaScript runs, many crawlers will see an empty page. The fix is architectural: give every location its own server-rendered URL, link to all of them from plain HTML, and treat the interactive map as an enhancement on top. The widget is for humans. The static pages are for everything else.

This post covers the failure mode, a URL structure that works, and how to generate the pages without hand-maintaining hundreds of files.

What is wrong with a typical locator?

A common locator is one route, /locations, that loads an empty shell, calls an API, and draws pins and a list client-side. The search box filters in the browser. There are no individual location URLs, or they exist only as hash fragments.

For a person with a modern browser, it works. For a crawler, the page is a script tag and a spinner.

Do crawlers really not run JavaScript?

Some do, some do not, and the ones that do are slower about it. Googlebot renders JavaScript, but rendering can happen later than the initial crawl. Vercel published an analysis in late 2024 of AI crawler traffic across its network and found that the major AI crawlers it measured, including OpenAI's and Anthropic's, fetched JavaScript files but did not execute them.

So if you want ChatGPT, Claude, or Perplexity to know your store hours, those hours need to be in the HTML response.

What URL structure works best?

One indexable URL per location, organized in a shallow hierarchy:

/locations/                          all regions
/locations/texas/                    state or region
/locations/texas/austin/             city, lists stores
/locations/texas/austin/south-congress/   one store

Each store page should include, in server-rendered HTML:

Business name, full address, and phone number.
Hours, including a visible note for holiday hours.
Services or departments specific to that store.
A static map image or link, not only an embedded interactive map.
LocalBusiness JSON-LD that matches the visible content.

The region and city pages are crawl paths, so link to every child with a normal <a href>. Do not rely on a sitemap alone.

How do you generate the pages?

Treat location data as content with one source of truth, and build pages from it. With a framework that supports static generation or server rendering, this is a small amount of code. A Next.js example using the App Router:

// app/locations/[state]/[city]/[store]/page.tsx
import { getAllStores, getStore } from "@/lib/locations";

export async function generateStaticParams() {
  const stores = await getAllStores();
  return stores.map((s) => ({ state: s.state, city: s.city, store: s.slug }));
}

export const revalidate = 3600; // refresh hours hourly

export default async function StorePage({ params }) {
  const { store: slug } = await params; // params is async in Next.js 15
  const store = await getStore(slug);
  return (
    <main>
      <h1>{store.name}</h1>
      <address>{store.street}, {store.city}, {store.region} {store.postalCode}</address>
      <a href={`tel:${store.phone}`}>{store.phoneDisplay}</a>
      <ul>
        {store.hours.map((h) => <li key={h.day}>{h.day}: {h.open} to {h.close}</li>)}
      </ul>
    </main>
  );
}

Revalidation matters for hours. A statically built page that never refreshes will eventually show last year's holiday schedule.

Where should location data live?

In one system that feeds both your listings and your pages. The failure you want to avoid is a website that says 9 to 6 while Google says 8 to 5, because someone updated one and not the other.

Options, with their tradeoffs:

Approach	Strength	Weakness
Headless CMS	Full control, fits your stack	You build the sync to listings yourself
Yext Pages	Tight link to Yext's listing data	Tied to Yext's platform and pricing
Synup locator and pages	Location pages and listings share one data source	Less flexible than a fully custom build
Custom database plus scripts	Cheapest at small scale	Maintenance grows with every location

Synup and similar platforms also expose APIs, so a common pattern is to keep the platform as the source of truth and pull data into your own static build. That keeps full control of the front end without a second copy of hours to maintain.

How do you check that it works?

Fetch a store page the way a non-rendering crawler would:

curl -s https://example.com/locations/texas/austin/south-congress/ | grep -i "south congress"

If the address and hours are not in that raw response, a crawler that skips JavaScript will not see them either. Also run a sample of store URLs through Google's URL Inspection tool in Search Console to confirm Google renders and indexes them.

FAQ

Can I keep my interactive map?

Yes. Render it on top of the static list. Just make sure the list and links exist without it.

Is a sitemap of location URLs enough?

It helps discovery, but internal links from region and city pages are what give crawlers a clear path and context.

Should closed stores keep their pages?

Redirect them to the nearest open location or the city page, so old links and bookmarks still land somewhere useful.

How many locations before this matters?

Even a few. A single JavaScript-only locator page can hide every location's hours from crawlers that skip scripts.

Building a Google Review Pipeline with the Business Profile API

Hello Nakama — Sun, 27 Sep 2026 20:26:46 +0000

You can build a working review pipeline on the Google Business Profile API with three pieces: a Pub/Sub subscription that tells you when a review arrives, a worker that fetches and stores the review, and a reply step that only posts after a human approves. Polling every location on a schedule works too, but notifications keep you inside quota and make alerts close to real time.

This post walks through the endpoints, a minimal Python worker, and the design choices that matter once you have hundreds of locations.

What do you need before you start?

API access. The Business Profile APIs require an access request to Google before your project can call them.
An OAuth client with the https://www.googleapis.com/auth/business.manage scope, authorized by an account that manages the locations.
A Google Cloud Pub/Sub topic, if you want push notifications.
Account and location IDs for the profiles you manage.

Which endpoints handle reviews?

Reviews still live on the v4 mybusiness.googleapis.com surface:

Action	Method and path
List reviews	`GET /v4/accounts/{accountId}/locations/{locationId}/reviews`
Get one review	`GET /v4/accounts/{accountId}/locations/{locationId}/reviews/{reviewId}`
Reply or edit a reply	`PUT /v4/accounts/{accountId}/locations/{locationId}/reviews/{reviewId}/reply`
Delete a reply	`DELETE /v4/accounts/{accountId}/locations/{locationId}/reviews/{reviewId}/reply`

The list call supports pageSize, pageToken, and orderBy, for example updateTime desc. Each review includes reviewId, reviewer, starRating as an enum from ONE to FIVE, comment, createTime, updateTime, and reviewReply if you already replied.

Check Google's current reference before you ship. This API family has been split and migrated over the years, and paths do change.

How do you get notified about new reviews?

Use the Business Profile Notifications API. You attach a Pub/Sub topic to the account and choose event types:

PATCH https://mybusinessnotifications.googleapis.com/v1/accounts/{accountId}/notificationSetting?updateMask=pubsubTopic,notificationTypes

{
  "name": "accounts/{accountId}/notificationSetting",
  "pubsubTopic": "projects/your-project/topics/gbp-events",
  "notificationTypes": ["NEW_REVIEW", "UPDATED_REVIEW"]
}

Grant publish rights on the topic to mybusiness-api-pubsub@system.gserviceaccount.com, or Google cannot deliver messages to it.

Treat a notification as a hint, not the data. The message tells you which location and review changed. Your worker then fetches the review itself.

What does a minimal worker look like?

Here is a stripped-down Python worker. It fetches the review, upserts it, and flags low ratings for a human.

import requests

API = "https://mybusiness.googleapis.com/v4"
STARS = {"ONE": 1, "TWO": 2, "THREE": 3, "FOUR": 4, "FIVE": 5}

def fetch_review(token, review_name):
    # review_name looks like accounts/123/locations/456/reviews/abc
    r = requests.get(
        f"{API}/{review_name}",
        headers={"Authorization": f"Bearer {token}"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

def handle_event(token, review_name, db, alerts):
    review = fetch_review(token, review_name)
    stars = STARS.get(review.get("starRating"), 0)

    db.upsert(
        key=review["name"],
        stars=stars,
        text=review.get("comment", ""),
        updated=review["updateTime"],
        replied="reviewReply" in review,
    )

    if stars <= 2 and "reviewReply" not in review:
        alerts.send(location=review_name.split("/reviews/")[0], stars=stars)

Key the store on the full review name. It is stable, and it makes the upsert idempotent when Pub/Sub delivers the same message twice, which it can.

How should replies work?

Draft automatically, publish manually. Use templates or a language model to draft a reply, store it as pending, and post only after someone approves it:

def post_reply(token, review_name, text):
    r = requests.put(
        f"{API}/{review_name}/reply",
        headers={"Authorization": f"Bearer {token}"},
        json={"comment": text},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

Replies are public and attached to your brand. An unreviewed automated reply to an angry customer is the kind of mistake that ends up in a screenshot.

What breaks at scale?

A few things, reliably:

Quota. Backfilling hundreds of locations with list calls burns quota fast. Backfill once, slowly, then rely on notifications.
Missed notifications. Run a nightly reconciliation that lists recent reviews per location and compares against your store.
Token ownership. If the authorizing user leaves the company, your refresh token dies with their access. Authorize with an account the business controls.
Edited reviews. Customers change ratings. Handle UPDATED_REVIEW and keep history if you report on it.

Should you build this or buy it?

Build it if reviews feed your own systems, such as a CRM or data warehouse, and you have engineers to maintain it. Buy if the goal is simply that someone replies well and on time.

On the buy side, the common options each have gaps. Birdeye has a broad suite but can be more than a team needs. Synup covers review monitoring, reply approvals, and scoped permissions, and it offers APIs so you can still pull data into your stack, though a full suite is overkill if reviews are your only use case. Podium ties requests to texting, which is great if you already text customers and less useful if you do not.

FAQ

Can I get reviews without API approval?

Not through the official API. Scraping Google Maps violates Google's terms and breaks often.

How far back can I fetch reviews?

The list endpoint pages through a location's reviews. Backfill once and store them yourself rather than refetching.

Can I reply to reviews on other platforms with this?

No. This covers Google only. Yelp, Facebook, and others have their own APIs and rules.

Should replies be written by AI?

Drafts, yes. Publishing, no. Keep a human approval step, especially for ratings of two stars or below.

LocalBusiness Schema for Multi-Location Sites: A Practical JSON-LD Pattern

Hello Nakama — Sat, 26 Sep 2026 20:38:55 +0000

For a multi-location site, put one Organization node on the brand level, and one LocalBusiness node (or a more specific subtype) on each location page. Give every node a stable @id, link each location to the brand with parentOrganization, and make sure the address, phone, and hours in the markup match the visible page and the Google Business Profile exactly. That is most of it. The rest is keeping it true.

Here is a pattern that scales from five locations to five hundred.

When should you use LocalBusiness?

Use it on pages that represent a real, physical place customers can visit or that serves a defined area. A store page, a clinic page, a branch page.

Do not use it just because your site talks about local topics. A blog about local marketing is not a local business. Google's local business structured data docs describe the intended use.

The brand node

Put this on the homepage, or in a shared layout, with the same @id everywhere:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Hardware",
  "url": "https://example.com/",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://www.linkedin.com/company/example-hardware"
  ]
}

Only include sameAs profiles that are real and owned by the brand.

The location node

On each location page, one node per location:

{
  "@context": "https://schema.org",
  "@type": "HardwareStore",
  "@id": "https://example.com/locations/austin-north/#location",
  "name": "Example Hardware Austin North",
  "url": "https://example.com/locations/austin-north/",
  "telephone": "+1-512-555-0100",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Example Rd",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78701",
    "addressCountry": "US"
  },
  "geo": { "@type": "GeoCoordinates", "latitude": 30.27, "longitude": -97.74 },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
      "opens": "08:00",
      "closes": "19:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": "Saturday",
      "opens": "09:00",
      "closes": "17:00"
    }
  ],
  "parentOrganization": { "@id": "https://example.com/#organization" }
}

The address and phone above are placeholder examples. Use your real data.

A few notes:

Use the most specific subtype that fits, such as HardwareStore, Dentist, or Restaurant. Fall back to LocalBusiness if nothing fits.
The @id is an identifier, not a link. Keep it stable. Changing it later breaks the connection between nodes.
parentOrganization points to the brand @id, so crawlers see one brand with many locations.

Generate it from the same data as the page

The biggest schema bug on multi-location sites is drift. The page says one set of hours, the markup says another, and the Google profile says a third.

Fix it structurally. Render the visible hours and the JSON-LD from the same location record:

function locationJsonLd(loc, site) {
  return {
    "@context": "https://schema.org",
    "@type": loc.schemaType || "LocalBusiness",
    "@id": `${site.url}locations/${loc.slug}/#location`,
    name: loc.name,
    url: `${site.url}locations/${loc.slug}/`,
    telephone: loc.phoneE164,
    address: {
      "@type": "PostalAddress",
      streetAddress: loc.street,
      addressLocality: loc.city,
      addressRegion: loc.region,
      postalCode: loc.postalCode,
      addressCountry: loc.country
    },
    openingHoursSpecification: loc.hours.map(h => ({
      "@type": "OpeningHoursSpecification",
      dayOfWeek: h.days,
      opens: h.opens,
      closes: h.closes
    })),
    parentOrganization: { "@id": `${site.url}#organization` }
  };
}

If the page template and the schema read from one object, they cannot disagree.

Handle special hours

Holiday hours can go in openingHoursSpecification with validFrom and validThrough. Remove them after the date passes. Stale holiday entries are a common source of wrong answers in search and AI tools.

Common mistakes

Mistake	Why it hurts	Fix
One LocalBusiness on the homepage for all locations	Merges many places into one	One node per location page
Markup hours differ from page	Conflicting signals	Render both from one record
Changing `@id` values	Breaks entity links	Treat `@id` as permanent
Adding reviews you do not show	Against guidelines	Only mark up visible, real content
LocalBusiness on non-location pages	Misleading	Limit to real place pages

Keeping it true at scale

Markup is only as good as the data behind it. If your hours live in five places, the schema will eventually be wrong somewhere. Most multi-location teams either keep a central location database that feeds the site, or use a listing platform that also powers location pages.

Options vary. Yext offers pages driven by its knowledge graph, with enterprise pricing and setup. Synup has store locator and local pages tied to its listings data, though teams with a custom CMS may prefer to keep rendering in their own stack and use its API instead. Uberall offers locator pages for international brands with sales-led onboarding. Or you build it yourself, which gives full control and full maintenance cost.

Validate before shipping

Run pages through Google's Rich Results Test and the Schema Markup Validator. Then spot check that the rendered HTML, not just your source, contains the JSON-LD, especially on client-rendered frameworks.

FAQ

Should every location page have its own LocalBusiness node?
Yes, if each page represents a distinct physical location.

Can I list all locations in one JSON-LD block on a store locator page?
You can reference them, but the full details belong on each location's own page.

Do I need geo coordinates?
They are optional but helpful. Use accurate values from your source data.

Does schema affect Google Business Profile?
No. They are separate. Keep them consistent by hand or through a shared data source.

Syncing Location Data to Google Business Profile Without Breaking It

Hello Nakama — Sat, 26 Sep 2026 20:30:55 +0000

A reliable Google Business Profile sync has four parts: one internal source of truth, field-level updates with an update mask, a read-back step that compares what Google actually shows, and a queue for edits Google rejected or changed. Most broken syncs skip the read-back. They assume a successful API response means the listing is live and correct. It does not.

These are practical notes for engineers building or maintaining a location data pipeline, whether for one brand or many.

What are you actually syncing?

A location record usually includes:

Business name
Address and service area
Primary phone
Regular hours and special hours
Primary and additional categories
Website URL
Attributes (accessibility, payment types, and so on)

Keep these in your own datastore with a stable internal ID per location, and map that ID to the Google location resource name. Never treat Google as the source of truth. It is a destination, and one that can change your data.

Which APIs are involved?

Google split the old My Business API into several APIs. For location data, the main one is the Business Information API, which reads and updates location fields. Account and access work sits in the Account Management API. Access to these APIs is not automatic. You request it through Google, and approval takes time, so plan for that before you build.

Check the current Business Profile APIs documentation for scopes, quotas, and endpoints, because details change.

Update one field at a time with a field mask

Send only what changed. The update call takes an updateMask, and anything outside the mask is left alone.

PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?updateMask=regularHours
Content-Type: application/json

{
  "regularHours": {
    "periods": [
      { "openDay": "MONDAY", "openTime": { "hours": 9 }, "closeDay": "MONDAY", "closeTime": { "hours": 18 } }
    ]
  }
}

Why this matters:

A full-record overwrite can wipe fields another team or the owner edited directly.
Narrow masks make failures easier to diagnose.
Smaller payloads are easier to audit.

Build your diff logic to emit a mask per changed field, not per record.

Make every write idempotent

Your sync will retry. Networks fail, quotas bite, jobs restart. Design so that sending the same update twice has the same result as sending it once.

A simple pattern:

def sync_location(loc):
    desired = normalize(loc.source_record)
    current = normalize(fetch_google_location(loc.google_name))
    changed = diff_fields(desired, current)
    if not changed:
        return "noop"
    mask = ",".join(changed)
    patch_location(loc.google_name, desired, update_mask=mask)
    enqueue_readback(loc.id, changed, delay_minutes=30)
    return "patched"

Normalization is the unglamorous core. Phone formats, time zones, trailing slashes on URLs, and whitespace in names all create false diffs if you do not normalize both sides the same way.

Read back what Google actually shows

Google can accept an update, then modify or reject it after review. It can also apply edits from users or its own data sources. The Business Information API exposes a way to fetch the Google-updated version of a location, which shows where Google's view differs from what you sent.

Your read-back job should:

Fetch the location after a delay.
Compare each changed field to the desired value.
Mark the change as live, modified, or rejected.
Alert a human for anything not live.

State	Meaning	Action
live	Google shows your value	Close the change
modified	Google shows a different value	Review, possibly contest
rejected	Update did not apply	Check guidelines, fix data, resubmit
pending	Not resolved yet	Recheck later

Without this table in your system, you are guessing.

Detect drift on a schedule

Even when nothing changes on your side, listings drift. A user suggests new hours. Google infers a category. Run a scheduled job that fetches every location, diffs against your source of truth, and reports differences. Decide per field whether to auto-revert or flag for review. Auto-reverting hours is usually safe. Auto-reverting a name change Google made after a guideline review is not.

Respect quotas and back off

The APIs have quotas. Batch work by account, spread writes over time, and use exponential backoff on rate-limit errors. Log every request and response with the internal location ID. When someone asks why a listing changed, the log is your answer.

Build or buy?

If you manage a few locations, a small script plus a spreadsheet may be enough. If you manage many, or need Apple Business Connect, Bing Places, and directories too, building every integration yourself gets expensive to maintain.

Listing platforms with APIs can sit in the middle. Yext has a deep API and data model, but it is enterprise-weight. Synup offers listing APIs and MCP support for LLM tooling, though you still need to design your own source of truth and review flow around it. Uberall provides APIs aimed at larger international brands, with sales-led onboarding. BrightLocal has an API focused more on audits and citation data than on direct profile management. Whichever route you take, keep the read-back and drift checks. A vendor can distribute data, but your system should still verify it.

FAQ

Can I use the API without approval?
No. You need to request access to the Business Profile APIs first.

Should I overwrite user-suggested edits automatically?
Only for fields where you are certain your data is correct, such as hours. Review the rest.

How often should drift checks run?
Daily is common for multi-location brands. Weekly can work for small, stable portfolios.

Does the API update Apple Maps or Bing?
No. Those platforms have their own tools and processes.

DEV Community: Hello Nakama

Auditing How Your Locations Appear on Google Maps with the Places API

What is the Places API (New)?

How do you get the Place ID for each location?

Which fields should the audit request?

How do the hours come back?

What does the input file look like?

What does the audit script look like?

What should you do with the results?

How often should you run it?

Does this replace a listing platform?

FAQ

Do I need Business Profile API access to run this?

Can I store the Places responses for trend reports?

Why do my hours match in Business Profile but not in the Places API?

Does this work for service-area businesses?

Designing a Location Data Model That Works as a Single Source of Truth

What should a location record contain?

How do you define the schema?

What does a valid record look like?

How do you validate beyond the schema?

How do you map one record to many outputs?

How do you push changes safely?

Who should be allowed to edit which fields?

Should you build this or use a platform?

FAQ

Why JSON Schema instead of a database schema?

Should hours be stored in local time or UTC?

Where should the Google Place ID live?

How do I handle a store that is closing?

Monitoring Google's Edits to Your Business Profiles with Pub/Sub Notifications

What notifications can the Business Profile APIs send?

How do you set up the Pub/Sub topic?

How do you link the Business Profile account?

What does a notification contain?

How do you see what Google changed?

What does the worker look like?

How do you accept or reject a change?

What if you cannot use notifications?

Where does this fit with a listing platform?

FAQ

Does a GOOGLE_UPDATE notification include the new value?

Should I auto-reject every Google update?

How many topics can one account use?

Can I monitor Q&A this way?

Tracking Google Business Profile Clicks in GA4 with UTM Parameters

Why do GBP clicks disappear into organic traffic?

Which UTM values should you use?

How do you tag hundreds of locations at once?

Should you worry about tagged URLs on a profile?

How do you find the traffic in GA4?

How do you check the numbers against Google's own counts?

What breaks this setup?

FAQ

Will UTM tags hurt my local rankings?

Why not use utm_medium=gbp?

Can I tag appointment or menu links too?

How often should I audit the tags?

Guardrails for Letting an AI Agent Edit Your Business Listings

Why are listings a risky target for agents?

How should the tools be designed?

What should a proposal contain?

How do you scope credentials?

How do you defend against prompt injection?

What should you log?

Should you build this or use a platform?

FAQ

Can I let an agent auto-apply low-risk changes?

What is MCP?

Which fields should agents never edit alone?

How do I test an agent before giving it write access?

Store Locators That Crawlers Can Actually Read

What is wrong with a typical locator?

Do crawlers really not run JavaScript?

What URL structure works best?

How do you generate the pages?

Where should location data live?

How do you check that it works?

FAQ

Can I keep my interactive map?

Why not use `utm_medium=gbp`?