Business Locations

In GMBMantra, a "location" is one Google Business Profile listing — a single storefront, service-area business, or office that your Google account either owns or manages. The full list comes from Google during sign-in: we call the GBP API, walk every account you have access to, and write each verified listing into our discovered_locations store. You then decide which of those discovered locations are active in GMBMantra by enabling them in the location picker — disabled ones stay linked to your account but don't sync reviews, performance, or posts, and don't count toward billing.

Once a location is active, the platform owns the day-to-day sync: new reviews, performance metrics, photos, and search keywords pull from Google on a recurring cron, and the location picker in the top bar of every dashboard page is how you switch context between them.

Managing Your Locations

1. 1

   Open the location picker (top bar of dashboard)

   The dropdown in the top bar of every dashboard page is the location switcher. It lists every location you've enabled in GMBMantra; each row shows the business name and the locality / administrative area pulled from storefrontAddress. Pick one and every page on the dashboard — /dashboard, /reviews, /heatmap, /insights — re-scopes to that location's data.

2. 2

   Toggle locations on or off

   Open the location manager and flip the toggle next to any location. On flips its UserLocation.status to active and starts syncing reviews, performance metrics, photos, search keywords, and posts from Google on the standard cron cadence. Off flips it to disabled — the underlying data and history stay in the database, but no fresh sync runs and the location stops counting toward billing or automation. You can flip a location back on later without losing anything.

3. 3

   Add new locations from Google (Refresh from Google)

   If you've added a new listing in Google Business Profile — business.google.com — or someone has just added you as a manager on theirs, click Refresh from Google in the location manager. That re-runs discoverUserLocations against the GBP API: every account you have access to is walked again, any new verified listings are written into discovered_locations, and a fresh UserLocation row is created so you can enable them. New locations show up in the picker after the refresh completes.

4. 4

   (Agency) Bring a client's locations along when they sign up

   On /agency/clients, Invite a Client sends the client an invite link. When the client clicks through and signs in with their own Google account, GMBMantra runs the same discovery against that account — every verified GBP listing they own or manage becomes a discovered location attached to them, not to the agency. The agency dashboard then aggregates across clients, but the locations remain owned by the client's Google identity.

Key Concepts

Verified vs unverified

Only verified GBP listings come through discovery — that's isVerified: true on the underlying DiscoveredLocation. If a location is unverified in Google Business Profile, Google's API doesn't expose the data we need (reviews, performance, posts), so GMBMantra can't sync it. Finish verification at business.google.com first, then click Refresh from Google here.

Active vs disabled vs lost-access

The status on each UserLocation row tells you where a location stands:

• active — fully enabled. Reviews, performance, search keywords, and media sync on the standard cron cadence; the location appears in the top-bar picker and in every metric.
• disabled — toggled off (or auto-disabled when discovery stopped seeing it). Data and history are kept; no fresh sync runs; the location is hidden from the picker. Flip the toggle back on to resume.
• lost_access — the GBP API returned 403/PERMISSION_DENIED for this location. Usually means your role on the listing was revoked in Google Business Profile. Re-add yourself as a manager at business.google.com, then Refresh from Google.

What happens when a location vanishes from GBP

GMBMantra does not delete locations automatically. If a location stops appearing in Google's discovery response — listing removed, your role revoked, or the API returns partial data because of a transient error — we mark the UserLocation as disabled instead of removing the row. That's deliberate: API blips and rate limits would otherwise wipe legitimate access. Locations that were manually enabled (syncSource: 'manual_refresh') or migrated in (syncSource: 'migration') are never auto-disabled — they only flip off when you explicitly toggle them. If a location really is gone from GBP, leave it disabled or remove it through the UI.

Sync cadence

Once a location is active, the cron pipeline picks it up automatically. Each sync type has its own threshold: review sync runs incrementally on a minutes-level cadence (only fetches new reviews since the last run), and performance, search keywords, media, and media metadata sync are all on hour-level thresholds — typically once per day. The cron only fires a job when the threshold has elapsed since lastReviewSync / lastPerformanceSync / etc., so a freshly-enabled location starts filling in within minutes for reviews and within a day for the rest.

Frequently Asked

Related