DEV Community: Citation Builder

Ranking a Two-Dimensional Catalog With One SQL Expression

Citation Builder — Thu, 03 Sep 2026 11:21:53 +0000

Every marketplace, catalog or directory app eventually hits the same question: given two independent dimensions, which rows do I show first? For us the dimensions are country and industry, and the rows are 1,300+ local business directories. A plumber in Munich and a law firm in Toronto need overlapping-but-different lists out of the same table.

The naive answers are all bad. Two dimensions of relevance is exactly the shape where "just add a WHERE clause" produces empty results and "just order by popularity" produces a list that ignores the user.

This is the scoring expression we landed on, why each piece is there, and the two bugs that cost us the most time.

The data model

Three tables. One catalog, two mapping tables:

directories(id, name, url, domain_rating, is_global, active, ...)
directory_countries(directory_id, country_code, rank)   -- rank within that country
directory_industries(directory_id, industry_slug, rank) -- rank within that vertical

A row can be mapped to many countries, many industries, both, or neither. is_global marks the handful that are relevant everywhere (Foursquare, OpenStreetMap and friends). Each mapping carries its own rank, curated per dimension: rank 10 in Germany says nothing about rank in Japan.

The query takes (p_country, p_industry) and must return every relevant row, best first, with p_industry optional.

Attempt 1: the inner join that eats your catalog

-- do not do this
select d.* from directories d
join directory_countries dc on dc.directory_id = d.id and dc.country_code = $1
join directory_industries di on di.directory_id = d.id and di.industry_slug = $2;

This returns only rows mapped to both, which in a sparse catalog is close to nothing. Worse, it silently drops the global anchors that every user needs, because a genuinely worldwide directory is often mapped to no single country at all.

Sparse many-to-many data punishes inner joins. The mappings are the evidence, not the filter.

Attempt 2: LEFT JOIN, and let the score decide

select d.id, d.name, d.domain_rating, dc.rank as country_rank, di.rank as industry_rank
from directories d
left join directory_countries  dc on dc.directory_id = d.id and dc.country_code  = $1
left join directory_industries di on di.directory_id = d.id and di.industry_slug = $2
where d.active
  and (d.is_global or dc.country_code is not null or di.industry_slug is not null);

Two things matter here.

The join predicate does the filtering, not the WHERE. The and dc.country_code = $1 sits in the ON clause, so non-matching rows survive with NULL mapping columns. Move that condition to WHERE and you have silently rewritten your LEFT JOIN into an INNER JOIN. It is the most common bug in this shape of query, and it fails quietly: you get a shorter list, not an error.

The WHERE clause is the relevance floor. A row qualifies if it is global, or mapped to this country, or mapped to this industry. Everything else is noise for this user, however strong its authority score.

The scoring expression

Now ordering. What we want, in plain language:

Directories curated for this country come first, because local search is local.
Global anchors sit alongside them when no industry is selected.
Industry-only matches come next.
Everything else trails.
Within a tier, use the curated rank; break ties by authority.

That is a tier plus an offset, which is one arithmetic expression:

(
  case
    when dc.country_code is not null then 0     -- mapped to this country
    when d.is_global and di.industry_slug is null then 0
    when di.industry_slug is not null then 1000 -- industry-only match
    else 2000                                   -- global, but an industry was asked for
  end
  + least(
      coalesce(di.rank, 999),
      coalesce(dc.rank, 999),
      case when d.is_global then 60 else 999 end
    )
)::int as relevance

The tier constants are spaced by 1000 while the offset is bounded by 999, so a tier can never leak into the one below it. That is the whole trick: reserve a numeric range per tier wider than any possible in-tier score. No window functions, no subqueries, no application-side merging.

least() over the three ranks means a row is placed by its strongest claim to relevance. A directory ranked 8 in Germany and 400 in "restaurants" is treated as an 8, because for this user its German relevance is the reason it appears at all.

The case when d.is_global then 60 is a synthetic rank: global anchors have no curated per-country rank, but they are not unranked either. Sixty places them below a country's top-tier native directories and above its long tail, which is exactly where they belong.

The COALESCE sentinel, and its trap

coalesce(di.rank, 999) looks harmless. It is, right up until someone curates a rank of 1000 and it sorts above an unranked row. Sentinels are a contract: pick a value outside the legal range and enforce that range at write time, or use 999999 and stop worrying. We kept 999 and added a check constraint. Do one or the other; do not leave it implicit.

Ordering, including the boolean

order by relevance asc,
         d.domain_rating desc nulls last,
         (d.recipe_status in ('verified','draft')) desc,
         d.name;

nulls last is not optional. In Postgres, NULL sorts first in DESC order, so without it every directory whose authority score we do not have would outrank every directory we scored. Our catalog holds a rating for a minority of rows, so this one clause was the difference between a credible list and a nonsense list.

The third key sorts a boolean: rows we can actually submit to automatically win the tie against rows a human would have to do by hand. Postgres orders false < true, so desc puts true first.

Two bugs worth stealing

Bug one: the disappearing catalog. Moving a join predicate from ON to WHERE turned the LEFT JOINs into inner joins. Every market with a thin native layer went from roughly thirty rows to a handful, and because a shorter list still looks like a list, it survived a review. The test that catches it is not "does the query return rows" but "does it return the global anchors for a country with zero native mappings".

Bug two: NULL-first ordering. Described above. Also silent, also plausible-looking. Both bugs share a signature: wrong output that is well-formed. Write the assertion against a known-sparse input, not the happy path.

Does the ranking hold up?

We measured the resulting lists across the whole catalog, and the honest finding was that most verticals are much thinner than the industry's "500 citations!" marketing suggests: per-category directory counts run from about 95 down to about 32, and ten of 45 categories have no category-specific platform at all. The wider 2026 data study covers method and distribution.

That matters for ranking design: when the true relevant set is a few dozen rows, precision at the top of the list is everything, and a fancy ML re-ranker is not the missing piece. A curated rank plus a tier offset gets you most of the way.

When not to build this

If you need the ranked list for one specific business rather than a general catalog, the build-versus-buy line is short: the query is a weekend, the curation behind those rank columns is the years. That is the actual product. We wrote up how citation building works end to end for the non-SQL version of the same problem, and there is a comparison of the commercial tools if you would rather not own the data at all.

Takeaways

Two-dimensional relevance wants LEFT JOINs plus a score, not a compound WHERE.
Encode tiers as spaced integer bands wider than any in-tier offset.
least(coalesce(...)) places a row by its strongest claim.
nulls last on any partially-populated DESC key, always.
Test against sparse input, because this whole class of bug returns a plausible wrong answer instead of an error.

The Google Map Pack Is a Database, Not a Search Result

Citation Builder — Fri, 28 Aug 2026 12:10:32 +0000

The Google map pack (the block of three local businesses with a map) is not ranked like the ten blue links below it. Organic results rank documents: pages, scored on content and links. The map pack ranks entities: business records, scored on whether Google trusts the data in the record. Once you internalize that, "why doesn't my client show up in the pack?" stops being an SEO mystery and becomes a debugging problem, and debugging problems are what we're good at.

This post is the engineer's version of that debugging session: how the record is assembled, where it gets corrupted, and how to diff it across sources with a few lines of Node.

The record, not the page

Google's own documentation reduces local ranking to three forces: relevance, distance, and prominence. It also states there is no way to pay for a better local ranking. What it doesn't spell out is where the record's data comes from. Their docs on business information list four inputs:

publicly available information, such as crawled web content
licensed data from third parties
user contributions (suggested edits)
Google's own interactions with the place

Read that list again as an engineer: you are not the only writer to this database. Your Google Business Profile is one writer among four. Directories, data aggregators, and random users all hold write access to fields you think you own. And when writers disagree, the merge strategy is not "owner wins", it is "confidence wins": Google may refuse your own edit if it can't corroborate it elsewhere.

That is why two businesses with identical websites can rank completely differently in the pack. One has a record every source agrees on. The other has three phone numbers in the wild.

The eight fields that matter

If the pack is a database contest, these are the columns it sorts on, roughly by how much movement each produces (the full evidence for each is in our map pack ranking factors reference):

#	Factor	You control it?
1	Primary GBP category	Fully
2	Proximity to the searcher	No
3	Review volume, recency, rating	Indirectly
4	Profile completeness and activity	Fully
5	Behavioral signals (calls, directions)	Indirectly
6	On-page location relevance	Fully
7	Citations and NAP consistency	Fully
8	Competitor spam levels	Report only

Notice what's fully controllable: the category, the profile data, the landing page, and the consistency of the record across the web. Notice also what most agencies sell hardest (more listings, more links) and where it actually sits in the table.

Diffing a business record across sources

The corruption you're hunting is rarely dramatic. It's "Ste 200" vs "Suite #200", a call-tracking number a previous agency left on one directory, a pre-rebrand name on a listing nobody remembers creating. Each variant is a competing write to the same record.

Here's the minimal diff harness. Every serious directory (and your own site, if you've done it right) exposes the record as LocalBusiness JSON-LD, so you can pull and compare the fields directly:

const norm = {
  phone: (s = '') => s.replace(/[^\d+]/g, '').replace(/^00/, '+'),
  name:  (s = '') => s.toLowerCase().replace(/[^\p{L}\p{N} ]/gu, '').trim(),
  street:(s = '') => s.toLowerCase()
    .replace(/\bsuite\b|\bste\.?\b/g, 'ste')
    .replace(/\bstreet\b|\bst\.?\b/g, 'st')
    .replace(/\s+/g, ' ').trim(),
};

async function record(url) {
  const html = await (await fetch(url)).text();
  const blocks = [...html.matchAll(
    /<script[^>]*application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi
  )].flatMap(m => { try { return [JSON.parse(m[1])] } catch { return [] } });
  const nodes = blocks.flatMap(b => b['@graph'] ?? [b]);
  const biz = nodes.find(n => /LocalBusiness|Dentist|Plumber|Restaurant/
    .test([].concat(n['@type']).join(',')));
  if (!biz) return null;
  return {
    url,
    name:   norm.name(biz.name),
    phone:  norm.phone(biz.telephone),
    street: norm.street(biz.address?.streetAddress),
  };
}

const sources = await Promise.all(listOfListingUrls.map(record));
const clean = sources.filter(Boolean);
for (const key of ['name', 'phone', 'street']) {
  const variants = new Set(clean.map(r => r[key]));
  if (variants.size > 1)
    console.log(`CONFLICT on ${key}:`, Object.fromEntries(
      clean.map(r => [new URL(r.url).hostname, r[key]])));
}

Run that against a business's known listings and you get the exact output a local SEO audit charges hundreds for: which field disagrees, on which host. The normalization step is where all the real-world pain lives, and it's also the point: if your normalizer needs three rules to match two listings, Google's entity resolution is doing the same work with the same uncertainty, and uncertainty is what suppresses records.

Not every source exposes JSON-LD, and plenty of directories render the NAP with JavaScript, so a fetch-based diff has honest blind spots. For the sources it can't read, tooling should say "unchecked" rather than guess. We run this exact philosophy as a free NAP checker (it reads OpenStreetMap via Nominatim plus two open directories, and it explicitly separates "missing" from "couldn't read"), so you can get the diff without writing the harness.

Fixing writes, not adding rows

The instinct once you find conflicts is to add more listings: more rows must mean more signal. The data says otherwise. Past the point of consistency, bulk listings on low-authority directories add coverage, not rank. What actually moves the record's standing:

Fix the conflicting writes first. Correct or claim the stale listings before creating anything new. Building on top of contradictions scales the contradictions.
Mirror the primary category everywhere. It's the strongest fully-controllable field, and directories have category fields too. Same classification, every source.
Complete the record. Hours, services, attributes. Between two equally close businesses, the more complete record tends to win, and it converts better after it wins.
Then let reviews and behavior compound. They're the heaviest signals you influence only indirectly, and they accumulate on top of a record Google trusts, not instead of it.

The whole discipline, one canonical record enforced across every source that has write access, is called NAP consistency, and it is the least glamorous, highest-floor work in local search. If you'd rather hand the fixing and building to someone whose job it is, that's literally what a citation building service does: audit the existing writes, correct them, create the missing ones, and prove each with the live URL.

The takeaway

Treat the map pack like the database it is. Enumerate the sources that hold your record, diff the fields, fix the writes, and only then optimize the parts everyone obsesses over. A page-one website with a corrupted record loses to a mediocre website with a clean one, every day, in every city.

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). Point it at the listings a business already has and you have the audit half of citation building: the part that decides whether to fix an existing record or create a new one.
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, our NAP checker runs this pipeline (plus a few data sources beyond schema) against any business name — free, no signup. And if you are weighing whether to build this in-house at all, the commercial options are compared in best citation building tools.

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. There is more on why the inconsistencies matter in this write-up on finding and fixing duplicate listings, and the full sweep that finds them in the first place is a local citation audit.

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. Coverage is a citation building problem (create the records that should exist); consistency is a maintenance problem (keep the records that already exist identical).

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.

If the domain itself is new to you, local citations covers what these directory records are and why search engines cross-check them before trusting a business.

DEV Community: Citation Builder

Ranking a Two-Dimensional Catalog With One SQL Expression

The data model

Attempt 1: the inner join that eats your catalog

Attempt 2: LEFT JOIN, and let the score decide

The scoring expression

The COALESCE sentinel, and its trap

Ordering, including the boolean

Two bugs worth stealing

Does the ranking hold up?

When not to build this

Takeaways

The Google Map Pack Is a Database, Not a Search Result

The record, not the page

The eight fields that matter

Diffing a business record across sources

Fixing writes, not adding rows

The takeaway

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