DEV Community: Citation Builder

Extracting LocalBusiness Schema (JSON-LD) NAP Data with Plain Node.js

Citation Builder — Fri, 24 Jul 2026 12:09:35 +0000

Every local business page that wants rich results in Google carries a LocalBusiness JSON-LD block: name, phone, address, hours. That makes structured data the most machine-readable source of a business's NAP (Name, Address, Phone) — and the first place to look when you audit whether a business is represented consistently across the web. This is exactly the kind of structured citation data that search engines cross-reference before deciding to trust a listing.

In this post we build a small, dependency-free Node.js pipeline that extracts LocalBusiness schema from any HTML page and diffs the NAP it declares against a canonical record. It is a simplified version of the extraction layer behind a free NAP consistency checker. Every output shown is the real result of running the code.

Step 1: pull the JSON-LD blocks out of the HTML

JSON-LD lives in <script type="application/ld+json"> tags. You do not need a full DOM parser to get at them — the tags cannot nest, so a regex over the raw HTML is fine for this job:

function extractJsonLd(html) {
  const blocks = [];
  const re = /<script[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
  let m;
  while ((m = re.exec(html)) !== null) {
    try {
      blocks.push(JSON.parse(m[1].trim()));
    } catch {
      // real-world JSON-LD is often broken; skip and count it
      blocks.push({ __parseError: true });
    }
  }
  return blocks;
}

The try/catch is not defensive paranoia. In the wild you will hit trailing commas, PHP warnings printed inside the script tag, and template placeholders that never got rendered. A parse failure is itself a finding worth reporting — Google won't read that block either.

Take this sample page — a typical Yoast/Rank-Math-style setup with an @graph plus a second script tag for breadcrumbs:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "WebSite", "name": "Athens Dental Care", "url": "https://example.com" },
    {
      "@type": ["Dentist", "LocalBusiness"],
      "name": "Athens Dental Care",
      "telephone": "+30 210 555 0134",
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "12 Ermou St",
        "addressLocality": "Athens",
        "postalCode": "105 63",
        "addressCountry": "GR"
      }
    }
  ]
}
</script>
<script type="application/ld+json">
{ "@type": "BreadcrumbList", "itemListElement": [] }
</script>

Running extractJsonLd on it finds 2 blocks.

Step 2: flatten `@graph` into a plain node list

Real-world JSON-LD comes in three shapes: a single node, an array of nodes, or a @graph wrapper (what most WordPress SEO plugins emit). Normalize all three into one flat list:

function flattenNodes(block) {
  if (Array.isArray(block)) return block.flatMap(flattenNodes);
  if (block && typeof block === 'object') {
    if (Array.isArray(block['@graph'])) return block['@graph'].flatMap(flattenNodes);
    return [block];
  }
  return [];
}

const nodes = blocks.flatMap(flattenNodes);
// 3 nodes: "WebSite", ["Dentist","LocalBusiness"], "BreadcrumbList"

Step 3: find the business node

Here is the trap that breaks naive implementations: @type can be a string or an array, and hundreds of schema.org subtypes (Dentist, Restaurant, Plumber, HairSalon...) are valid local-business types that may never mention LocalBusiness at all. Checking node['@type'] === 'LocalBusiness' misses most real pages.

function isLocalBusiness(node) {
  const types = [].concat(node['@type'] ?? []);
  if (types.includes('LocalBusiness')) return true;
  // Hundreds of schema.org subtypes (Dentist, Restaurant, Plumber...) never
  // say "LocalBusiness" explicitly — fall back to the shape of the data.
  return Boolean(node.name && node.address && (node.telephone || node.openingHours || node.openingHoursSpecification));
}

const biz = nodes.find(isLocalBusiness);
// picked: ["Dentist","LocalBusiness"] Athens Dental Care

[].concat(x) is a compact way to treat "string or array" uniformly. The shape-based fallback (has a name, an address, and either a phone or opening hours) catches subtypes without maintaining a 400-entry type list.

Step 4: reduce it to a flat NAP record

function toNap(node) {
  const addr = node.address && typeof node.address === 'object' ? node.address : {};
  return {
    name: node.name ?? null,
    phone: node.telephone ?? null,
    street: addr.streetAddress ?? null,
    city: addr.addressLocality ?? null,
    zip: addr.postalCode ?? null,
    country: addr.addressCountry ?? null,
  };
}

For our sample page:

{
  "name": "Athens Dental Care",
  "phone": "+30 210 555 0134",
  "street": "12 Ermou St",
  "city": "Athens",
  "zip": "105 63",
  "country": "GR"
}

Step 5: diff against the canonical record — normalize first

Comparing raw strings produces false alarms everywhere: +30 210 555 0134 vs 00302105550134 is the same phone; 12 Ermou St vs 12 Ermou Street is the same address. Normalize both sides before comparing:

const digits = (s) => (s ?? '').replace(/\D/g, '').replace(/^00/, '');
const squash = (s) => (s ?? '').toLowerCase().normalize('NFKD').replace(/\p{M}/gu, '')
  .replace(/\b(st|street|ave|avenue|rd|road|blvd|suite|ste|unit)\b\.?/g, '')
  .replace(/[^a-z0-9]/g, '');

digits('+30 210 555 0134') === digits('00302105550134'); // both "302105550134"
squash('12 Ermou St') === squash('12 Ermou Street');       // both "12ermou"

digits keeps only numbers and strips the international 00 prefix so E.164 and dialed formats collide into one value. squash lower-cases, folds accents (normalize('NFKD') + stripping combining marks with \p{M}), drops street-type abbreviations, and removes everything non-alphanumeric.

The diff itself is then trivial:

function diffNap(found, canonical) {
  const issues = [];
  if (digits(found.phone) !== digits(canonical.phone)) {
    issues.push(`phone mismatch: "${found.phone}" vs "${canonical.phone}"`);
  }
  if (squash(found.street) !== squash(canonical.street)) {
    issues.push(`street mismatch: "${found.street}" vs "${canonical.street}"`);
  }
  if (squash(found.zip) !== squash(canonical.zip)) {
    issues.push(`zip mismatch: "${found.zip}" vs "${canonical.zip}"`);
  }
  return issues;
}

Against the correct canonical record (00302105550134, 12 Ermou Street, 10563) the sample page produces no issues — the formatting differences are all absorbed by normalization:

diffNap(toNap(biz), canonical);
// []

Against a record with a genuinely different phone and street number it reports exactly the two real problems:

diffNap(toNap(biz), wrong);
// [
//   'phone mismatch: "+30 210 555 0134" vs "+30 210 555 0199"',
//   'street mismatch: "12 Ermou St" vs "14 Ermou Street"'
// ]

That asymmetry is the entire point of the normalization layer: zero false positives on cosmetic differences, loud and specific on real ones.

Where to take it

Feed it live pages with fetch(url).then(r => r.text()) and you have a schema-aware NAP auditor for any list of URLs (your own locations, or every directory listing a business appears on).
Report __parseError blocks — broken JSON-LD is invisible in the browser but costs rich results.
The same normalize-then-compare pattern extends to business names, where fuzzy matching earns its keep; I covered that in a previous post on detecting duplicate listings.

If you'd rather see the production version of this idea, the NAP checker runs this pipeline (plus a few data sources beyond schema) against any business name — free, no signup.

Detecting Duplicate Business Listings with Fuzzy Matching in JavaScript

Citation Builder — Mon, 20 Jul 2026 12:17:52 +0000

When you list a business across dozens of directories, the same company shows up written a dozen different ways: "Joe's Plumbing LLC", "Joe Plumbing", "Joe's Plumbing & Heating". Search engines and AI assistants read those as maybe the same entity, and "maybe" is exactly what you do not want. Detecting these near-duplicates is a fuzzy-string-matching problem, and you can get surprisingly far with a few dozen lines of plain JavaScript.

Here is the approach behind the matching layer of a free NAP consistency checker, with runnable, dependency-free code. Every output below is the actual result of running the snippet.

Step 1: normalize before you compare

Raw string similarity is noise until you strip the parts that carry no identity. For business names that means lower-casing, folding accents, dropping the possessive 's, removing punctuation, and discarding legal suffixes and filler words.

const LEGAL_SUFFIXES = new Set([
  'llc', 'inc', 'incorporated', 'ltd', 'limited', 'co', 'corp',
  'corporation', 'gmbh', 'ltda', 'plc', 'ae', 'oe', 'epe', 'ike',
]);
const NOISE = new Set(['the', 'and', 'of']);

function normalizeName(raw) {
  return raw
    .toLowerCase()
    .normalize('NFKD')
    .replace(/[\u0300-\u036f]/g, '') // strip accents: café -> cafe
    .replace(/['’]s\b/g, '')         // drop possessive 's: joe's -> joe
    .replace(/[^a-z0-9\s]/g, ' ')    // punctuation (incl. &) -> space
    .split(/\s+/)
    .filter((w) => w.length > 1 && !LEGAL_SUFFIXES.has(w) && !NOISE.has(w))
    .join(' ')
    .trim();
}

normalizeName("Joe's Plumbing, LLC"); // "joe plumbing"
normalizeName('The Joe & Sons Co.');   // "joe sons"
normalizeName('Café Böhme GmbH');      // "cafe bohme"

That one function removes most false differences before any scoring happens. Do not skip it: comparing un-normalized strings is where naive dedupe scripts go wrong.

Step 2: score similarity with token set ratio

Levenshtein distance alone breaks on word reordering ("Athens Dental Care" vs "Dental Care Athens" looks very different character by character). The trick popularized by Python's fuzzywuzzy is the token set ratio: treat each name as a set of words and compare the shared tokens against the leftovers. It is word-order independent and length tolerant.

function tokenSetRatio(a, b) {
  const ta = new Set(normalizeName(a).split(' ').filter(Boolean));
  const tb = new Set(normalizeName(b).split(' ').filter(Boolean));
  if (!ta.size || !tb.size) return 0;

  const shared = [...ta].filter((t) => tb.has(t)).length;
  const onlyA = ta.size - shared;
  const onlyB = tb.size - shared;
  const union = ta.size + tb.size - shared;

  const jaccard = shared / union;
  // Penalize each side's unique tokens a little, so a tagline or an added
  // service word lowers the score without killing it.
  const drift = (onlyA + onlyB) / (ta.size + tb.size);
  return Math.round(100 * jaccard * (1 - 0.35 * drift));
}

tokenSetRatio("Athens Dental Care", "Dental Care Athens");   // 100
tokenSetRatio("Joe's Plumbing LLC", "Joe Plumbing");         // 100
tokenSetRatio("Joe's Plumbing", "Joe's Plumbing & Heating"); // 62
tokenSetRatio("Bright Smile Dental", "Bright Star Cafe");    // 15

Set a threshold (I use 85) above which two names are "probably the same business". Everything roughly between 60 and 85 is the interesting zone: real duplicates hiding behind a tagline, a franchise suffix, or a typo, worth a human glance.

Step 3: do the same for the address

Names are only half of NAP (name, address, phone). Addresses have their own normalization: collapse the common abbreviations, then reuse the same ratio.

const STREET_ABBR = {
  street: 'st', avenue: 'ave', boulevard: 'blvd', road: 'rd',
  drive: 'dr', suite: 'ste', apartment: 'apt', floor: 'fl',
};

function normalizeAddress(raw) {
  let s = raw.toLowerCase().replace(/[.,]/g, ' ');
  for (const [long, short] of Object.entries(STREET_ABBR)) {
    s = s.replace(new RegExp(`\\b${long}\\b`, 'g'), short);
  }
  return s.replace(/\s+/g, ' ').trim();
}

function addressMatches(a, b) {
  return tokenSetRatio(normalizeAddress(a), normalizeAddress(b)) >= 80;
}

normalizeAddress("123 Main Street, Suite 4");   // "123 main st ste 4"
addressMatches("123 Main Street", "123 Main St."); // true

Putting it together

A minimal duplicate finder over listings pulled from different directories:

function findDuplicates(listings) {
  const groups = [];
  for (const listing of listings) {
    const hit = groups.find((g) =>
      tokenSetRatio(g[0].name, listing.name) >= 85 &&
      addressMatches(g[0].address, listing.address));
    if (hit) hit.push(listing);
    else groups.push([listing]);
  }
  return groups.filter((g) => g.length > 1); // only the collisions
}

findDuplicates([
  { name: "Joe's Plumbing LLC", address: '123 Main Street' },
  { name: 'Joe Plumbing',       address: '123 Main St.' },
  { name: 'Bright Star Cafe',   address: '9 River Road' },
]);
// => [ [ "Joe's Plumbing LLC", "Joe Plumbing" ] ]

It clusters the same business as it appears across directories while keeping genuinely different ones apart.

Where the simple version stops

This is deliberately dependency-free and good enough to flag most inconsistencies. Two honest limits:

Phonetic misspellings ("Katherine" vs "Catherine") slip through token matching. Add a Double Metaphone pass if that matters for your data.
Real-world address messiness (unit numbers, PO boxes, localized formats across countries) needs a proper geocoder to resolve. Comparing against a structured source like the OpenStreetMap Nominatim API beats string matching once you cross borders.

If you just want to see how consistent a real business's listings are without wiring any of this up, that is what our NAP checker does against live directory data, and there is more on why the inconsistencies matter in this write-up on finding and fixing duplicate listings.

The core idea travels well beyond local SEO: normalize hard, compare as token sets, and treat the 60-to-85 band as the place worth a human look. That heuristic has saved me from a lot of bad dedupe.

Checking local-business NAP consistency in code

Citation Builder — Fri, 03 Jul 2026 12:00:49 +0000

If you have ever done local SEO, you have heard the acronym NAP: Name, Address, Phone. The folklore is that these three fields should be byte-for-byte identical everywhere your business is listed (Google, Yelp, Apple Maps, the long tail of directories), or your local rankings suffer.

"Just compare the strings" is the instinct. Then you actually try it, and every assumption falls apart. This is a writeup of the engineering problems I ran into building a free NAP checker, and how I ended up solving them. No framework, just plain JavaScript and a few HTTP calls.

The core problem: equality is the wrong operator

Here is the same real business as three directories store it:

Joe's Plumbing & Heating, LLC   | 123 N Main St Ste 4   | (415) 555-0199
Joe's Plumbing and Heating      | 123 North Main Street  | +1 415-555-0199
Joeβ€™s Plumbing & Heating LLC    | 123 N. Main St. #4     | 415.555.0199

A human reads those as one business. === reads three different businesses across all three fields. The whole job is closing that gap without being so fuzzy that two genuinely different businesses score as a match. Every field needs its own normalization pipeline before you can compare anything.

Phone is the easy win, so start there

Phone numbers feel messy but they are the most tractable field, because there is a real spec underneath. Strip everything to digits, drop the country code, and compare the national significant number. libphonenumber does this properly, but the 80% version is small:

function normalizePhone(raw, region = "US") {
  const digits = (raw || "").replace(/\D/g, "");
  if (!digits) return null;

  // US/CA: 11 digits starting with 1 -> drop the country code
  let nsn = digits;
  if (region === "US" && nsn.length === 11 && nsn.startsWith("1")) {
    nsn = nsn.slice(1);
  }
  // store last 10 as the comparable key
  return nsn.length >= 10 ? nsn.slice(-10) : nsn;
}

normalizePhone("(415) 555-0199");   // "4155550199"
normalizePhone("+1 415-555-0199");  // "4155550199"
normalizePhone("415.555.0199");     // "4155550199"

All three formats above collapse to 4155550199. Phone becomes a clean equality check on a normalized key. The one trap: extensions. 555-0199 x12 should match 555-0199 on the main number, so compare the leading NSN, not a naive "last 10 digits" that swallows the extension. For anything beyond US/CA, hand it to libphonenumber and trust the region metadata, because national-number length is not universal.

Names: strip the legal suffix, then match tokens

Business names break equality in two predictable ways:

Legal suffixes. LLC, Inc, Ltd, Co, GmbH, Corp, L.L.C. These are noise for matching. One directory keeps them, one drops them, one abbreviates.
Connectors and punctuation. & vs and, smart quotes (β€™ vs '), trailing commas, casing.

So the name pipeline is: lowercase, normalize unicode (β€™ β†’ '), expand/standardize &, strip a known list of legal suffixes, collapse whitespace. Then I don't do a raw string compare. I tokenize and measure token overlap, because word order and a stray extra word shouldn't tank the score:

const LEGAL = /\b(llc|l\.l\.c\.|inc|incorporated|ltd|co|corp|company|gmbh|kg|bv|sa|srl)\b/g;

function normalizeName(s) {
  return (s || "")
    .toLowerCase()
    .normalize("NFKC")
    .replace(/[β€™']/g, "")
    .replace(/&/g, " and ")
    .replace(LEGAL, "")
    .replace(/[^a-z0-9\s]/g, " ")
    .replace(/\s+/g, " ")
    .trim();
}

function tokenScore(a, b) {
  const A = new Set(normalizeName(a).split(" ").filter(Boolean));
  const B = new Set(normalizeName(b).split(" ").filter(Boolean));
  if (!A.size || !B.size) return 0;
  let shared = 0;
  for (const t of A) if (B.has(t)) shared++;
  return shared / Math.max(A.size, B.size); // Jaccard-ish, biased to the longer side
}

"Joe's Plumbing & Heating, LLC" vs "Joe's Plumbing and Heating" now scores 1.0 on shared tokens. Dividing by the longer token set (rather than the union) keeps a directory that bolts on a city name ("... Heating San Francisco") from scoring a perfect match against the clean version.

Addresses: the abbreviation swamp

Addresses are the worst field, and it is worth being honest about why. The variation isn't typos, it's a dictionary of equivalent forms that postal systems treat as identical:

In the wild	Canonical
`St`, `St.`	`Street`
`Ave`, `Av`	`Avenue`
`Blvd`	`Boulevard`
`N`, `N.`	`North`
`Ste`, `#`, `Unit`	(suite designator)
`Hwy`	`Highway`

The fix is an expansion map applied token by token, the same way you normalize the name. 123 N Main St Ste 4 and 123 North Main Street #4 both reduce to 123 north main street 4 and compare cleanly. Keep the map small and US/region-specific; an over-eager map will "correct" things that were never abbreviations.

Why reverse-geocoding lies to you

Here is the subtle one that cost me the most time. Some directories only give you a lat/long, not a clean street string. The tempting move is to reverse-geocode those coordinates back into an address and compare. Don't trust that comparison for a mismatch verdict.

Reverse geocoding snaps a point to the nearest known feature in the geocoder's database. A rooftop pin 12 meters off can resolve to the building next door, a different suite, or the road centerline. So you reverse-geocode 123 Main St and get back 125 Main St, and your checker screams "address mismatch!" when the listing is perfectly fine. The error is in your verification method, not in the data.

The rule I settled on: reverse-geocoded addresses are advisory. If the forward, text-based address agrees, great. If it disagrees, fall back to a coordinate-distance check (are the two points within ~50m?) before ever reporting a mismatch. A mismatch born from snapping is a false positive, and false positives in this tool are worse than gaps, because they send people editing listings that were already correct.

Scoring: per field, not one blob

Early on I concatenated N + A + P and computed one similarity number. Useless. A wrong phone and a wrong suite number are completely different problems, and an aggregate score hides which one you have.

So scoring is field-level. Each directory result returns a per-field verdict, and not_found is explicitly not a failure:

function scoreField(mine, theirs, kind) {
  if (theirs == null) return { status: "not_found" };   // coverage gap, not a mismatch
  const ok =
    kind === "phone" ? normalizePhone(mine) === normalizePhone(theirs)
    : kind === "name" ? tokenScore(mine, theirs) >= 0.8
    : normalizeAddress(mine) === normalizeAddress(theirs);
  return { status: ok ? "match" : "mismatch", theirs };
}

That not_found distinction matters more than it looks. If a directory simply doesn't list you, that is a coverage signal ("go claim this listing"), not a consistency signal ("you have conflicting data"). Folding them together makes a business with thin coverage look like a business with a data integrity problem. They need opposite fixes.

The data sources are the actual hard part

The algorithms above are a weekend. Getting clean field data to compare against, for free, at scale is the part that never ends.

What worked, server-side and free:

OpenStreetMap / Nominatim is the workhorse. Geocode the address, get structured address parts back. Critically, request extratags β€” that is where phone / contact:phone and website live, so you can compare more than just the address. Respect the usage policy: one request per second, a real User-Agent, and cache aggressively.
iBegin and Lacartes gave usable structured listings for US/CA/UK without a login wall.

What did not work, and why it's worth knowing before you waste an afternoon:

Yelp and Yellow Pages: hard 403 to anything from a datacenter IP. Their bot detection assumes residential traffic; your server is not that. Scraping them at scale means a residential proxy budget, which kills "free."
Hotfrog: same datacenter 403 story.
hub.biz: echoed my query back at me instead of returning its own stored record, which is worthless for a consistency check (you'd be comparing the input to itself).
A long tail of directories sit behind Cloudflare challenges or render NAP only after client-side JS, so a plain server fetch sees an empty shell.

The lesson is that "check across all directories" is marketing; "check across the directories that expose structured data to an anonymous server request" is the real, shippable scope. Be upfront about coverage instead of pretending a not_found from a bot-wall means the listing is absent.

Putting it together

The shape that worked:

Normalize the user's own NAP once.
For each reachable source, fetch, extract NAP (incl. extratags), normalize the same way.
Score per field, with match / mismatch / not_found as distinct states.
Treat reverse-geocoded addresses as advisory and gate mismatches behind a distance check.
Report coverage and consistency as two separate things.

I packaged this into a free checker I built if you want to see the normalization behavior on a real business without writing the code. But the genuinely portable lesson is the framing: NAP consistency is a per-field normalization-and-matching problem with a nasty data-acquisition tail, and the single biggest correctness bug is trusting a reverse-geocode to tell you two addresses disagree.

If you build your own, start with phone (real spec, clean wins), get your name and address normalizers right, and spend your remaining time on the data sources, because that is where the project actually lives.

DEV Community: Citation Builder

Extracting LocalBusiness Schema (JSON-LD) NAP Data with Plain Node.js

Step 1: pull the JSON-LD blocks out of the HTML

Step 2: flatten @graph into a plain node list

Step 3: find the business node

Step 4: reduce it to a flat NAP record

Step 5: diff against the canonical record — normalize first

Where to take it

Detecting Duplicate Business Listings with Fuzzy Matching in JavaScript

Step 1: normalize before you compare

Step 2: score similarity with token set ratio

Step 3: do the same for the address

Putting it together

Where the simple version stops

Checking local-business NAP consistency in code

The core problem: equality is the wrong operator

Phone is the easy win, so start there

Names: strip the legal suffix, then match tokens

Addresses: the abbreviation swamp

Why reverse-geocoding lies to you

Scoring: per field, not one blob

The data sources are the actual hard part

Putting it together

Step 2: flatten `@graph` into a plain node list