How to Push Holiday Hours to All Your GBP Locations via API

A restaurant chain with 40 locations needs to push holiday hours for Thanksgiving through New Year’s across all locations before the holiday rush. Doing it manually would take all day.

When the GBP API Is Worth Setting Up

Manual GBP management works for 1-5 locations. Beyond that, the API provides efficiency:

API makes sense for:

  • 10+ locations
  • Frequent bulk updates (holiday hours, seasonal changes)
  • Consistent attribute updates across portfolio
  • Automated monitoring and alerts

API complexity includes:

  • Google Cloud project setup
  • OAuth authentication
  • API credential management
  • Development resources to implement

For large portfolios or agencies managing many clients, the setup investment pays off.

Prerequisites

Before using the API:

  • Google Cloud project created
  • Business Profile API enabled
  • OAuth credentials configured
  • Access to all GBP locations via same account
  • Some technical capability (or developer support)

The gbp-api-automation skill doesn’t execute API calls directly — it helps you plan and structure the API workflow.

The Holiday Hours Update Prompt

"Design a GBP API workflow to push holiday hours to all 40 locations
of [Brand Name] for the following holidays:
Thanksgiving: closed
Christmas Eve: 11am-3pm
Christmas: closed
New Year's Eve: 11am-8pm
New Year's Day: closed

I have GBP API credentials set up.
Show me the API call structure and how to handle errors if some
locations fail to update."

The API Call Structure

GBP API Holiday Hours Update: [Brand Name] — 40 Locations

ENDPOINT
Use: Google My Business API (Business Profile API)
Method: PATCH
Endpoint: /accounts/{accountId}/locations/{locationId}

SPECIAL HOURS FIELD
The specialHours field handles holiday hours:

{
  "specialHours": {
    "specialHourPeriods": [
      {
        "startDate": {"year": 2024, "month": 11, "day": 28},
        "endDate": {"year": 2024, "month": 11, "day": 28},
        "isClosed": true
      },
      {
        "startDate": {"year": 2024, "month": 12, "day": 24},
        "openTime": "11:00",
        "closeTime": "15:00",
        "isClosed": false
      },
      {
        "startDate": {"year": 2024, "month": 12, "day": 25},
        "endDate": {"year": 2024, "month": 12, "day": 25},
        "isClosed": true
      },
      {
        "startDate": {"year": 2024, "month": 12, "day": 31},
        "openTime": "11:00",
        "closeTime": "20:00",
        "isClosed": false
      },
      {
        "startDate": {"year": 2025, "month": 1, "day": 1},
        "endDate": {"year": 2025, "month": 1, "day": 1},
        "isClosed": true
      }
    ]
  }
}

Batch Processing All 40 Locations

BATCH PROCESSING APPROACH

Step 1: Retrieve all location IDs
GET /accounts/{accountId}/locations
Response: List of all 40 location IDs with names

Step 2: Loop through locations
For each locationId in list:
  - PATCH specialHours to location
  - Log success/failure
  - If rate limit hit, pause 60 seconds

Step 3: Error handling per location
  - 200 OK: Success, log and continue
  - 403 Forbidden: Location not owned by account → skip, log for manual review
  - 429 Rate limit: Pause 60 seconds, retry
  - 400 Invalid data: Log specific error, check hours format
  - 5xx Server error: Retry up to 3 times with backoff

Step 4: Summary report
  - Successful updates: [count]
  - Failed updates: [count]
  - Failed location IDs for manual review: [list]

Error Handling and Verification

ERROR HANDLING MATRIX

Error | Cause | Action
403 Forbidden | Location not owned by this account | Skip, add to manual review list
429 Rate Limit | Too many requests | Pause 60 sec, retry
400 Bad Request | Invalid hours format | Log error detail, fix and retry
401 Unauthorized | Token expired | Refresh OAuth token, retry
404 Not Found | Invalid location ID | Verify location ID, skip if invalid
5xx Server Error | Google-side issue | Retry with exponential backoff

RETRY LOGIC
Max retries: 3 per location
Backoff: 30s, 60s, 120s
After 3 failures: Add to manual review list, continue to next location

Verification After Update

VERIFICATION STEP

After running the batch update:

1. Pull 5 random location profiles
   GET /accounts/{accountId}/locations/{randomLocationId}
   Verify specialHours field shows correct holiday schedule

2. Manual spot check
   Visit Google Maps for 2-3 locations
   Confirm holiday hours display correctly

3. Run verification report
   "Pull current holiday hours for 5 random [Brand Name] locations.
   Verify they match the push we just ran."

Other Bulk API Use Cases

Holiday hours is one use case. The API handles:

Attribute updates: Push the same attribute (e.g., “Outdoor seating”) to all locations at once.

{
  "attributes": [
    {
      "attributeId": "has_outdoor_seating",
      "valueType": "BOOL",
      "values": [true]
    }
  ]
}

Description updates: Push a new brand description or messaging update across all locations.

Category changes: Add or remove secondary categories in bulk.

Photo management: Upload standard brand photos to all locations.

Hours changes: Update regular hours (not just holidays) across portfolio.

When to Use API vs. Manual

Use API for:

  • 10+ locations needing the same change
  • Time-sensitive updates (holiday hours before the holiday)
  • Frequent recurring updates
  • Consistency-critical changes

Manual is fine for:

  • Single location updates
  • Location-specific changes
  • One-time adjustments
  • When API isn’t set up

Implementing the Workflow

For agencies: Partner with a developer to build the API workflow. The prompt-generated specifications can guide implementation.

For enterprises: Your development team implements based on API documentation. Claude provides the workflow design.

For those without dev resources: Use GBP bulk upload spreadsheets (available in GBP manager for some updates) or third-party tools that wrap the API.

The Complete API Workflow

  1. Plan the update (what changes, which locations)
  2. Design the API workflow with Claude
  3. Implement or hand off to developer
  4. Test on 2-3 locations first
  5. Run full batch
  6. Handle errors and retries
  7. Verify with spot checks
  8. Document for future updates

The gbp-api-automation skill doesn’t execute the API calls — it designs the workflow that you or your team implements. The value is in the planning and error handling logic, not the execution itself.

For 40+ locations with regular updates, API automation saves hours per update cycle. The initial setup investment pays off quickly.