🤫 Yellow Pages — the road to 100% US coverage

TL;DR: 1,161,314 licensed professionals across 1,633 ZIP areas answer 37.8% of the US map within 25 miles today; getting to 100% is a bytes-in-the-image problem, not a data problem, and the plan buys coverage and depth separately.

Status as of 2026-07-28: see body.

Where we actually are

Measured 2026-07-28, and recomputed on every ingest so the public page cannot drift from the index.


Licensed professionals in the index	1,733,553
ZIP areas covered	30,556 of 33,791
Carrying a phone the regulator published	99.9%
US map answered within 25 miles	99.82%
US map answered within 10 miles	98.17%
Specialties, each measured separately	29

The number the aggregate hides

99.82% is the flattering figure. Recall is measured per specialty rather than rolled up, because "a healthcare worker within 25 miles" and "a rheumatologist within 25 miles" are different promises and only one of them is what somebody typed. Measured that way:

specialty	answered within 25 mi
Rheumatology	30.73%
Nephrology	32.05%
Endocrinology	32.51%
Gastroenterology	35.92%

A thin shard spreads its budget across specialties, so common professions land in every ZIP and rare specialists rarely make the cut. That gap is real and it is ours to close; hiding it inside an average would be the easiest dishonesty available on this subject.

The finding that changed the ingest

The extract arrived with 12% of rows declaring a state that their own ZIP contradicted — a Connecticut electrician placed in Cupertino, a Park Ridge cardiologist labelled New York. The first read was that those rows were bad and should be quarantined.

Measuring it says otherwise. Among the disagreeing rows, the regulator-published phone's area code matched the ZIP's state 18,286 times and the declared state 2,042 times. The column is carrying the licence-issuing state, not the address.

So the ZIP is authoritative, the declared value is kept as licence metadata and never as a location, and 337,000 rows had their state corrected rather than dropped. The lesson is the general one: when two fields disagree, find a third that can arbitrate before deciding which to throw away.

The real constraint

The instinct is that coverage is a data-acquisition problem. It is not — the public record already holds far more people than we serve. The constraint is bytes inside the container image.

	ZIP areas	rows	shard bytes
Today, at 800 listings per ZIP	1,633	1,161,314	126 MB
Same depth, every US ZIP	33,791	~24 M	~2.6 GB

2.6 GB does not ship in a container image. Every honest plan has to buy coverage and depth separately, because they cost different amounts.

The plan

1 — Done. Every ZIP answers, and now almost every ZIP answers with a neighbour. National ZIP resolution over all 33,791 ZIP areas, distance-ranked, with a by-name handoff to the regulator wherever the index is still thin. Nobody hits a dead end, and nothing is ever invented to fill a gap.

2 — Done. The thin national tier — the step that moved the map. The source was never the constraint: the public-domain provider registry publishes people in nearly every populated ZIP. So every ZIP outside the deep tier got a shallow shard of about 30 listings, phone-first, one of every specialty before two of any. 28,923 ZIP areas, 572,239 listings, 62 MB — against the 2.5 GB that the same depth everywhere would have cost. Shards group by 3-digit ZIP prefix, which is both cheaper to build and better to serve, because a proximity query fans out to neighbours and neighbours share a prefix. 25-mile recall went from 37.8% to 99.82%.

3 — Next. Close the rare-specialty gap. Rheumatology at 30.7% against an aggregate of 99.8% is the gap a thin tier cannot close, because spreading a small budget across specialties is exactly what leaves rare ones out. The fix is a targeted pull per specialty per region — a different and much smaller query, not more generic depth.

4 — Then. Depth moves out of the image. Deep shards become object-store artifacts fetched per request behind a small in-process cache, versioned by content hash so a deploy can never serve a half-swapped index. That removes the per-ZIP cap entirely.

5 — Then. The trades, the advisers, the agents, the civic roll. 531,689 records already in hand — electricians, contractors, technicians — are held back because their state file publishes a licence-type code rather than a profession: ELC, C-RXN, 10, Mini Establishment. None of those tells a person what the business does.

The resolution turned out to be simpler than expected and worth recording. Connecticut's own open-data registry publishes the code and its plain-English name side by side ("70" → "Emergency Medical Technician") across 641 pairs and 2.6 million records, 657,311 of them active and in-state. 479 of 518 codes resolve unambiguously straight from the regulator. The remaining 39 do not — ELC covers both Electrical Journeyperson and Electrical Contractor — and those stay held back rather than being flattened into a label that would be wrong for tens of thousands of people. The better move still is to re-pull the state from its own source with the credential name attached, rather than patch a lossy extract.

6 — Always. Claimed, owned, removable. Size is not the goal; being trusted is. Every professional can claim their one listing, verified against the regulator at claim time, and remove it in one step with no retention flow.

What is not yet true

There is no benchmark of the ingest on edge hardware and no cost-per-watt figure for it, so the intent to run batch ingest on the edge grid is a design direction and not a result. FedRAMP High and DoD Impact Level certifications remain in pursuit — none is claimed anywhere.

Sources

Directory coverage, live and recomputed each deploy
CMS NPPES NPI Registry — public domain
Internal ingest report and coverage snapshot, regenerated by the directory build scripts on every ingest