@acjlabs/google-taxonomy-verify

Google's official Product Taxonomy, bundled as data, plus lookup and verification helpers. TypeScript, works in Node, Bun, Deno, and the browser — no network calls, no external services.

Install

npm install @acjlabs/google-taxonomy-verify

Why this exists

Ask an LLM to classify a product into Google's Product Taxonomy and it will confidently return a leaf_id that looks plausible — and is sometimes wrong. A real example: asked to classify a winter parka, a capable model returned 212 (the real ID for "Apparel & Accessories > Clothing > Shirts & Tops") instead of the correct 5598 ("Apparel & Accessories > Clothing > Outerwear > Coats & Jackets"). The claimed category path it gave alongside the ID didn't even match what 212 actually is — a fabrication, not just an imprecise guess.

Since Google's taxonomy is fixed, public reference data with exactly one correct answer per real-world category, there's no reason to trust a probabilistic claim here. Verify it deterministically instead.

What's in it

import {
  isVerifiedGoogleLeafId,
  lookupGoogleTaxonomyPath,
  findGoogleTaxonomyId,
  googleTaxonomyEntryCount,
} from "@acjlabs/google-taxonomy-verify";

// The core check: does this ID exist, AND does its real path match what was claimed?
isVerifiedGoogleLeafId("212", ["Apparel & Accessories", "Clothing", "Shirts & Tops"]); // true
isVerifiedGoogleLeafId("212", ["Apparel & Accessories", "Clothing", "Outerwear"]); // false — path mismatch
isVerifiedGoogleLeafId("999999", ["Anything"]); // false — ID doesn't exist

// Plain lookup by ID.
lookupGoogleTaxonomyPath("5598");
// ["Apparel & Accessories", "Clothing", "Outerwear", "Coats & Jackets"]
lookupGoogleTaxonomyPath("not-a-real-id"); // null

// Reverse lookup: exact full path -> ID. Not a fuzzy search — segments must match exactly.
findGoogleTaxonomyId(["Apparel & Accessories", "Clothing", "Shirts & Tops"]); // "212"

googleTaxonomyEntryCount(); // 5595

The data

google-taxonomy-2021-09-21.json — 5,595 entries, {ID, Cat1..Cat7} (up to 7 taxonomy levels; empty string for unused levels). Sourced from Google's own published taxonomy file (google.com/basepages/producttype/taxonomy-with-ids.en-US.txt), confirmed current via a direct live check against that file. Google publishes this taxonomy specifically for merchant/developer use in Shopping feeds — public reference data, not a creative work requiring a license grant, consistent with the several other open-source mirrors of the same file.

Why this exists (the longer version)

We build Catalog Attribute Normalizer, a hosted API/MCP server that classifies merchant product catalogs into Google/Shopify/Amazon taxonomies using an LLM classifier — and hit exactly the fabrication problem described above in our own real classifier output. The fix (verify every claimed ID against the real taxonomy file before trusting it, never fabricate) is now a standing part of that product. This package is the small, standalone piece of that fix: the real taxonomy data plus the verification/lookup logic, with no LLM, no hosting, no API key — just the reference data and deterministic checks, MIT-licensed, for anyone who needs it on its own.

Scope

This ships one taxonomy snapshot (2021-09-21, confirmed current as of publishing this package). Google updates the taxonomy occasionally; if a newer snapshot matters for your use case, verify against Google's own live file (linked above) before relying on an exact ID match for very recently added categories. This package does not classify products for you — it only verifies/looks up IDs you (or your classifier) already have. If you need the classification itself, that's a separate, harder problem — see Catalog Attribute Normalizer if you want a hosted solution, or an open-source text-to-category matcher if you'd rather run one yourself (a different task from this package's ID verification).

License

MIT