DEV Community: Hello Nakama

LocalBusiness Schema for Multi-Location Sites: A Practical JSON-LD Pattern

Hello Nakama — Sat, 26 Sep 2026 20:38:55 +0000

For a multi-location site, put one Organization node on the brand level, and one LocalBusiness node (or a more specific subtype) on each location page. Give every node a stable @id, link each location to the brand with parentOrganization, and make sure the address, phone, and hours in the markup match the visible page and the Google Business Profile exactly. That is most of it. The rest is keeping it true.

Here is a pattern that scales from five locations to five hundred.

When should you use LocalBusiness?

Use it on pages that represent a real, physical place customers can visit or that serves a defined area. A store page, a clinic page, a branch page.

Do not use it just because your site talks about local topics. A blog about local marketing is not a local business. Google's local business structured data docs describe the intended use.

The brand node

Put this on the homepage, or in a shared layout, with the same @id everywhere:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Hardware",
  "url": "https://example.com/",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://www.linkedin.com/company/example-hardware"
  ]
}

Only include sameAs profiles that are real and owned by the brand.

The location node

On each location page, one node per location:

{
  "@context": "https://schema.org",
  "@type": "HardwareStore",
  "@id": "https://example.com/locations/austin-north/#location",
  "name": "Example Hardware Austin North",
  "url": "https://example.com/locations/austin-north/",
  "telephone": "+1-512-555-0100",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Example Rd",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78701",
    "addressCountry": "US"
  },
  "geo": { "@type": "GeoCoordinates", "latitude": 30.27, "longitude": -97.74 },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
      "opens": "08:00",
      "closes": "19:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": "Saturday",
      "opens": "09:00",
      "closes": "17:00"
    }
  ],
  "parentOrganization": { "@id": "https://example.com/#organization" }
}

The address and phone above are placeholder examples. Use your real data.

A few notes:

Use the most specific subtype that fits, such as HardwareStore, Dentist, or Restaurant. Fall back to LocalBusiness if nothing fits.
The @id is an identifier, not a link. Keep it stable. Changing it later breaks the connection between nodes.
parentOrganization points to the brand @id, so crawlers see one brand with many locations.

Generate it from the same data as the page

The biggest schema bug on multi-location sites is drift. The page says one set of hours, the markup says another, and the Google profile says a third.

Fix it structurally. Render the visible hours and the JSON-LD from the same location record:

function locationJsonLd(loc, site) {
  return {
    "@context": "https://schema.org",
    "@type": loc.schemaType || "LocalBusiness",
    "@id": `${site.url}locations/${loc.slug}/#location`,
    name: loc.name,
    url: `${site.url}locations/${loc.slug}/`,
    telephone: loc.phoneE164,
    address: {
      "@type": "PostalAddress",
      streetAddress: loc.street,
      addressLocality: loc.city,
      addressRegion: loc.region,
      postalCode: loc.postalCode,
      addressCountry: loc.country
    },
    openingHoursSpecification: loc.hours.map(h => ({
      "@type": "OpeningHoursSpecification",
      dayOfWeek: h.days,
      opens: h.opens,
      closes: h.closes
    })),
    parentOrganization: { "@id": `${site.url}#organization` }
  };
}

If the page template and the schema read from one object, they cannot disagree.

Handle special hours

Holiday hours can go in openingHoursSpecification with validFrom and validThrough. Remove them after the date passes. Stale holiday entries are a common source of wrong answers in search and AI tools.

Common mistakes

Mistake	Why it hurts	Fix
One LocalBusiness on the homepage for all locations	Merges many places into one	One node per location page
Markup hours differ from page	Conflicting signals	Render both from one record
Changing `@id` values	Breaks entity links	Treat `@id` as permanent
Adding reviews you do not show	Against guidelines	Only mark up visible, real content
LocalBusiness on non-location pages	Misleading	Limit to real place pages

Keeping it true at scale

Markup is only as good as the data behind it. If your hours live in five places, the schema will eventually be wrong somewhere. Most multi-location teams either keep a central location database that feeds the site, or use a listing platform that also powers location pages.

Options vary. Yext offers pages driven by its knowledge graph, with enterprise pricing and setup. Synup has store locator and local pages tied to its listings data, though teams with a custom CMS may prefer to keep rendering in their own stack and use its API instead. Uberall offers locator pages for international brands with sales-led onboarding. Or you build it yourself, which gives full control and full maintenance cost.

Validate before shipping

Run pages through Google's Rich Results Test and the Schema Markup Validator. Then spot check that the rendered HTML, not just your source, contains the JSON-LD, especially on client-rendered frameworks.

FAQ

Should every location page have its own LocalBusiness node?
Yes, if each page represents a distinct physical location.

Can I list all locations in one JSON-LD block on a store locator page?
You can reference them, but the full details belong on each location's own page.

Do I need geo coordinates?
They are optional but helpful. Use accurate values from your source data.

Does schema affect Google Business Profile?
No. They are separate. Keep them consistent by hand or through a shared data source.

Syncing Location Data to Google Business Profile Without Breaking It

Hello Nakama — Sat, 26 Sep 2026 20:30:55 +0000

A reliable Google Business Profile sync has four parts: one internal source of truth, field-level updates with an update mask, a read-back step that compares what Google actually shows, and a queue for edits Google rejected or changed. Most broken syncs skip the read-back. They assume a successful API response means the listing is live and correct. It does not.

These are practical notes for engineers building or maintaining a location data pipeline, whether for one brand or many.

What are you actually syncing?

A location record usually includes:

Business name
Address and service area
Primary phone
Regular hours and special hours
Primary and additional categories
Website URL
Attributes (accessibility, payment types, and so on)

Keep these in your own datastore with a stable internal ID per location, and map that ID to the Google location resource name. Never treat Google as the source of truth. It is a destination, and one that can change your data.

Which APIs are involved?

Google split the old My Business API into several APIs. For location data, the main one is the Business Information API, which reads and updates location fields. Account and access work sits in the Account Management API. Access to these APIs is not automatic. You request it through Google, and approval takes time, so plan for that before you build.

Check the current Business Profile APIs documentation for scopes, quotas, and endpoints, because details change.

Update one field at a time with a field mask

Send only what changed. The update call takes an updateMask, and anything outside the mask is left alone.

PATCH https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?updateMask=regularHours
Content-Type: application/json

{
  "regularHours": {
    "periods": [
      { "openDay": "MONDAY", "openTime": { "hours": 9 }, "closeDay": "MONDAY", "closeTime": { "hours": 18 } }
    ]
  }
}

Why this matters:

A full-record overwrite can wipe fields another team or the owner edited directly.
Narrow masks make failures easier to diagnose.
Smaller payloads are easier to audit.

Build your diff logic to emit a mask per changed field, not per record.

Make every write idempotent

Your sync will retry. Networks fail, quotas bite, jobs restart. Design so that sending the same update twice has the same result as sending it once.

A simple pattern:

def sync_location(loc):
    desired = normalize(loc.source_record)
    current = normalize(fetch_google_location(loc.google_name))
    changed = diff_fields(desired, current)
    if not changed:
        return "noop"
    mask = ",".join(changed)
    patch_location(loc.google_name, desired, update_mask=mask)
    enqueue_readback(loc.id, changed, delay_minutes=30)
    return "patched"

Normalization is the unglamorous core. Phone formats, time zones, trailing slashes on URLs, and whitespace in names all create false diffs if you do not normalize both sides the same way.

Read back what Google actually shows

Google can accept an update, then modify or reject it after review. It can also apply edits from users or its own data sources. The Business Information API exposes a way to fetch the Google-updated version of a location, which shows where Google's view differs from what you sent.

Your read-back job should:

Fetch the location after a delay.
Compare each changed field to the desired value.
Mark the change as live, modified, or rejected.
Alert a human for anything not live.

State	Meaning	Action
live	Google shows your value	Close the change
modified	Google shows a different value	Review, possibly contest
rejected	Update did not apply	Check guidelines, fix data, resubmit
pending	Not resolved yet	Recheck later

Without this table in your system, you are guessing.

Detect drift on a schedule

Even when nothing changes on your side, listings drift. A user suggests new hours. Google infers a category. Run a scheduled job that fetches every location, diffs against your source of truth, and reports differences. Decide per field whether to auto-revert or flag for review. Auto-reverting hours is usually safe. Auto-reverting a name change Google made after a guideline review is not.

Respect quotas and back off

The APIs have quotas. Batch work by account, spread writes over time, and use exponential backoff on rate-limit errors. Log every request and response with the internal location ID. When someone asks why a listing changed, the log is your answer.

Build or buy?

If you manage a few locations, a small script plus a spreadsheet may be enough. If you manage many, or need Apple Business Connect, Bing Places, and directories too, building every integration yourself gets expensive to maintain.

Listing platforms with APIs can sit in the middle. Yext has a deep API and data model, but it is enterprise-weight. Synup offers listing APIs and MCP support for LLM tooling, though you still need to design your own source of truth and review flow around it. Uberall provides APIs aimed at larger international brands, with sales-led onboarding. BrightLocal has an API focused more on audits and citation data than on direct profile management. Whichever route you take, keep the read-back and drift checks. A vendor can distribute data, but your system should still verify it.

FAQ

Can I use the API without approval?
No. You need to request access to the Business Profile APIs first.

Should I overwrite user-suggested edits automatically?
Only for fields where you are certain your data is correct, such as hours. Review the rest.

How often should drift checks run?
Daily is common for multi-location brands. Weekly can work for small, stable portfolios.

Does the API update Apple Maps or Bing?
No. Those platforms have their own tools and processes.