GBP Node.js SDKThe Enterprise standard.
Manage locations, menus, attributes, media, reviews, verifications, and quotas with zero-config OAuth, auto-pagination, and strict type safety.
Skip to content
npm install @vitabletech/gbp-sdk🚀 v1.3.0 is LIVE!⚡ Live Playground: gbp-playground.vitabletech.in📊 Performance Metrics v1🔍 Search Keywords Impressions📈 Multi Daily Metrics Time Series✅ Native Verifications API📈 Quotas API Support🔗 Official Chains API🍔 Food Menus Types🤖 Auto-Pagination Built-in!🚀 v1.3.0 is LIVE!⚡ Live Playground: gbp-playground.vitabletech.in📊 Performance Metrics v1🔍 Search Keywords Impressions📈 Multi Daily Metrics Time Series✅ Native Verifications API📈 Quotas API Support🔗 Official Chains API🍔 Food Menus Types🤖 Auto-Pagination Built-in!
🛠️ What you can manage
🏪 Business Profiles
Manage accounts, fetch locations, update business hours, and handle special hours effortlessly across multiple locations.
📊 Performance & Insights
Fetch daily time series, desktop & mobile search/maps impressions, customer search keywords, and breakdowns via Business Profile Performance API v1.
🍔 Services & Menus
Full support for FoodMenus and Service APIs. Build strict TypeScript menus with dietary labels, allergens, and nutritional facts.
⭐ Reviews & Posts
Reply to customer reviews, fetch metrics, and publish local posts, offers, or event updates directly to Google.
✨ Attributes & Amenities
Patch specific location attributes safely. Handle complex amenities like accessibility, dining options, and service flags.
✅ Verifications & Chains
Trigger PIN/SMS verifications programmatically and associate your unverified locations with official global Chains.
📸 Media Uploads
Upload photos and videos directly to Google’s v4 endpoints and manage category tags seamlessly.
💡 Why use this SDK?
Instead of struggling with raw Google APIs, REST endpoints, and manual token refreshing, this SDK provides an enterprise-ready DX:
🔐 Built-in Auth
Zero-config OAuth 2.0 flow with intelligent token refreshing and pluggable file/memory storage. Never write a token refresh loop again.
📑 Auto Pagination
Stop writing boilerplate loops. The SDK automatically traverses nextPageToken to fetch thousands of records across pages instantly.
🛡️ Strict TypeScript Types
100% typed request/response bodies. Catch errors at compile time when writing food menus, attributes, or verification options.
🚦 Smart Rate Limiting
Built-in exponential backoff and automatic retry logic for 429 and 5xx errors, ensuring your enterprise workflows don't crash.
🌐 Unified Services API
We abstract away Google's fragmented APIs into a single unified client supporting locations, verifications, media, and more.
🚀 Quick Start in 3 Steps
Step 1: Install the SDK
Install via your favorite package manager.
bash
npm install @vitabletech/gbp-sdkbash
yarn add @vitabletech/gbp-sdkbash
pnpm add @vitabletech/gbp-sdkStep 2: Configure OAuth
Initialize the client with your Google Cloud credentials.
typescript
import { GBPClient } from '@vitabletech/gbp-sdk';
const client = new GBPClient({
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
redirectUri: 'http://localhost:3000/oauth/callback',
refreshToken: process.env.GOOGLE_REFRESH_TOKEN, // Optional
});Step 3: Call the SDK
You're ready! Start calling any GBP service with automatic token management.
typescript
// Fetch all locations for a specific account (auto-paginated)
const locations = await client.locations.listAll('accounts/1234567890');
// Update a location's attributes
await client.attributes.patchAttributes(locations[0].name, {
attributes: [{ name: 'has_delivery', valueType: 'BOOL', values: [true] }],
});🎉 What's New in v1.3.0
🚀 Performance API Expansion & v1.3.0 Release!
Version 1.3.0 introduces first-class native support for Google's Business Profile Performance API (v1), empowering applications with granular analytics, daily time series, keyword insights, and seamless auto-pagination.
- Performance API v1 (
MetricsService):- Single Metric Daily Time Series: Query
locations.getDailyMetricsTimeSeriesfor precise daily counts (calls, website clicks, direction requests, bookings, food orders, impressions). - Multi Daily Metrics Time Series: Query
locations.fetchMultiDailyMetricsTimeSerieswith support fordailySubEntityTypebreakdowns (day of week, time of day) and flexible camelCase (startDate/endDate) or snake_case dates. - Monthly Search Keywords Impressions: Query
locations.searchkeywords.impressions.monthly.listto discover exactly what search terms users typed to discover your business. - Auto-Pagination & Paginators: Built-in
listAllSearchKeywordsImpressionsMonthly(automatic traversal) andlistSearchKeywordsImpressionsMonthlyPaginator(cursor-based traversal). - Convenient Location Shortcuts: Access all performance methods directly from
client.locations.*without separate service instantiations. - Native Performance Quotas: Dedicated
client.quotas.getPerformance(projectId)helper to check and monitor Performance API quotas.
- Single Metric Daily Time Series: Query
- Verifications API: Trigger phone, SMS, and postcard verifications natively (
mybusinessverifications.googleapis.com). - Quotas API: Programmatically check your API Quotas to avoid hitting rate limits (
serviceusage.googleapis.com). - Chains API: Search global brands and associate your locations with corporate chains effortlessly.
- Location Attributes: Manage location amenities, flags, and attributes easily. Check out our guide on
patchAttributesvsupdateLocationAttributesto choose the best method. - Media Upload Upgrades: The
MediaServicenow fully supports Google's v4 endpoints and allows category updates viapatch(). - Enterprise Ready: Comprehensive Network Whitelist documentation with
businessprofileperformance.googleapis.comadded.