Google Business Profile setup

Google Business Profile (GBP) connects each business's locations for three things:

• Reviews show up in the engagement inbox (synced every 6 hours), with AI-drafted replies that go out only through Approvals.
• Posts (What's New, Offer, Event) publish from the Social Poster.
• Profile insights (calls, direction requests, website clicks, and Maps and Search views) appear on /local-falcon and in the gbp_insights MCP tool.

It rides the same Google Cloud OAuth client as sign-in, GA4/Search Console, YouTube and Google Ads. Only the scope and the redirect URI differ.

#1. Request Business Profile API access (Google gates it)

Google does not open the Business Profile APIs to every Cloud project. Until your project is approved, every call answers 403 SERVICE_DISABLED or hits a quota of zero. The app shows "API access pending" on the Integrations card, the Local Falcon insights card and the inbox. Nothing breaks, and nothing needs reconnecting once access is granted.

1. Make sure the Google account that owns the Cloud project manages a verified Business Profile that has been live for 60+ days. Google checks this.
2. Submit the GBP API access request form: https://developers.google.com/my-business/content/prereqs#request-access (choose "Application for Basic API Access"). Use the same Cloud project number as GOOGLE_OAUTH_CLIENT_ID.
3. Google answers by email, usually within a few days to two weeks. Approval raises the quotas from 0 to the standard per-minute limits.

#2. Enable the APIs on the Cloud project

In APIs & Services → Library, enable:

The v4 API does not appear in the Library until access is approved. Enable it afterwards. It is still the only surface for reviews and local posts.

#3. OAuth client

On the existing OAuth client (APIs & Services → Credentials):

• Add the authorized redirect URI GOOGLE_GBP_REDIRECT_URI:
  • local: http://localhost:4000/integrations/gbp/callback
  • prod: https://marketing-api.keyescode.com/integrations/gbp/callback
• Add the scope https://www.googleapis.com/auth/business.manage to the consent screen (Data Access → Add or remove scopes → "Manually add scopes", since it is not listed until the v4 API is enabled). Google classes it as non-sensitive, so adding it needs no justification and does not reopen OAuth verification: the Verification Center still read "verified" after it was saved.

#4. Environment

Migration 1790251730000-GoogleBusinessProfile creates gbp_connections, gbp_locations and gbp_daily_metrics, and adds rating to social_comments. It runs at start like every other migration.

#Production status (project keyescode, 472961833586)

Done on 2026-09-23 (MARK-9VLUKL):

• business.manage on the consent screen, with no re-verification needed
• Both GBP redirect URIs on OAuth client 472961833586-1qud…
• GOOGLE_GBP_REDIRECT_URI set on the Railway @marketing-os/api service
• Account Management, Business Information and Performance APIs enabled
• Basic API Access form submitted 2026-09-23: support case 8-6991000041976 (Google quotes 7–10 business days)
• Google My Business API (v4) enabled. It only appears after approval
• First connect, with reviews in social_comments

#5. Connect

Settings → Integrations → Google Business Profile → Connect → Google consent → back on Integrations with the location picker open → choose locations → Save locations. Each chosen location becomes a Social Poster destination and a review source.

#Schedules and quota

Locations are walked one at a time, and a 429 is retried once after a pause. One "access pending" answer stops the run for that business.

#What is not verified

No code path has been run against real Google: the APIs are gated, and the project had not been approved when this shipped. The request and response shapes follow Google's published references.