Reference

Some inputs are pulled for your exact address; others describe the surrounding census tract or county; the grid-carbon factors describe a whole power-grid region; a couple use national models; and a few depend only on your house and are identical anywhere. This is the single most common source of confusion, so here it is up front.

The engine scores thirteen dimensions. The composite is the mean of whichever could be scored (location dimensions are omitted, not zeroed, when their data/keys are unavailable). National grades use absolute thresholds: A ≥ 80, B ≥ 60, C ≥ 40, D ≥ 20, F < 20.

The structural system. It drives Disaster Resilience (separate factors per peril) and the build-quality grade used by Durability & Environmental. Lower peril factors = less expected loss = better; higher build grade = better. ICF/SIP also get extra envelope credit in the Energy model beyond what the wall code below implies.

Upkeep/deterioration. Multiplies expected loss for every disaster peril (so it affects the score at any age, with no upper cap) and feeds the Durability model.

Affects the flood peril only (below-grade space is what floods).

The build-code era (wind/seismic) vulnerability is a continuous curve, linearly interpolated between the anchor years below and clamped beyond them. A 1969 and a 1970 build no longer differ by a cliff. Lower is better.

A separate continuous curve captures the electrical/wiring era (fire peril), interpolated between these anchors and clamped beyond them.

Above-code features that reduce a specific peril's expected loss. Each is a multiplier (lower = bigger reduction) applied on top of the construction/condition adjustment. FORTIFIED tiers are composite and supersede the individual wind features; the three elevation tiers are mutually exclusive.

Starting configurations. Any field you set in Construction details (or via CLI/API) overrides the preset.

Every variable above is settable three ways: the Examples search form, the housing-simulate CLI, and the /label HTTP API (see Setup).

CLI

housing-simulate --address "123 Main St, Columbus, OH" \
    --construction icf --year-built 2026 --condition excellent \
    --foundation slab --sqft 1800 --value 350000 \
    --solar --hurricane-straps --fire-sprinklers --json

Core flags: --preset, --address (or --lat/--lon), --construction, --year-built, --foundation, --condition, --flood-zone, --value, --units, --sqft, --lot-acres. Each resilience upgrade is a flag (e.g. --solar, --fortified-gold, --elevation-1ft). --json emits the full payload; --no-fetch runs offline.

Density comparison: add --density to compare the same parcel at 1–4 dwelling units (fixed lot, constant per-unit value). This is the density dividend. Set the counts with --density-units 1,2,4; combine with --json for machine-readable output.

API

GET /label?address=<addr>&preset=baseline&construction=icf&year_built=2026
          &condition=excellent&sqft=1800&value=350000
          &upgrades=solar,hurricane_straps,fire_sprinklers

Same parameters as the CLI; resilience upgrades are a single comma-separated upgrades= list. GET /suggest?q= powers the address autocomplete.

GET /density?address=<addr>&units=1,2,4&per_unit_value=250000

Compares the parcel across densities (fixed lot, vary units). Accepts every /label house parameter plus units= (comma-separated counts, default 1,2,3,4) and per_unit_value= (held constant; otherwise an explicit value= is the per-unit value, else the county median is auto-filled). Each scenario returns its scores plus fiscal productivity per acre (revenue_per_acre, cost_per_acre, net_fiscal_per_acre), and the response includes the headline density dividend (fiscal ratio, Infrastructure grade, and total-revenue-per-acre multiplier from fewest to most units). revenue_per_acre is property tax + user fees, matching the scope of cost_per_acre.

GET /timeline?address=<addr>&years=2000,2026,2040

Holds the address fixed and moves the clock. Accepts every /label house parameter plus years= (comma-separated as-of years for the building-ageing sweep; default a quarter-century back, now, and fifteen years on; at most six). Returns series (per dimension: ordered points, the delta, and a basis of observed, projection or aging — a measurement, a forecast, and arithmetic on a component-lifespan model are three different claims), point_in_time (a sentence for every dimension that carries no series, so a missing trend never renders as silence), and as_of (the Building headline grade at each year). Every point is scored on today’s breakpoints, so a change is a change in the place or the house rather than in how it ranks against a moving national average; a national_percentile is therefore surfaced only at the point its reference distribution was calibrated for.

Badge

GET /badge?address=<addr>&style=full&theme=auto

The label as a standalone SVG, for embedding on a page that isn’t ours. It renders inside a plain <img> — no script, no CORS, no build step on the host page:

<a href="https://housinglabel.dev/label.html">
  <img src="https://your-api-host/badge?address=123%20Main%20St,%20Memphis,%20TN"
       width="360" height="116"
       alt="Housing Nutrition Label — the building and the site, graded">
</a>

Takes address= (or lat=/lon=), plus style= (full 360×116, compact 300×40), theme= (auto, light, dark — auto follows the reader’s own setting through a media query browsers honour even inside an <img>), preset=, and label_text= to override the caption.

It shows two grades, not one — the building and the site, the same split the label leads with. A single letter would travel further and would be the wrong number: the two axes disagreeing is the information, and a composite that hides a D behind an A is the summary a badge is most tempted to print. An axis that could not be scored reads not scored rather than being rounded down to an F.

Two consequences of the <img> constraint: browsers disable links inside an <img>-loaded SVG, so wrap the badge in an anchor for click-through (the wordmark is drawn into the image so attribution survives if you don’t); and no web fonts are available, so text falls back to the reader’s system stack and long addresses truncate rather than being fitted.

The badge carries the trademark, which is licensed separately from the code — see the trademark policy. Displaying it unmodified, with attribution, is referential use and needs no permission.

Print & save

GET /label.svg?address=<addr>&theme=light&download=1

The whole label as one US Letter page of vector — both headline grades, all thirteen dimensions, the running-cost line, and the disclaimer in full — for printing, filing, or dropping into a report. It takes every /label house parameter and is scored through the same path, so a saved sheet cannot disagree with the label it was saved from, refinements included. Beyond those: theme= (light by default, where the badge defaults to auto — this one is made for paper, and paper has no dark mode), download=1 for an attachment rather than an inline render, label_text= to caption it with an address you have already formatted, and scored= to stamp a date in the footer.

Three things it does differently from the card on this site, all of them because paper is not a screen. It has an edge: the layout is budgeted against the page, so a thirteen-dimension label lands on one sheet rather than breaking across two wherever the browser chose — the per-row detail panels are the one thing left off, because printing all thirteen would be a booklet, not a label. Colour is never the only channel: every grade is a letter and a bar length and a number, so a grayscale printer or a photocopy loses nothing. The text is still text: real <text> elements rather than outlines, so the sheet stays searchable, selectable, and editable in Illustrator or Inkscape.

Printing from the site needs no API call: the Print label button — in the search form's own action row, disabled until something has been scored — prints the page as it stands — the rows you expanded included, the controls dropped — and adds a colophon naming the source and the date, because a page of grades with no source and no date is the copy that gets misread a year later.

Keys & usage

No key is required, and on a self-hosted instance none exists. Every caller is anonymous unless the operator has issued keys, and an anonymous caller is unmetered — the same service that ran before keys did. Where keys have been issued, sending one as an X-API-Key header gets you a rate-limit bucket of your own rather than one shared with everybody behind the same address, plus your plan’s daily allowance. It does not change the numbers: a scored address returns the same label on every plan.

?key= also works and is not equivalent. A query string is part of the request line, so it is captured verbatim by the server’s access log, by any proxy in front of it, by browser history, and by the Referer sent to third parties — none of which the API can unwrite. Prefer the header wherever you can set one. ?key= exists for callers that genuinely cannot (an <img> or iframe embed, a quick curl); requests carrying it are answered no-store so the key-bearing URL stays out of the disk cache, and a key that has travelled that way is one worth rotating.

GET /usage

Reports the calling key’s plan, what it has spent today, what remains, and that the day resets at 00:00 UTC. It answers for the caller and only the caller — there is no parameter that points it at another key.

Anonymous callers are counted too, one row each: a badge is attributed to the site embedding it (the Referer’s host, so a thousand readers of one page count as one embedder), everything else to the calling address. That is attribution rather than authentication — a Referer is trivially forged, and it counts cooperative callers correctly without stopping an uncooperative one.

Metering counts scoring passes, not requests: /label, /label.svg and /badge are one each, /presets is five, a four-scenario /density is four, a three-point /timeline is three. Metered replies carry X-Quota-Limit, X-Quota-Remaining and X-Quota-Used; exhausting the day returns 429. A request rejected as invalid is never charged, and an unrecognised key is refused with 401 rather than quietly downgraded to the free tier.