Google Business Profile

Overview

The Google Business Profile (GBP) integration connects your client's Business Profile locations to the platform, enabling automated audits across 10 scoring dimensions, AI-generated content suggestions, and direct profile updates through the admin UI or MCP tools.

Read This First

In plain language:

• the score matters
• profile truth matters more
• website and GBP should agree
• posts and replies still need sensible review

Prerequisites

• A Google account that owns or manages at least one Business Profile
• Access to Google Cloud Console
• The server running with MongoDB connected

Google Cloud Setup

Step 1: Google Cloud Project

If you already have a Google Cloud project with OAuth configured for GA4/GSC connections, skip to Step 2 — the same project and credentials work for GBP.

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Note the Project ID for future reference

Step 2: Enable the GBP APIs

Enable all three Business Profile APIs in your Google Cloud project:

Step 3: OAuth Consent Screen

If you already configured the consent screen for GA4/GSC, just add the GBP scope:

1. Go to APIs & Services → OAuth consent screen
2. Click Edit App
3. On the Scopes step, click Add or Remove Scopes
4. Add: https://www.googleapis.com/auth/business.manage
5. Save

If creating a new consent screen:

1. Choose External user type
2. Fill in app name, support email, developer contact email
3. Add the scope: https://www.googleapis.com/auth/business.manage
4. Add test users (your Google account email) — required while app is in "Testing" status
5. Save and continue through all steps

Step 4: OAuth Client Credentials

If you already have OAuth credentials for GA4/GSC, use the same ones — no new credentials needed.

If creating new:

1. Go to APIs & Services → Credentials
2. Click + Create Credentials → OAuth client ID
3. Application type: Web application
4. Add authorized redirect URIs:
   • Production: https://api.v2.affinitydesign.ca/integrations/google/callback
   • Local dev: http://localhost:8000/integrations/google/callback
5. Copy the Client ID and Client Secret

Step 5: Environment Variables

# Google OAuth (shared with GA4/GSC connections)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://api.v2.affinitydesign.ca/integrations/google/callback

For local dev, use http://localhost:8000/integrations/google/callback.

These are the same 3 variables used by GA4 and GSC connections. If already set, GBP works automatically — no additional env vars needed. No GBP-specific API keys are required.

Connecting Locations

Via Admin UI

1. Navigate to SEO → Google Business in the admin panel
2. Select a client from the picker
3. Click Connect GBP (triggers the OAuth popup)
4. The OAuth flow hits: GET /integrations/google/authorize?clientId={id}&serviceType=gbp
5. User grants business.manage scope
6. Callback auto-discovers all GBP accounts and locations
7. A Connection document is created with serviceType: "gbp" per location

Via API

# Get the OAuth URL (open in browser)
curl "https://api.v2.affinitydesign.ca/integrations/google/authorize?clientId=CLIENT_ID&serviceType=gbp"

# After completing OAuth, verify the connection exists
curl -H "Authorization: Bearer ADMIN_TOKEN" \
  "https://api.v2.affinitydesign.ca/admin/gbp/connections/CLIENT_ID"

What Happens on Connect

1. OAuth consent screen with business.manage scope
2. Token exchange → access + refresh tokens stored in Connection.oauthTokens
3. Auto-discovery: lists all GBP accounts → lists locations per account
4. First location is set as the default in serviceConfig
5. For multi-location businesses, each location gets its own Connection document
6. Token auto-refresh: google-auth.js listens for tokens events and persists new credentials

Running Audits

Via Admin UI

1. Go to SEO → Google Business
2. Click a location card
3. Click Run Audit — scores the profile across 10 dimensions
4. Or click Auto Audit — scores + auto-commits critical/high fixes

Via API

# Run audit
curl -X POST -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "CLIENT_ID"}' \
  "https://api.v2.affinitydesign.ca/admin/gbp/CONNECTION_ID/audit"

# List audit history
curl -H "Authorization: Bearer ADMIN_TOKEN" \
  "https://api.v2.affinitydesign.ca/admin/gbp/CONNECTION_ID/audits"

Scoring Dimensions

The audit scores profiles across 10 dimensions (100 points total):

MCP Tools

The MCP plugin exposes 10 GBP tools for use in AI agent sessions:

Plus additional read/write tools and 3 resources exposed through the MCP plugin at mcp/plugins/gbp.js.

Troubleshooting

Architecture Reference

OAuth Flow:
  Admin UI → GET /integrations/google/authorize?serviceType=gbp
           → Google consent screen (business.manage scope)
           → GET /integrations/google/callback
           → Token stored in Connection.oauthTokens
           → Auto-discovers accounts + locations

API Layer:
  routes/gbp.js         → 7 admin endpoints (audit, chat, commit, auto)
  routes/client.js      → 2 client-facing endpoints (read-only)

Utilities:
  utils/google-auth.js  → OAuth2 client factory + auto-refresh
  utils/gbp-client.js   → 12 GBP API wrapper functions
  utils/gbp-scoring.js  → 10-dimension scoring engine
  utils/gbp-audit-engine.js → Full audit pipeline (fetch → score → AI content)
  utils/gbp-verticals.js → Vertical detection + rules

Models:
  models/connection.js  → serviceType: "gbp", multi-location support
  models/gbp-audit.js   → Audit snapshots with scores, gaps, AI content

MCP:
  mcp/plugins/gbp.js    → 10 tools (read + write) + 3 resources