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](#overview)
2. [Prerequisites](#prerequisites)
3. [Google Cloud Console Setup](#google-cloud-console-setup)
4. [Environment Configuration](#environment-configuration)
5. [OAuth Redirect URI Configuration](#oauth-redirect-uri-configuration)
6. [Permissions & Scopes](#permissions--scopes)
7. [Development vs Production](#development-vs-production)
8. [Troubleshooting](#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](https://console.cloud.google.com/)
- A verified business location on Google Maps

---

## Google Cloud Console Setup

### Step 1: Create a New Project

1. Navigate to [Google Cloud Console](https://console.cloud.google.com/)
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:
```json
{
  "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)

```python
# 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:

```env
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

```python
# 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](https://business.google.com/)
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](https://developers.google.com/my-business)
- [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)
- [Google Cloud Console Support](https://support.google.com/cloud/)

---

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