Google Business Profile API: A Practical Developer's Guide

Beyond the Dashboard Why You Need the GBP API

What the API changes in practice

Why review syncing is often the first real use case

Gaining Access and Initial Project Setup

Set up the Google Cloud project correctly

1. Create or select a projectUse a dedicated project, not a shared sandbox. Save the Project ID and Project Number somewhere obvious because you'll need both during approval and debugging.

2. Enable the Business Profile APIsTurn on the APIs your integration needs. The verified setup path includes the core Business Profile APIs and related management APIs, depending on your use case.

3. Configure the OAuth consent screenChoose the correct user type, fill in app details, developer contacts, and authorized domains. If you're building for production use, don't leave the consent screen half-configured and expect the rest of the process to go smoothly.

4. Create OAuth credentialsGenerate a Client ID and Client Secret. Even if you later use server-side flows, you still want your auth story clean from the start.

Fill out the access request like a reviewer will read it

• State the exact use case“Sync reviews for authorized business locations into our internal reputation dashboard” is stronger than “manage business data.”

• Name who owns the locationsIf you're acting for clients, say that clearly. If you're managing owned locations, say that clearly. Ownership ambiguity causes trouble later.

• Request only the scopes you needAsking for broad permissions without a matching business reason creates friction.

What to submit before you hit send

• Project details readyProject ID, project number, linked Google accounts, and company website.

• Use case phrased in operational termsListing updates, review management, or content publishing.

• Location context includedRelevant location IDs or a clear explanation of the locations you'll manage.

• Consent screen cleaned upNo placeholder branding, no missing developer contacts, no mismatched domains.

Authentication Showdown OAuth 2.0 vs Service Accounts

The practical difference

Authentication method comparison

How to decide without overthinking it

• Users connect their own Google accounts

• You need a consent screen in-product

• Your app acts on behalf of different businesses

• A scheduled worker runs the sync

• Your team controls the environment

• The same authorized account handles the locations repeatedly

What usually works best

Pulling Google Reviews A Practical Code Walkthrough

Start by discovering accounts and locations

import fetch from "node-fetch";

const ACCESS_TOKEN = process.env.GBP_ACCESS_TOKEN;

async function gbpRequest(url, options = {}) {
  const res = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      "Content-Type": "application/json",
      ...(options.headers || {})
    }
  });

  if (!res.ok) {
    const text = await res.text();
    throw new Error(`GBP request failed: ${res.status} ${text}`);
  }

  return res.json();
}

async function listAccounts() {
  const url = "https://mybusiness.googleapis.com/v4/accounts";
  return gbpRequest(url);
}

async function listLocations(accountName) {
  const url = `https://mybusinessbusinessinformation.googleapis.com/v1/${accountName}/locations`;
  return gbpRequest(url);
}

async function main() {
  const accounts = await listAccounts();
  console.log(JSON.stringify(accounts, null, 2));

  // Pick the correct account, then list locations
  const accountName = accounts.accounts?.[0]?.name; // example: accounts/123456789
  if (!accountName) throw new Error("No GBP accounts found");

  const locations = await listLocations(accountName);
  console.log(JSON.stringify(locations, null, 2));
}

main().catch(console.error);

Fetch every review, not just the first page

import fetch from "node-fetch";

const ACCESS_TOKEN = process.env.GBP_ACCESS_TOKEN;
const ACCOUNT_ID = process.env.GBP_ACCOUNT_ID;
const LOCATION_ID = process.env.GBP_LOCATION_ID;

async function gbpRequest(url, options = {}) {
  const res = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      "Content-Type": "application/json",
      ...(options.headers || {})
    }
  });

  if (!res.ok) {
    const text = await res.text();
    throw new Error(`GBP request failed: ${res.status} ${text}`);
  }

  return res.json();
}

async function listAllReviews(accountId, locationId) {
  let reviews = [];
  let pageToken = null;

  do {
    const params = new URLSearchParams();
    params.set("pageSize", "100");
    if (pageToken) params.set("pageToken", pageToken);

    const url = `https://mybusiness.googleapis.com/v4/accounts/${accountId}/locations/${locationId}/reviews?${params.toString()}`;
    const data = await gbpRequest(url);

    reviews = reviews.concat(data.reviews || []);
    pageToken = data.nextPageToken || null;
  } while (pageToken);

  return reviews;
}

async function main() {
  const reviews = await listAllReviews(ACCOUNT_ID, LOCATION_ID);

  const normalized = reviews.map((r) => ({
    reviewId: r.reviewId,
    comment: r.comment || "",
    reviewer: r.reviewer?.displayName || "Anonymous",
    starRating: r.starRating,
    createTime: r.createTime,
    reply: r.reviewReply?.comment || null,
    replyTime: r.reviewReply?.updateTime || null,
  }));

  console.log(JSON.stringify(normalized, null, 2));
}

main().catch(console.error);

The fields worth storing

• reviewId as your external unique key

• comment for display and moderation

• reviewer.displayName for attribution

• starRating for filtering and UI

• createTime for ordering and incremental sync logic

• reviewReply if your product needs response visibility

Replying to a review

async function replyToReview(locationId, reviewId, comment) {
  const url = `https://mybusiness.googleapis.com/v4/locations/${locationId}/reviews/${reviewId}/reply`;
  return gbpRequest(url, {
    method: "PUT",
    body: JSON.stringify({ comment })
  });
}

Building a Real-World Review Sync Feature

A simple schema that stays stable

The sync loop that holds up in production

1. Fetch authorized locations from your mapping table.

2. Pull all pages of reviews for each location.

3. Upsert on external_review_id.

4. Update reply fields if Google shows a newer reply state.

5. Record sync status per location.

Scheduling and display

Navigating Errors Quotas and Rejection

Access rejection is more common than many guides admit

• Tighten the use caseBe explicit about whose locations you manage and under what authorization.

• Avoid scope inflationRequesting more than your use case needs invites scrutiny.

• Align the business model statementIf your app manages client location data, say that plainly and consistently across the form, website, and consent configuration.

Handle quotas and transient failures like infrastructure, not exceptions

async function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function withRetry(fn, maxAttempts = 3) {
  let attempt = 0;

  while (attempt < maxAttempts) {
    try {
      return await fn();
    } catch (err) {
      attempt += 1;
      const message = String(err.message || "");

      const retryable =
        message.includes("429") ||
        message.includes("500") ||
        message.includes("502") ||
        message.includes("503") ||
        message.includes("504");

      if (!retryable || attempt >= maxAttempts) {
        throw err;
      }

      const backoff = Math.floor((Math.random() + 1) * 500 * attempt);
      await sleep(backoff);
    }
  }
}

Diagnose permission problems before you blame the endpoint

• Account-location relationshipConfirm the location belongs to the account you're querying.

• Authorized actorMake sure the token represents the correct approved identity.

• Environment driftTeams often test with one Google account and deploy with another.

• Resource namingA malformed account or location path can look like an auth error.