# About the Google Business Profile Locations API

The Locations API manages a site's Google Business Profile locations: the entries that decide how a
business appears on Google Search and Google Maps. Use it to import locations from a Google account,
read and update their details, reply to reviews, manage photos, run verification, and read
performance insights.

The API is a live view onto Google, not a copy of it. Google owns the business data (name, address,
opening hours, photos, reviews, attributes, insights) and Wix fetches it per request and passes it
through. Wix stores only what it needs to keep locations addressable: Google's opaque location and
account IDs, and a service-area postal address where one applies.

## Before you begin

Read this section first. Most of it changes how you structure your integration, not just how you call
a method.

- **Google-backed methods and imports require a connection, and they report a missing one two
  different ways.** Establish the connection with the Google Business Profile Connection API first,
  and treat a missing connection as a setup step rather than an error to retry.
  - **The import methods fail outright.** `ListGbpAccounts` and `ListUnimportedLocations` return
    `FAILED_PRECONDITION` with `CONNECTION_NOT_FOUND`, and `BulkCreateLocations` rejects the whole
    request before processing any item.
  - **The hydrating reads succeed with per-location errors.** `QueryGoogleLocations` and
    `GetGoogleLocation` still return their rows and paging; the missing credential lands on each row
    as `googleError` instead. So check `googleError` per row rather than relying on the call to fail.

  Wix-only methods remain available without active Google credentials: `GetGBPLocation`,
  `QueryGBPLocations`, `UpdateLocation`, `DeleteLocation`, and `BulkDeleteLocations`.
- **A site has one connected Google account, which may span several Business Profile accounts.** A
  single Google login can hold multiple Business Profile accounts ("location groups"), so
  `account_id` appears throughout and a site's locations can come from more than one of them.
- **A location's ID is Google's ID.** `GBPLocation.id` is Google's opaque location identifier, not a
  Wix-generated one. It is immutable and it is what you use everywhere.
- **Locations must be imported before you can work with them.** `CreateLocation` registers a listing
  that already exists at Google; it does not create one. `CreateGoogleLocation` is the method that
  creates a new listing. See the import flow below, and the table showing which methods reach Google.
- **Almost nothing here is stored by Wix, so almost nothing is retryable-cheap.** Most calls make a
  live Google API request. Expect Google's latency and Google's rate limits, and don't build tight
  polling loops over these methods.
- **Google failures reach you in one of two shapes, and they carry different detail.**
  - **Write and import paths fail the call** with `GOOGLE_API_CALL_FAILED`, carrying Google's code,
    description and HTTP status.
  - **Hydrating reads never fail the call.** `QueryGoogleLocations` and `GetGoogleLocation` attach the
    problem to the affected row as `googleError`, and separately `voiceOfMerchantError`, so a single
    bad location doesn't cost you the page or break the cursor. Google's raw response body is not
    forwarded on this path.

  Either way, some failures are permanent (the profile is suspended, the field is not editable) and
  retrying will not help. Read the error before deciding.
- **`UpdateLocation` does not write to Google.** Despite the name, it only updates Wix-stored fields:
  `service_area_postal_address`, and `feed_entity_id` on its first write. To change Google-owned data
  (title, address, hours, categories), call `UpdateGoogleLocation`.
- **Verification for service-area businesses needs an address saved first.** Call `UpdateLocation`
  with `field_mask = "service_area_postal_address"` before `GetVerificationOptions`, or Google rejects
  the request.
- **Business Profile posts are not part of this API.** Neither are Business Profile accounts
  themselves. You can list them, but not create or modify them.

## What the API provides

With the Locations API, your app can:

- **Import and manage locations**: list the Business Profile accounts reachable from the site's
  connection, discover locations not yet imported, and import them individually or in bulk.
- **Read locations two ways**: `QueryGBPLocations` returns Wix-stored rows only and is the fast,
  cheap path; `QueryGoogleLocations` returns the same rows hydrated with live Google data in one
  round-trip.
- **Update location details**: write through to the Business Profile, or save a service-area address
  on the Wix side.
- **Manage reviews**: list reviews, publish a reply, delete a reply.
- **Manage photos and media**: list, add, and remove media on a location one at a time, or
  queue a whole gallery with `BulkCreateMediaUploads` and poll `ListMediaUploads` until it
  drains. Google accepts about 10 edits per minute per profile, so the queue exists to pace a
  large save for you.
- **Read and write attributes**: read a location's attributes and the metadata describing which
  attributes its category supports, then update them.
- **Run verification**: fetch the available verification methods, start verification, and complete it
  with the PIN Google issues.
- **Check profile health**: read Google's Voice of Merchant state to find out whether a profile is
  live, needs verification, or has an ownership conflict.
- **Read performance data**: location insights and search-keyword impressions.
- **Manage access**: list a location's admins and invite new ones.
- **Look up reference data**: the address schema for a country, and suggestions for regions and
  establishments when creating a location.

## Import locations

Importing is a three-step discovery flow. Each step narrows what the next one needs.

1. **`ListGbpAccounts`**: the Business Profile accounts reachable from the site's connection. Use it
   to let the site owner choose which account to import from.
2. **`ListUnimportedLocations`** with that `account_id`: the locations under that account that this
   site has not imported yet. Wix computes this as the difference between Google's list and the
   site's own rows, so already-imported locations don't reappear.
3. **`BulkCreateLocations`**: import the chosen locations in one call. Per-item failures are reported
   in `results[].itemMetadata.error`; the request as a whole doesn't abort because one item failed.

## Which side does each method affect?

The `*Google*` methods are the ones that reach Google. Everything else touches only Wix storage,
including some names that read as though they wouldn't. Check this table before calling anything
destructive.

| Method | Wix row | Google listing |
|---|---|---|
| `CreateLocation`, `BulkCreateLocations` | created | untouched (imports an existing listing) |
| `CreateGoogleLocation` | created | **created** |
| `UpdateLocation` | updated | untouched (`service_area_postal_address`, `feed_entity_id`) |
| `UpdateGoogleLocation` | untouched | **updated** |
| `DeleteLocation` | deleted | untouched (recovery path for a listing that's already gone) |
| `DeleteGoogleLocation` | deleted | **deleted** |
| `BulkDeleteLocations` | deleted | untouched (bulk form of `DeleteLocation`) |

Three traps in that table:

- **There is no bulk Google delete.** `BulkDeleteLocations` removes only Wix rows. To delete several
  Google listings too, call `DeleteGoogleLocation` once per location.
- **`UpdateLocation` is not the way to edit a Business Profile.** It writes only the two Wix-stored
  fields above. Masking a Google-owned field into it will not reach Google. Use
  `UpdateGoogleLocation`.
- **`DeleteLocation` is a reconciliation tool, not the normal delete.** Its purpose is cleaning up a
  Wix row whose Google listing is already gone or unreachable, for example after
  `DeleteGoogleLocation` returned `LOCATION_DB_PERSIST_FAILED`, meaning Google succeeded but Wix
  didn't record it.

`BulkDeleteLocations` can partially succeed. An OK response does not mean every row was deleted;
inspect every `results[].itemMetadata` entry and handle its error before treating the batch as
complete.

Deleting a location requires `GBP_ADMIN`.

## Personal data

Business Profile data is business information, but two areas carry personal data and should be
handled accordingly:

- **`service_area_postal_address`** is the one field Wix stores that can be personal data. Service-area
  businesses (trades, mobile services, anyone without a storefront) are frequently run from a home
  address, so this is often a residential address. Wix stores it solely to supply Google's verification
  flow with the `context` it requires; it is not published to the Business Profile and it is not a copy
  of the Google-owned address. Every field of it is marked as personal data on the wire. Don't log it,
  don't display it beyond the flow that collects it, and don't retain your own copy.
- **Search keywords** returned by `ListSearchKeywordImpressions` are the terms real people typed into
  Google. The contract marks `searchKeyword` as personal data for exactly that reason: a search term
  can contain a name, an address, or a phone number. Don't log them raw and don't republish them.
- **Admin email addresses.** `InviteAdminToLocation` takes an email, marked as personal data on the
  wire, and `GetLocationAdmins` returns the email or account name of each existing manager.
- **Reviews and phone numbers** pass through from Google and contain reviewer names, review text, and
  business contact numbers.

## Terminology

- **Google Business Profile (GBP)**: Google's product for managing how a business appears on Search
  and Maps.
- **GBPLocation**: A location imported into a Wix site. Identified by Google's opaque location ID;
  holds the Wix-side identifiers and dates, not the business data.
- **Business Profile account** (`account_id`): Google's container for locations, also called a
  location group. One Google login can reach several.
- **Import**: Creating the Wix-side row that makes an existing Google location addressable from Wix.
  It never creates a location at Google.
- **Service-area business**: A business that serves customers at their location rather than at a
  storefront. These use `service_area_postal_address` for verification.
- **Verification**: Google's process for confirming that whoever manages a profile is entitled to.
  Until it completes, a profile may not appear publicly.
- **Voice of Merchant**: Google's summary of whether a profile is live and authoritative, and what to
  do if it isn't.

@sdk_package_setup

# Locations API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It
provides a useful starting point as you plan your implementation.

> **Prerequisite:** every flow assumes the site already has a Google connection, established through
> the Google Business Profile Connection API. Without one, the first connection-dependent call fails
> with `FAILED_PRECONDITION` and `CONNECTION_NOT_FOUND`.

## Import a site's locations

The site owner has just connected their Google account and you want their locations available in Wix.

1. Call **List GBP Accounts**. One Google login can hold several Business Profile accounts, so present
   the list and let the owner pick. Don't assume the first one.
2. Call **List Unimported Locations** with the chosen `accountId`. This returns only what the site
   hasn't imported yet, so re-running the flow won't offer duplicates.
3. Let the owner select which of those to import.
4. Call **Bulk Create Locations** with the selected locations, supplying `id` and `accountId` on each.
5. Inspect `results[].itemMetadata.error`. The call reports per-item failures instead of aborting, so a
   `200` does not mean every location imported.

Repeat steps 2 to 5 per account if the owner wants locations from more than one.

## List locations for a dashboard

Which method to use depends on whether you need Google's business data.

- **Just the site's locations**: call **Query GBPLocations**. It reads Wix-stored rows only: fast,
  no Google round-trip, no Google rate limit. Use it for counts, ID lookups, and anything driven by
  `id`, `googleLocationId`, or `accountId`.
- **Locations with their live details**: call **Query Google Locations**. Same rows, each hydrated
  with a live Google fetch, in one round-trip instead of N.

With Query Google Locations, check each row for a `googleError`. A single location failing at Google
does not fail the request and does not break paging. The page comes back with that row's error
attached, so render it as a per-location problem rather than an empty dashboard.

## Verify a service-area business

Service-area businesses (trades, mobile services, anything without a storefront) need an address on
file before Google will offer verification methods, because Google uses it as the verification
`context`.

1. Collect the service-area address from the site owner.
2. Call **Update Location** with `location.id` set to the location you're verifying, the address in
   `location.serviceAreaPostalAddress`, and `fieldMask = "service_area_postal_address"`. The ID is what
   identifies the row to patch; without it there is nothing to update. This is a Wix-side write; it
   does not touch the Business Profile.
3. Call **Get Verification Options** for that `locationId`. Skipping step 2, or saving an address
   Google cannot resolve, makes Google reject this, surfaced as `INVALID_VERIFICATION_ADDRESS`.
   Prompt the owner to correct the address and retry.
4. Present the returned methods and let the owner choose one.
5. Call **Start Verification** with the chosen method. Google sends a PIN by postcard, phone, or email,
   and the response returns `pendingVerificationId`. **Persist it**: a postcard takes days to arrive,
   so it has to survive the session, and step 6 is impossible without it.
6. Call **Complete Verification** with `locationId`, `pendingVerificationId` and `pin` (all three are
   required), then handle each typed outcome:
   - `VERIFICATION_PIN_INVALID`: prompt the owner to check and re-enter the PIN for the same pending
     verification. Do not request a new PIN automatically for a typing mistake.
   - `VERIFICATION_PIN_EXPIRED`: the PIN is no longer usable; restart from step 5 to request a new
     one.
   - `VERIFICATION_EXPIRED`: Google no longer recognizes the pending verification; restart from
     step 5 to create a new one.

Treat that address as personal data throughout: for a service-area business it's usually the owner's
home. Collect it for this flow, don't log it, and don't keep your own copy.

For a storefront business, skip steps 1 and 2 and start at **Get Verification Options**.

## Check whether a profile is actually live

A location existing in Wix does not mean it appears on Google. Verification can be pending, the
profile can be suspended, or someone else can be claiming ownership.

1. Call **Get Voice of Merchant** for the location.
2. Act on what Google reports: wait, verify, comply, or resolve an ownership conflict. If it says
   verify, run the verification flow above.

Surface this on a dashboard rather than only on failure. It's the difference between "your location is
set up" and "your location is set up but nobody on Google can see it".

## Reply to new reviews

1. Call **List Reviews** for the location, sorted and paged as needed.
2. For each review needing a response, call **Put Review Reply**. A location has one reply per review,
   so calling it again replaces the existing reply.
3. Call **Delete Review Reply** to withdraw one.

Reviews come straight from Google and contain reviewer names and free text. Handle them as personal
data.

## Manage photos

There are two ways to change a location's photos, and which one you want depends
on how many changes you're making.

### One photo at a time

1. Call **List Media** for the location.
2. Call **Create Media** to add a photo, or **Delete Media** to remove one.

These write to the Business Profile immediately and return the outcome. There's
no draft state. They don't pace themselves, so use them for single changes: a
burst returns `429`.

### Many photos at once

Google accepts only about 10 edits per minute per Business Profile, so a site
owner saving a full gallery can't be served by immediate writes. Queue the
changes instead and let them apply in the background.

1. Call **Bulk Create Media Uploads** with everything to add or remove. It
   returns in well under a second without calling Google. One call has to be
   either all additions or all removals, so send two if you need both.
2. Poll **List Media Uploads** to follow progress. Read the response as a whole:

   | What comes back | What it means |
   | --- | --- |
   | Anything `PENDING` or `UPLOADING` | Still working. Don't report results yet. |
   | Only `FAILED` items | Finished, and those items didn't make it. |
   | Nothing | Nothing is outstanding for this location. |

3. Show the failures, if any. Call **Dismiss Media Upload Failures** when the
   site owner acknowledges them.

There's no completion callback, so polling is the only way to know. Expect a
large set to take a while: the queue applies a few changes a minute per
location, so 52 photos take on the order of ten minutes to appear in full.

### An empty queue is not proof of success

A change that succeeds is removed from the queue, and so is a failure that's been
cleared. The two look identical afterwards, so an empty response tells you the
queue is empty and nothing more. Confirm against **List Media** rather than
inferring success.

This matters most when more than one app manages the same location. Queuing
clears every failure for that location, whoever queued it, so one app submitting
a change discards failures the other hasn't read yet. Read failures before
queuing again, and don't treat an empty queue as proof your own submission
worked.

### Showing the gallery mid-flight

While the queue is still working, Google's list lags behind what the site owner
asked for in both directions. Count only changes still on their way, because a
`FAILED` addition never reached Google:

```
gallery = Google's media list
        + additions still PENDING or UPLOADING
        - removals still PENDING or UPLOADING
```

### The rate limit is shared

The same budget of roughly 10 edits per minute covers every write to the
profile, not just photos. **Update Google Location** and **Update Location
Attributes** draw on it too, so interleaving those with photo changes brings the
`429` closer. Pace the profile as a whole rather than each method separately, and
treat a `429` as worth retrying after a delay rather than as a rejection.

## Report on performance

- **Get Location Insights**: how a location performed.
- **List Search Keyword Impressions**: the search terms that surfaced it.

Both hit Google live and are subject to Google's rate limits and data-freshness rules. Cache results
on your side for dashboards rather than calling per page view.

## Remove a location

Decide first whether you are removing it from Wix or deleting the customer's Google listing. These are
different operations and one is not reversible.

- **Un-import from Wix, leave Google alone**: call **Delete Location**, or **Bulk Delete Locations**
  for several Wix rows at once.
- **Delete the Google listing as well**: call **Delete Google Location** once per location. There is
  no bulk Google delete.

Both require `GBP_ADMIN`.

**Bulk Delete Locations** can partially succeed. An OK response does not mean every row was deleted;
inspect every `results[].itemMetadata` entry and handle its error before treating the batch as
complete.

If **Delete Google Location** returns `LOCATION_DB_PERSIST_FAILED`, Google deleted the listing but Wix
didn't record it, leaving a row pointing at nothing. The error payload carries the location ID; call
**Delete Location** with it to reconcile.

Coding Examples

Overview

Sled Tests

Go Headless

Extend Websites with SDK

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

GraphQL (Alpha)

Get Voice Of Merchant