This page explains how a record gets attached to a building, a landlord, a contractor or a neighborhood — and where that matching is known to be imperfect. The short version: buildings are keyed on their Borough-Block-Lot number, which is exact; everything joined by a name is a best effort and is labelled as one.
Buildings: keyed on the lot, not the address
A typed address is resolved to a BBL — one digit of borough, five of block, four of lot — and every record on a building page is fetched by that number rather than by the address text. This matters because one building can carry several addresses ("1 Times Square" and "1475 Broadway" are one lot) and because street names are spelled a dozen ways across agencies.
The agencies do not agree on how to write a BBL, and the differences were measured against the live data rather than assumed:
- HPD's violation feed carries a plain ten-digit
bblcolumn. - DOB's violation feed carries borough, block and lot separately, with the lot padded to five digits.
- The ECB feed stores the lot both ways — four digits and five — so both are asked for and the results summed.
Getting one of those wrong does not produce an error. It produces a page that says zero. That is why each one is written down.
Landlords: matched by name, with the limits that implies
A landlord page is built from two legs: lots whose owner name on the Department of Finance tax roll reduces to the same key, and HPD registrations naming a company of that name as owner, officer or agent. Both are name matches, and names are not identifiers.
So: a company recorded under more than one spelling will appear as more than one page, and two unrelated companies that happen to share a name will appear as one. The tax roll also wraps long owner names at a fixed width, which is why some names on these pages read oddly — that is how the city stores them, and correcting the spelling would break the link between the page and the record it came from.
Buildings held through a differently-named shell company will not appear on a page for the parent. That is a real limit, not an oversight: joining shells to a parent means inferring from shared addresses, and some of those addresses are registered-agent offices used by hundreds of unrelated companies. On a page that names a company, that is the wrong risk to take.
Contractors: keyed on the licence number AND the trade
A DOB licence number is not an identity on its own. Licence 2305 is Turner Construction as a General Contractor and a plumbing company as a Master Plumber — two unrelated businesses, one number, and DOB's own licence roster carries eight rows for it, one per trade. So contractor pages are keyed on the pair: number and licence type.
The three systems also spell the number three ways — the roster stores it bare, the legacy permit feed pads it to seven digits, DOB NOW pads it to six — so each is queried with its own padding. Contractor pages cover General Contractors only, because "GC" is the one licence type spelled identically in both permit systems; the other trades use vocabularies that do not line up, and guessing at the mapping would merge companies.
Two further limits are worth stating. Names are reproduced as filed: DOB's roster cuts a business name at 25 characters, and one company often files under several spellings, so the name shown is the fullest one the city holds rather than a tidied one. And no violation is attributed to any contractor, for the reason given in data sources.
Neighborhoods: the city's own boundaries
Neighborhood pages use City Planning's Neighborhood Tabulation Areas, matched to buildings through the 2020 census tract the tax roll records for each lot and DCP's own tract-to-NTA equivalency table. No boundary is drawn or estimated here.
That join was checked against a source that knows nothing about it: the Department of Buildings prints its own neighborhood name on every DOB NOW permit, from DOB's geocoder. Across 295 sampled lots, the neighborhood this method produces and the one DOB printed were identical 295 times, with no disagreements. Where a neighborhood page quotes a violation count, it is a count for the buildings listed on that page and says so — the violation feeds carry no census tract, so a true neighborhood total would mean one request per building.
How fresh the numbers are
Pages are built from live queries when they are requested, then held for a period so the same page is not rebuilt for every visitor. So a figure is current as of the day the page was built, and the page says so where it quotes one. The underlying schedules belong to the agencies, not to us — data sources gives each publisher's own cadence.
"Open" always means the status the city's own dataset carries. An open violation is a filing that has not been resolved in the record; it is not a finding against any individual, and a building can carry an old open violation for something long since fixed but never signed off.
What the scores are
The building and landlord scores shown in the app are our own estimates, computed from the public records on the page. They are not official city ratings, not credit scores, and not endorsed by any agency. They exist to summarise a long record, and every one of them can be traced back to the counts it was built from.
When we are wrong
Records disagree with reality sometimes, and sometimes we join them badly. Every page in the app carries a "See a mistake? Report a correction" link, and reports are read. If a page is wrong about a building you know, that is the fastest way to fix it — and the most useful thing you can include is the address and which specific figure looks wrong.