Manage Google Business Profile Locations

Unconnected-site fast path — read first. Read the connection once. Treat NEVER_CONNECTED, NEEDS_RECONNECT, or a single CONNECTION_NOT_FOUND/not-found response from that connection check as the same setup state. Query Wix-only GBP locations once to answer what the site already has, report the result, explain the connect → account selection → unimported-location selection → bulk-create flow, and stop — after that one query the next action is the final response, with no other tool call. Do not call a Google-backed location method, probe for Business Profile accounts, guess an endpoint, or make further API probes or documentation searches until the connection is VALID. A 403 or PERMISSION_DENIED is terminal: the next action is the final response explaining it. Stop without the Wix-only query, documentation search, or any other tool call.

The API is a live view onto Google, not a copy: most calls make a real Google request, with Google’s latency and rate limits. A location’s ID is Google’s opaque location ID and is what identifies it everywhere.

Direct calls for the unconnected-site path

Use these request shapes directly; do not search the API reference before calling them.

Make Get Connection first, then branch before making any other call:

• 403 or PERMISSION_DENIED — stop. The next action is the final response; explain that the current Wix identity cannot inspect the site’s GBP state. Do not query locations, inspect installed apps, search documentation, or try another endpoint.
• NEVER_CONNECTED, NEEDS_RECONNECT, or CONNECTION_NOT_FOUND — make one Query GBP Locations call, report the Wix-stored result, explain the future import steps, and stop. The next action is the final response.
• VALID — proceed with the requested Google-backed flow.

Do not call List GBP Accounts or another Google-backed method until the connection is VALID — account discovery requires the connection, and its request shape is not the locations query. Never guess an endpoint that is not in the table above or in the loaded reference.

Check the connection first

Google-backed methods require a Google connection, established through the Google Business Profile Connection API (see the connect recipe). Before Google-backed work, call Get Connection:

• VALID — proceed.
• NEVER_CONNECTED or NEEDS_RECONNECT — report a setup step, not an error, and offer to run the connect flow. Do not retry location calls until the connection is VALID.

Wix-only reads and deletes still work without active Google credentials: Get GBP Location, Query GBP Locations, Update Location, Delete Location, and Bulk Delete Locations.

Import locations

Importing registers listings that already exist at Google; it never creates one. Each step narrows the next:

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

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

List and query locations

Choose by whether live Google data is needed:

• Just the site’s locations: call Query GBP Locations. 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 live business details: call Query Google Locations (or Get Google Location for one). Each row is hydrated with a live Google fetch. Check each row for googleError — one location failing at Google does not fail the request or break paging, so render it as a per-location problem, not an empty result.

Update the correct side

Wix stores almost nothing; the method name tells you which side a write reaches. Check before calling anything destructive:

• Update Location is not the way to edit a Business Profile — it writes only Wix-stored fields. To change Google-owned data (title, address, hours, categories), call Update Google Location, and confirm with the owner first: the change is publicly visible on Google.
• To create a brand-new Google listing, call Create Google Location after explicit confirmation. Use the API’s reference-data methods (address schema, category and region suggestions) rather than inventing values.
• Google allows roughly 10 profile edits per minute per Business Profile, and the budget is shared across every write method. Pace the profile as a whole and treat a 429 as worth retrying after a delay, not as a rejection.

Remove a location

Decide first whether the owner is removing it from Wix or deleting the real Google listing — these are different operations and one is irreversible. Confirm which they mean before calling anything:

• Un-import from Wix, leave Google alone: call Delete Location, or Bulk Delete Locations for several. Inspect every results[].itemMetadata entry — the bulk call can partially succeed.
• Delete the Google listing as well: call Delete Google Location once per location; there is no bulk Google delete. Require explicit confirmation naming the location — the listing disappears from Google Search and Maps.
• If Delete Google Location returns LOCATION_DB_PERSIST_FAILED, Google deleted the listing but Wix didn’t record it. The error payload carries the location ID; call Delete Location with it to reconcile.

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 suspended, or ownership contested. Call Get Voice of Merchant for the location and act on what Google reports: wait, verify, comply, or resolve the conflict.

Recovery rules

• FAILED_PRECONDITION with CONNECTION_NOT_FOUND: the site has no usable Google connection. Report the setup step and offer the connect flow; do not retry the same call.
• GOOGLE_API_CALL_FAILED: read the carried Google code and description. Some failures are permanent (profile suspended, field not editable) — retrying will not help; explain instead.
• Per-row googleError on hydrating reads: report it per location and continue with the rest of the page.
• Rate limited (429): wait, then retry; interleaved writes share one budget per profile.
• Permission denied: stop after the first 403 or PERMISSION_DENIED. Do not retry with other locations, request shapes, or sites, and do not search for an alternate API or method. Deleting locations requires the site’s GBP_ADMIN role.

The same API also covers reviews and replies, photos and bulk media uploads, attributes, verification, performance insights, and location admins — load the specific public method reference needed before constructing a request so field names, filters, permissions, and errors come from the live contract. Once a connection state or typed error selects a branch above, do not search or browse for an alternate API, method, or request shape.