DEV Community: Nearbia

Starting a Local Directory From Public Records: Notes on the License Frame

Nearbia — Wed, 28 Oct 2026 12:16:17 +0000

Most local business directories begin with whatever businesses submit about themselves. We are trying the opposite order for Nearbia: start with the records that say who is allowed to do the work, then find websites, then check each site. The directory is not live yet. What is live is a set of plain guides and a work log, and this post walks through the data side of that work.

Why start with licenses

In Florida, contracting without a state license is a crime, and the state's Department of Business and Professional Regulation (DBPR) is the body that issues trade licenses. For a directory of contractors, that makes the license file a natural "frame": the set of entities that should be in scope before you look at anything else.

The license data itself is surprisingly structured. A Florida contractor license number starts with a few letters, and those letters encode two things:

The trade. CFC is a certified plumbing contractor, CAC is air conditioning, CGC is general, EC is electrical. Two easy ones to misread: CCC is roofing and CPC is pool/spa.
The scope. Codes starting with C are certified (passed a board-approved exam, valid in any Florida jurisdiction). Codes starting with R are registered (met local competency rules, valid only where those rules were met).

If you are modelling this, the prefix is effectively a compound key: trade + scope. Treat "certified vs registered" as a first-class field, because it changes where a business can legally work.

The stages, as a pipeline

The Nearbia work log lays the process out in stages. Paraphrased as a pipeline:

National list of websites. Free open datasets of US places are downloaded whole. Each website gets one key so duplicates collapse.
License frame. Florida's contractor license file lists everyone allowed to work. The log notes the state site blocks automated downloads, so a saved copy from a public web archive is used, and freshness is not guaranteed. That is an honest constraint worth designing around: version your snapshots and record their dates.
City domain list. Sites with a plumbing category or name, inside or near city limits, are pulled from the national list.
Other candidate sources. Building permits, the state business entity registry, and paid search listings for the city.
Merge into companies. Records join on license number, then phone, then name and city, then final domain after redirects.
Place addresses in city limits. A mailing city is not a city boundary.
Website check in a real browser.

The first slice is deliberately small: one trade (plumbers) in one city (St. Petersburg, Florida).

Things that bite you

Join order matters. License number is the strongest key when present. Phone numbers are shared, recycled and tracked. Names drift ("Inc." vs "LLC", DBAs). Domains redirect. Ordering joins from strongest to weakest key keeps bad matches from cascading.

Mailing city ≠ city. The work log points out that some St. Petersburg ZIP codes reach into Seminole, Kenneth City and Pinellas Park. If your city page filters on the mailing city string, you will list businesses that are not in the city. Geocode and test against the actual boundary.

Neighbouring cities overlap. The log reports that St. Petersburg and Clearwater shared about 80% of the same companies within a radius in their tests. Their decision: a city page lists only companies with an office inside that city. Whatever you choose, make the rule explicit, because "serves the area" and "is located here" are different claims.

Not every record says what you think. A local business tax receipt is not a contractor license. Registering an LLC does not qualify anyone to contract. If you are merging state corporate filings with license data, keep them as separate attributes rather than collapsing them into one "verified" flag.

Public records are a toolbox

Beyond licenses, Florida law opens state, county and city records to inspection by anyone, with specific exceptions. For a contractor, that includes corporate filings and fictitious names (Sunbiz), building permits (county portals), code enforcement cases, court dockets and liens, OSHA inspections, and federal exclusions in SAM.gov. Each answers a different question, and each has blind spots. A permit portal, for example, cannot show work that was done without a permit.

Where to read more

The full write-ups, including the stage table with dates and the record-by-record reference, are in the work log published by Nearbia. If you work with licensing or permit data and have hit any of the same problems, I would be glad to hear how you handled them in the comments.

Why One HTTP Request Misjudged 200 Business Websites, and the Browser + LLM Pipeline That Replaced It

Nearbia — Tue, 13 Oct 2026 08:41:20 +0000

For one slice of Nearbia, a US local business directory assembled from public records, the team had to answer a narrow question: which candidate websites really belong to a plumber that serves St. Petersburg, Florida? The list started with 200 domains, and fewer than half passed. Below are the pipeline, the first version that failed, and the numbers from a snapshot taken on Oct 1, 2026.

Inputs: eight sources, 200 domains

Candidates came from five free sources and three paid ones.

Free	Paid
Overture Maps	Google business listings
Foursquare	Google Maps
OpenStreetMap	Google organic results
AllThePlaces
Florida license records

The inclusion rule was geographic. A domain stayed on the list if at least one source put it inside the city boundary (US Census Bureau TIGERweb, Places layer) or within 3 km of that line:

92 domains inside the city;
90 just outside, in places like Gulfport, Kenneth City and Pinellas Park;
17 only from organic search results, with no coordinates;
1 with nothing but a postal city.

Every source missed something. 30 domains came from Foursquare and nowhere else, 21 from Overture only, 17 from Google organic results only. All Google lookups for the slice cost about $0.18.

Version 1: one request per homepage

The first pass was cheap. It sent a single request to each homepage, took the first 400 KB of raw HTML and searched it for the city name and plumbing words. It failed in both directions.

Real plumbers it rejected:

sites that render their content with JavaScript;
sites that keep the address on the contact page only;
sites that say "Tampa Bay" rather than the city name.

Wrong sites it accepted:

lead-generation sites and directories, which repeat the city name all over the page;
parked domains and server placeholder pages, which it counted as live.

Against a real browser, the quick check undercounted dead domains (27 instead of 36) and let six lead-generation domains through. On Oct 1, 2026 it lost its say in verdicts: now it only reports whether a domain answers.

Where the checker runs matters too

From a computer in the Netherlands, 47 of the 200 sites did not respond. From a US IP address, 15 of those 47 loaded right away. Since then, every check runs from the US.

Version 2: render, label, verify, locate

Render. Every live homepage loads in ordinary Chrome with JavaScript enabled, five browsers in parallel. The 171 homepages that answered took about 40 minutes.
Label. A language model hosted on Nearbia's own server reads each captured page and assigns one site type: a local company's own site, a franchise location page, a national chain, a directory, a lead-generation site, unrelated, or dead.
Verify. The model must quote the page to back its label, and code confirms that each quote really appears there. Labels with confidence below 0.6 go to a person.
Locate. Whether a business is local is not the model's call. Code decides it from evidence found on the site.

Location evidence, strongest first

Code reads the homepage first. When it finds nothing there, it opens up to two more pages: contact, service area, or a chain's local page.

Rank	Signal	Detail
1	Phone on the site matches the phone the sources list for that domain	Those source records already sit in the city. Toll-free 8xx numbers are ignored, since a chain uses the same one everywhere.
2	Area ZIP code in the address or structured data	33701 to 33716, 33730 to 33747, 33781, 33782
3	A city from the zone next to "FL" or "Florida"	The state is mandatory: Gulfport also exists in Mississippi, and Tennessee has a Petersburg.
Weak	Only a region (Pinellas, Tampa Bay) or only the 727 area code	Not enough to enter the corpus

Before three duplicates were merged, 91 sites had evidence. The strongest signal was a phone match for 58 of them, city plus state for 19 and a ZIP code for 14. Ten of the 91 were local pages of franchises.

Final split of the 200 domains (Oct 1, 2026)

Group	Domains
Local plumbers with location evidence	88
Local plumbers, region only	10
Local plumbers, no location evidence	7
Local businesses in another trade (HVAC, appliance repair)	13
National chains and brands	3
Directories and lead-generation sites	17
Not home services	16
Duplicates redirecting to another domain on the list	4
Blocked by bot protection, even in a browser	6
Dead, parked or no DNS	36
Total	200

The 88 form the corpus, and only they go on to a full crawl and fact extraction. Of the 88, 45 sit inside city limits and 38 within 3 km of the boundary.

Three things the data got wrong

A wrong website on a local record. Five domains tied to St. Petersburg belonged to plumbers in Colorado, Idaho, Mississippi, Broward County and Orange City, Florida. Without evidence on the sites themselves, they would have entered the directory.
Gaps in the starting database. It lacked 21 of the 45 in-city plumbers in the corpus. Google alone found 11 of those 45.
Invented trades. The model once labeled a sewer pipe lining company as window cleaning. That is why a person reviews the "another trade" group.

Known limits

This is a single snapshot from Oct 1, 2026. Sites change, and dead domains may come back.
The check reads the homepage plus at most two pages. A plumber that names its area only deeper in the site lands in "region only" or "no location evidence", and those 17 domains still need a human review.
Only businesses with a known website are covered. Florida records list 93 active plumbing licenses with a St. Petersburg address; for 69 of them no domain is known, and some have no website at all.

How do you confirm that a website really belongs to a business at a given place? Curious which signals others rely on.

This post was written with AI assistance from Nearbia's original field notes; every figure in it comes from those notes.