If you have ever attempted to integrate the Google Business Profile (GBP) API (formerly Google My Business) into a production application, you know firsthand that it can feel like navigating an obstacle course in the dark.
Between multi-part OAuth 2.0 consent screens, access tokens expiring after a strict 60 minutes, pagination requiring manual nextPageToken cursor handshakes, and an ecosystem fragmented across four completely separate Google Cloud APIs, what should be an afternoon feature frequently devolves into weeks of debugging.
At VitableTech, our engineering team manages massive multi-location local SEO infrastructures, review management pipelines, and automated business analytics for enterprise clients and digital marketing agencies across the globe. We grew frustrated with setting up boilerplate backend servers just to verify an OAuth redirect or test a single metric endpoint.
That is why we built and published the VitableTech Google Business Profile API Playground and open-sourced our battle-hardened @vitabletech/gbp-sdk.
-
1.
Fragmented Cloud Endpoints: Business Information, Reviews, Performance Metrics, and Verifications live under distinct hostnames (
mybusinessbusinessinformation.googleapis.com,businessprofileperformance.googleapis.com, etc.) with incompatible request structures. -
2.
The 60-Minute Token Cliff: Google access tokens expire on the hour. Without strict concurrency-safe refresh token management, high-volume production jobs throw cascading
401 Unauthorizederrors. -
3.
Deprecation of Legacy Insights: Google sunset the legacy GMB Insights API. The modern Performance API v1 uses entirely new daily time-series metrics and monthly search keyword impression schemas that lack thorough documentation.
-
4.
Cryptic Pagination Loops: Multi-location enterprises with 1,000+ branch locations must handle recursive cursor requests without hitting Google's sensitive rate limits.
Meet the Solution: VitableTech GBP API Playground
The GBP API Playground is a zero-setup, web-based developer environment hosted at https://gbp-playground.vitabletech.in/. It allows any engineer or technical marketer to test Google Business Profile integrations in seconds using their own Google Cloud Console credentials.
Bring Your Own Credentials (BYOC)
Paste your Google Client ID & Secret to authenticate directly against your company's Google Cloud project. No pre-seeded demo data locks you in.
Zero-Storage Security Policy
Your Client Secret, access tokens, and refresh tokens reside exclusively in client-side memory and ephemeral browser session storage. Nothing is stored on our database.
Interactive Swagger UI Docs
Jump into /api-docs/ to inspect full OpenAPI 3.0 schemas, test parameters, and examine actual raw JSON payloads.
Performance API v1 Ready
Query daily impressions, direction requests, phone calls, and monthly search keyword breakdowns without guessing JSON request envelopes.
Step-by-Step: How to Test GBP APIs in 3 Minutes
Here is the exact step-by-step flow to authenticate and execute your first Google Business Profile API call using the playground:
Create an OAuth 2.0 Web Application in Google Cloud
Navigate to the Google Cloud Console → APIs & Services → Credentials. Create an OAuth 2.0 Client ID and choose Web application as the application type.
Whitelist the Mandatory Authorized Redirect URI
Under Authorized redirect URIs in Google Cloud Console, add the following exact URL:
https://gbp-playground.vitabletech.in/auth/google/callback
Tip: The playground provides a 1-click "Copy URI" button right at the top of the interface for convenience.
Authenticate with Google
Return to gbp-playground.vitabletech.in, enter your Client ID and Client Secret, click Save Credentials, and hit Login with Google Business Profile.
Execute Real Endpoints via Swagger UI
Once authenticated, click Open Swagger API Docs. You can immediately call:
GET /accounts– List all managed merchant business accounts.GET /locations– Paginate through all active store locations.GET /reviews– Read customer reviews, ratings, and comment replies.POST /performance/daily-metrics– Query daily impressions and customer interaction time series.POST /performance/search-keywords– Inspect local search query impressions for organic ranking audits.
The Engine Under the Hood: @vitabletech/gbp-sdk
The playground is built on top of our official open-source package, @vitabletech/gbp-sdk (v1.3.0). While the playground lets you experiment visually in the browser, the SDK powers your actual backend microservices, cron jobs, and webhooks.
1. Installing the SDK
npm install @vitabletech/gbp-sdk
# or using pnpm
pnpm add @vitabletech/gbp-sdk2. Fetching Multi-Location Accounts with Auto-Pagination
Instead of manually tracking pageToken query parameters and chaining promises, call listAll():
import { GBPClient } from '@vitabletech/gbp-sdk';
const client = new GBPClient({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
redirectUri: 'https://your-domain.com/auth/callback',
});
// Pass the refresh token retrieved during OAuth
client.setRefreshToken(process.env.STORED_REFRESH_TOKEN!);
async function syncBusinessLocations() {
// 1. Fetch all accounts attached to the authenticated profile
const accounts = await client.accounts.list();
const primaryAccount = accounts[0];
// 2. Fetch EVERY location with automatic recursive pagination
const allLocations = await client.locations.listAll({
parent: primaryAccount.name,
readMask: 'name,title,storeCode,storefrontAddress,phoneNumbers,websiteUri',
});
console.log(`Successfully fetched ${allLocations.length} locations across your organization!`);
return allLocations;
}
3. Querying Performance API v1 Metrics (Daily Time-Series & Search Keywords)
The modern Performance API v1 is notorious for its strict date formats and multi-layered request objects. Here is how easy it is with @vitabletech/gbp-sdk:
// Query Daily Metrics (Website clicks, Call button clicks, Directions)
const dailyMetrics = await client.performance.getDailyMetricsTimeSeries({
name: 'locations/1234567890123456789',
dailyMetric: 'BUSINESS_IMPRESSIONS_DESKTOP_MAPS',
dailyRange: {
startDate: { year: 2026, month: 10, day: 1 },
endDate: { year: 2026, month: 10, day: 31 },
},
});
// Query Top Search Keywords driving local discovery
const topKeywords = await client.performance.listSearchKeywordsImpressionsMonthly({
parent: 'locations/1234567890123456789',
monthRange: {
startMonth: { year: 2026, month: 8 },
endMonth: { year: 2026, month: 10 },
},
pageSize: 50,
});
for (const keyword of topKeywords.searchKeywordsCounts || []) {
console.log(`Keyword: "${keyword.searchKeyword}" -> Impressions: ${keyword.insightsValue?.value}`);
}
Comparison: Raw HTTP vs. Standard Library vs. VitableTech
| Feature | Raw Axios / Fetch | Google APIs Official Node | VitableTech Ecosystem |
|---|---|---|---|
| Browser Testing Playground | ❌ None (Must build local server) | ❌ Basic OAuth Playground only | ✅ Full BYOC Swagger Sandbox |
| Token Refresh Logic | ❌ Manual implementation | ⚠️ Basic OAuth2 client | ✅ Concurrency-safe automatic refresh |
| Auto-Pagination (`listAll`) | ❌ Manual cursor tracking | ❌ Not built-in for GBP | ✅ Native `listAll` on all collections |
| Performance API v1 Typing | ❌ Generic `any` | ⚠️ Outdated GMB v4 artifacts | ✅ Strict TypeScript definitions |
| Retry & Exponential Backoff | ❌ Manual | ⚠️ Optional configuration | ✅ Built-in jittered backoff |
How VitableTech Helps Companies Scale Beyond the Playground
Building a prototype in a playground is step one. Taking a Google Business Profile integration into mission-critical production across hundreds or thousands of merchant locations requires robust architectural planning.
Here is how the VitableTech Engineering Team partners with agencies, franchises, and SaaS providers:
Automated AI Review Agents
We engineer custom LLM pipelines that listen to Google review webhooks, analyze customer sentiment, craft brand-compliant, context-aware responses, and automatically post replies through verified GBP endpoints.
Explore Review AI Architecture →Multi-Location Sync & Hours Management
Managing holiday hours, special attributes, and emergency closures across 500+ franchise branches? We develop bi-directional synchronization engines linking internal ERPs, CRMs, or POS systems directly to Google's Business Information API.
Consult on Enterprise Sync →White-Label Reporting Portals
Transform raw Performance API metrics into branded client dashboards. We construct high-speed analytics portals with automated PDF exports, executive KPI summaries, and automated rank tracking alerts.
Build Custom Client Dashboards →Need an Enterprise Google Business Profile Integration?
Stop spending engineering quarters wrestling with Google's API nuances. Partner with VitableTech to deploy scalable, secure, and production-ready local SEO engines.
Frequently Asked Questions (Developer & Agency FAQs)
What is the VitableTech GBP Playground and do I have to pay for it?
The VitableTech GBP Playground is 100% free and open to all developers, technical marketers, and product managers. You bring your own Google Cloud OAuth credentials and execute calls directly against your own accounts with zero fees or tier limits.
Are my Google OAuth credentials or tokens saved on your servers?
No. We maintain a strict zero-retention security policy. Your Client ID, Client Secret, access tokens, and refresh tokens exist purely inside your browser's local session memory. Nothing is ever written to any database, file system, or analytical tracking tool on our servers.
Which Google Cloud APIs must be enabled for full playground functionality?
To unlock all Swagger endpoints, enable the following in your Google Cloud Console:
Google Business Profile Business Information APIBusiness Profile Performance API(for daily time-series & keyword impressions)My Business Account Management APIMy Business Verifications API
How does the playground and SDK handle Google's 60-minute token expiration?
Google access tokens expire after exactly 3600 seconds (1 hour). The underlying @vitabletech/gbp-sdk includes an internal thread-safe token manager that automatically exchanges your refresh token for a brand new access token right before expiration, eliminating interrupted jobs.
Can I deploy @vitabletech/gbp-sdk to serverless platforms (Netlify, AWS Lambda, Cloudflare)?
Yes. The SDK was purposefully built with lightweight, zero-bloat dependencies. It runs smoothly on Node.js 18+, Netlify Serverless Functions, AWS Lambda, Google Cloud Run, and containerized Docker environments.
What is the difference between legacy GMB Insights and Performance API v1?
Google completely deprecated the old reportLocationInsights endpoint. The modern Business Profile Performance API v1 separates engagement metrics into daily time-series counts (calls, website clicks, message conversations, booking clicks) and aggregates search keywords into monthly impression rankings. Our SDK and playground fully support this modern v1 format.
Can VitableTech build a custom multi-location GBP solution for our enterprise?
Yes! That is our core specialty. Whether you need an automated AI review responder, a central multi-brand location sync engine, or a white-label client portal, our team can deliver custom, enterprise-grade software. Contact our engineering team today →
Written by the VitableTech Engineering Team
We are full-stack software engineers, cloud architects, and API specialists. We architect, build, and maintain mission-critical enterprise applications, SaaS platforms, and developer tooling for global clients across the USA, UK, India, and beyond.