HH/apps/social/setup_docs/google_business.md

Google Business Profile API Setup Guide

This guide provides step-by-step instructions for setting up Google Business Profile (formerly Google My Business) API integration for managing reviews.

---

Table of Contents

1. Overview
2. Prerequisites
3. Google Cloud Console Setup
4. Environment Configuration
5. OAuth Redirect URI Configuration
6. Permissions & Scopes
7. Development vs Production
8. Troubleshooting

---

Overview

API Version: My Business API v4 / Account Management v1 Base URL: Google API Services Auth Method: OAuth 2.0

Features Supported

• Fetch business locations
• Read Google reviews for locations
• Reply to reviews as the business owner
• Monitor review ratings and feedback

---

Prerequisites

• A Google account with owner/manager access to a Google Business Profile
• Access to Google Cloud Console
• A verified business location on Google Maps

---

Google Cloud Console Setup

Step 1: Create a New Project

1. Navigate to Google Cloud Console
2. Click on the project selector dropdown at the top
3. Click "New Project"
4. Enter project details:
   • Project Name: e.g., "PX360 Social Integration"
   • Organization: Select your organization (if applicable)
5. Click "Create"
6. Select your new project

Step 2: Enable Required APIs

1. Go to "APIs & Services" → "Library"
2. Search for and enable the following APIs:
   • Google My Business API (Note: May require verification)
   • My Business Account Management API
   • My Business Business Information API

⚠️ Important: Google My Business API requires approval from Google. You may need to fill out a form explaining your use case.

Step 3: Configure OAuth Consent Screen

1. Go to "APIs & Services" → "OAuth consent screen"
2. Select "External" user type (unless you have a Google Workspace account)
3. Click "Create"
4. Fill in the required fields:
   • App Name: Your application name
   • User Support Email: Your support email
   • App Logo: Upload your logo
   • Application Home Page: Your website URL
   • Authorized Domains: Your domain(s)
   • Developer Contact Email: Your email
5. Click "Save and Continue"
6. Add scopes (click "Add or Remove Scopes"):
   • https://www.googleapis.com/auth/business.manage
7. Click "Save and Continue"
8. Add test users (for development)
9. Click "Save and Continue"

Step 4: Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. Select "Web application"
4. Configure:
   • Name: e.g., "PX360 Web Client"
   • Authorized JavaScript origins:
     • Development: http://127.0.0.1:8000
     • Production: https://yourdomain.com
   • Authorized redirect URIs:
     • Development: http://127.0.0.1:8000/social/callback/GO/
     • Production: https://yourdomain.com/social/callback/GO/
5. Click "Create"
6. Download the JSON file - This is your credentials file

Step 5: Save Credentials File

1. Rename the downloaded JSON file to gmb_client_secrets.json
2. Place it in your project's secrets/ directory:

   your_project/
   ├── secrets/
   │   └── gmb_client_secrets.json
   └── ...
   

The JSON file structure should look like:

{
  "web": {
    "client_id": "xxxxx.apps.googleusercontent.com",
    "project_id": "your-project-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "your-client-secret",
    "redirect_uris": ["http://127.0.0.1:8000/social/callback/GO/"]
  }
}

---

Environment Configuration

Django Settings (settings.py)

# Google Business Profile API Configuration
import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent.parent

# Google My Business (Reviews) Configuration
GMB_CLIENT_SECRETS_FILE = BASE_DIR / 'secrets' / 'gmb_client_secrets.json'
GMB_REDIRECT_URI = 'https://yourdomain.com/social/callback/GO/'

Environment Variables (.env)

While the credentials are in a JSON file, you can set the redirect URI via environment:

GMB_REDIRECT_URI=https://yourdomain.com/social/callback/GO/

---

OAuth Redirect URI Configuration

The redirect URI must match exactly what's configured in Google Cloud Console.

Development

http://127.0.0.1:8000/social/callback/GO/
http://localhost:8000/social/callback/GO/

Production

https://yourdomain.com/social/callback/GO/

⚠️ Note: Google accepts both HTTP and HTTPS for localhost/127.0.0.1, but production must use HTTPS.

---

Permissions & Scopes

The application requires the following OAuth scope:

Scope	Description	Required
https://www.googleapis.com/auth/business.manage	Full access to manage business listings and reviews	✅ Yes

Code Reference

# apps/social/utils/google.py
SCOPES = ['https://www.googleapis.com/auth/business.manage']

API_VERSION_MYBUSINESS = 'v4'
API_VERSION_ACCOUNT_MGMT = 'v1'

---

Development vs Production

Development Setup

Setting	Value
GMB_REDIRECT_URI	http://127.0.0.1:8000/social/callback/GO/
Protocol	HTTP allowed for localhost
App Verification	Not required for testing
User Access	Only added test users

Production Setup

Setting	Value
GMB_REDIRECT_URI	https://yourdomain.com/social/callback/GO/
Protocol	HTTPS required
App Verification	Required by Google
User Access	Any Google account

Google App Verification

For production, if your app requests sensitive scopes, you may need to go through Google's verification process:

1. Submit your app for verification in Google Cloud Console
2. Provide a demo video showing how the integration works
3. Wait for Google's review (can take several days to weeks)

Alternative: Use a service account for internal business use (no verification needed if only accessing your own business data).

---

Service Account Alternative (Recommended for Internal Use)

If you're only managing your own business locations, consider using a Service Account:

Step 1: Create Service Account

1. Go to "IAM & Admin" → "Service Accounts"
2. Click "Create Service Account"
3. Enter name and description
4. Click "Create and Continue"
5. Skip optional steps
6. Click "Done"

Step 2: Create Key

1. Click on the created service account
2. Go to "Keys" tab
3. Click "Add Key" → "Create new key"
4. Select "JSON"
5. Click "Create"
6. Save the JSON file securely

Step 3: Grant Business Access

1. Go to Google Business Profile Manager
2. Select your business
3. Go to "Users" → "Add users"
4. Add the service account email (found in the JSON file)
5. Grant appropriate access level (Owner or Manager)

---

Troubleshooting

Common Error: "Access Denied - Requested client not authorized"

Cause: OAuth consent screen not configured or app not verified.

Solution:

1. Ensure OAuth consent screen is properly configured
2. Add user as a test user if app is in testing mode
3. Submit app for verification if needed for production

---

Common Error: "Invalid Grant"

Cause: Authorization code expired or already used.

Solution:

• Authorization codes are single-use and expire quickly
• Ensure your code handles the callback immediately
• Check that redirect URI matches exactly

---

Common Error: "The caller does not have permission"

Cause: User doesn't have access to the business location.

Solution:

1. Verify user is an Owner or Manager of the Google Business Profile
2. Check business account permissions at business.google.com
3. Ensure the correct account is selected during OAuth

---

Common Error: "API Not Enabled"

Cause: Required APIs not enabled in Google Cloud Console.

Solution:

1. Go to APIs & Services → Library
2. Enable: Google My Business API
3. Enable: My Business Account Management API
4. Wait a few minutes for changes to propagate

---

Common Error: "Token Refresh Failed"

Cause: Refresh token expired or revoked.

Solution:

• Google OAuth tokens expire after 6 months of inactivity
• User must re-authenticate
• Ensure offline_access is requested during initial auth

---

Common Error: "Quota Exceeded"

Cause: API quota limit reached.

Solution:

• Default quota: varies by API method
• Request higher quota in Google Cloud Console
• Implement rate limiting in your application

---

API Quotas & Limits

Resource	Default Limit
Read Requests	150 per minute
Write Requests	50 per minute
Locations per Account	10,000

The application implements rate limiting to stay within these bounds.

---

Verification

After setup, verify the integration:

1. Ensure gmb_client_secrets.json is in place
2. Navigate to /social/ in your application
3. Click "Connect Google Business"
4. Authorize with your Google account
5. Select your business location
6. Verify reviews are fetched
7. Test replying to a review

---

Support Resources

• Google Business Profile API Documentation
• OAuth 2.0 for Web Server Applications
• Google Cloud Console Support

---

Last Updated: February 2026 API Version: My Business v4 / Account Management v1