Locations

Create, read, update, archive, and verify locations, including their media.

• Readlist_locationsList a client's business locations, newest first. This is the starting point for anything about locations: use it to find a location and its id before calling update_location, or to answer questions like "how many active locations does this client have?", "which locations still need verification?", or "show locations tagged test-pipeline". All filters are optional and are combined together (a location must match all of them); tags, categories, and verification each accept multiple values and match any of them. Returns a page of location summaries plus a running `total` and a `nextCursor` — each summary has the location's name, address (street/city/state/postalCode/country as one joined line plus their own fields), phone, website, store code, category, tags, labels, status, verification, how many saved edits haven't synced to publishers yet (pendingChanges), when it was last published, and its client. To page through more, call again passing the returned `nextCursor`. You don't pass an agency — it comes from your credentials.
• Readlist_location_tagsList the distinct internal tags used across a client's locations (or the whole agency's), sorted alphabetically. Use this to DISCOVER which tags exist before filtering by tag — especially when a user names a subset without saying "tag" (e.g. "all my small-store locations"): call this to check whether "small-store" is one of their tags, then pass it as the `tags` filter to list_locations or the rollup tools. Pass clientId to scope to one client, or omit for the agency-wide tag vocabulary. You don't pass an agency — it comes from your credentials.
• Readget_location_by_idGet the full details of a single location by its id. Use this once you know which location you want — typically after list_locations gives you the id — when the list summary isn't enough. Returns everything about that one location: full business profile (name, address, coordinates, phone(s), website, email, description, tagline), categories (general + per-publisher), hours (regular, special, and more-hours), attributes, services, menu, media, social links, service area, any per-publisher overrides, which publishers it's connected to, its verification status, and when it was last edited. IMPORTANT: for a location migrated from the legacy Synup platform, the `id` on the returned location can differ from the id you passed in — both values work everywhere a location id is accepted (here, update_location, etc.), but they won't be equal as strings, so don't use them to test whether two responses refer to the same location. You don't pass an agency — it comes from your credentials, and a location from another agency is never returned. To look up or find a location id first, use list_locations.
• Writecreate_locationCreate a new business location under a client. You must provide the client's id (find it with list_clients), the location's business name, its two-letter country code (ISO-3166-1 alpha-2), and SOME category — creation fails without one, even though the schema can't mark it required (pass at least categoryName, from list_categories, or publisherCategories.google, from list_publisher_categories). Everything else — address, phone, website, description — is optional but makes for a better listing. Categories come in two kinds: one general category (look it up with list_categories) and per-publisher categories for Google, Facebook, Apple, and Bing (look them up with list_publisher_categories); resolve those first and pass their ids. Once created, the location is automatically queued for submission to online directories and listings. If latitude/longitude are omitted they're derived from the address. Returns the new location's id. You don't pass an agency — it comes from your credentials.
• Writeupdate_locationUpdate an existing location's business details — including its categories (general, per-publisher primary, and additional), Google Business Profile attributes, and its service/product list. Identify the location by its id (the id returned by create_location). Pass only the fields you want to change — anything you omit is left as-is, and passing a field replaces its current value (pass an empty string to clear a text field, or the full new list to replace a list). The country can't be changed after a location is created. If you change the address without also passing coordinates, latitude/longitude are re-derived automatically. By default your change updates the shared details that every publisher inherits; to change a value for specific publishers only (e.g. a different description on Google vs. Facebook), pass applyToPublishers. Use specialHours for one-off date closures/hours (e.g. "mark this Sunday, Aug 2 2026, as closed") — any calendar date works, not just named holidays; use regularHours/moreHours for the standing weekly schedule and extra hour types. Saved changes are automatically queued to sync out to the connected directories and listings. Returns the updated location. You don't pass an agency — it comes from your credentials.
• Readget_location_mediaGet all of a single location's photos, grouped by category (COVER, LOGO, INTERIOR, etc.), plus the logo URL and a count summary. Use this to see what imagery a location currently has before uploading or deleting. Identify the location by its id (from list_locations or create_location). You don't pass an agency — it comes from your credentials.
• Readlist_location_mediaList locations together with their photos, newest first. Same filters as list_locations (client, status, tags, categories, verification, search, created range) — use it to answer things like "which locations have no photos?" or "show the media for this client's active locations". Each row has the location's id, name, logo, full media grouped by category, and a photo count. Returns up to 100 per page with a `nextCursor` for more. You don't pass an agency — it comes from your credentials.
• Writeupload_location_mediaAdd one or more photos to a location, in a given category. Provide each image as a public https URL (we fetch and re-host it) or as base64 bytes. Only images are supported (jpeg, png, gif, webp), max 5 MB each. The LOGO category holds a single logo — uploading to LOGO replaces the current logo. All other categories append. Saved photos are automatically queued to publish to Google. You don't pass an agency — it comes from your credentials.
• Writedelete_location_mediaRemove photos from a location. Pass `urls` to delete specific photos, or `category` to clear a whole category. The logo cannot be deleted — upload a new LOGO image to replace it instead. This removes the photos in the app; note it does not delete them from Google. You don't pass an agency — it comes from your credentials.
• Writearchive_locationSCHEDULE a location to be archived at the end of the current billing period, or restore an archived one. Archiving is deferred, not immediate: the location stays fully active — and still counts against the plan's location limit — until the period the customer has already paid for ends, then it is archived automatically and stops being billed. Because the slot is still occupied, scheduling does NOT free room to add another location until after it archives. Pass archived: false to restore an already-archived location. Use cancel_scheduled_archive to call off a pending archival.
• Writecancel_scheduled_archiveCall off a pending archival, so a location scheduled to archive at the end of the billing period carries on as normal. Only works while the archival is still pending — once the period has ended and the location is actually archived, use archive_location with archived: false to restore it instead.
• Writepublish_locationPush a location's current business details out to its connected Google Business Profile. Use this after update_location if you want to force an immediate sync rather than waiting for the automatic queue. Idempotent — safe to call repeatedly. Returns the push result including any per-field errors Google reported — or, if the location has no Google account connected, `{ skipped: "<reason>" }` instead (nothing to push to, not an error).
• Writebulk_update_locationsApply the same profile patch, publisher overrides, and/or tag add/remove to many locations at once, optionally publishing each to Google afterward. Useful for changes like "add the tag 'holiday-hours-2026' to these 40 locations" or "turn off online ordering everywhere in this client". Capped at 100 locations per call — extra ids beyond that are silently skipped (check the returned `skipped` count). Tags are merged per-location (added/removed against each location's existing tags), never wholesale replaced. Returns a per-location result so partial failures are visible.
• Readget_location_verification_statusCheck a location's Google verification status and available verification methods. Returns connected:false if no Google account is linked. When connected, returns the current verification state (verified / pending / status) and the verification options Google currently offers for this listing (email, phone call, SMS, postcard, etc.) — use these to choose a method for verify_location.
• Writeverify_locationStart or complete Google verification for a location. To start: pass method (from get_location_verification_status's options — e.g. "EMAIL", "PHONE_CALL", "SMS", "ADDRESS") plus whichever of emailAddress/phoneNumber/mailerContact that method needs. To complete a pending verification once the PIN arrives: pass pin instead. The location must already be connected to a Google account (get_location_verification_status returns connected:false otherwise).