How this dataset is built.

01What this dataset is

A normalized, source-traceable, annually updated register of U.S. cities with current population, annual history, growth, density, land area, and centroid coordinates. Every field traces back to a specific raw Census file recorded with its sha256 in our build manifest.

The audience is someone who will scrutinize the numbers — a journalist, urban planner, real-estate analyst, researcher, or data-curious resident. The dataset is built to be defensible at that level. It is not a casual list-content product.

• Current population (Vintage V2025, July 1, 2025 reference date).
• Annual estimate history: 2010–2019 from V2019 and 2020–2025 from V2025.
• Within-vintage growth fields (absolute and percent) — never crossing the seam.
• National and state population, growth, and density rank.
• Land area, water area, density, and centroid (lat, lon).
• Stable Census geoid and a stable URL slug.
• Per-row provenance flags pointing back to the source file each value came from.

02How Census produces these numbers

Census does not count residents annually. The annual numbers are estimates built from the most recent decennial census plus year-by-year changes:

1. County estimates first. A cohort-component method on births, deaths, and domestic + international migration updates each county's population annually since the 2020 census.
2. Subcounty distribution. For each place or MCD, Census estimates housing units, multiplies by a household-population-per-housing-unit ratio derived from the 2020 census, and produces an “uncontrolled” household-population estimate.
3. Controlled to county totals. A rake factor rescales subcounty household-population estimates so they sum exactly to the published county household-population total. Subcounty estimates are not independent of county estimates.
4. Group quarters added separately. Population in correctional, juvenile, nursing, college, military, and other institutional facilities is estimated separately from a Group Quarters Report and added back. A college town's apparent year-to-year change can be driven entirely by reported dorm occupancy.
5. Final rounding uses a “greatest mantissa” method so rounded subcounty values still sum to the controlled county total.

03What counts as a “city”

The Population Estimates Program (PEP) only produces annual subcounty estimates for “areas of general-purpose government.” That means incorporated places (cities, towns, villages, boroughs, municipalities) plus minor civil divisions in 20 strong-MCD states. PEP does not publish annual estimates for Census-Designated Places (CDPs).

The V1 cities table includes 19,483 records:

What V1 explicitly does not include

• Minor civil divisions (SUMLEV=061). A real coverage gap. Edison Township NJ (~107k), Hempstead town NY (~800k), Brookhaven town NY (~487k), Cherry Hill NJ, and many other major Northeast population centers are missing. Tracked as the highest-priority V2 expansion.
• CDPs other than Urban Honolulu. PEP doesn't estimate them annually. For unincorporated communities like Silver Spring MD, Arlington VA, and East Los Angeles CA, use the decennial census or ACS directly.
• Place-portions and county-balance partition records (SUMLEV=071, 157, 172). These overlap with the place records — including them would double-count.
• U.S. territories. Puerto Rico, USVI, Guam, American Samoa, and the Northern Mariana Islands are published in separate releases and are not in V1. The 51 jurisdictions covered are 50 states + DC.

04Consolidated cities & special cases

Eight cities have consolidated their government with their county or surrounding territory. Census represents them at SUMLEV=170 (the legally meaningful unit) plus a SUMLEV=162 “balance” record. We use the SUMLEV=170 population and borrow the SUMLEV=162 balance's gazetteer geometry, since the gazetteer doesn't publish a separate row for the consolidated entity. This slightly understates land area — and overstates density — for these eight cities by the area of separately-incorporated enclaves.

• Milford CT · Athens-Clarke County GA · Augusta-Richmond County GA · Indianapolis IN · Greeley County KS · Louisville/Jefferson County KY · Butte-Silver Bow MT · Nashville-Davidson TN.

Three additional legal-status edge cases must be included explicitly:

Urban Honolulu CDP, HI

Pop 341,868. Honolulu has no separate municipal government from Honolulu County (consolidated since 1907); Census represents the city as a CDP. A strict “active legal city” rule would remove the largest city in Hawaii. Included with place_type='cdp_in_estimates'.

Washington city, DC

Pop 693,645. DC has no separate city government from the federal district itself; the place record is “nonfunctioning” because the government function is at the state-equivalent level. Included.

Houma city, LA

Pop 114,156. Houma is a former parish seat in Terrebonne Parish where the municipal government was consolidated into the parish in 2003; the Census place record is "nonfunctioning" (FUNCSTAT='N') but continues to report population. Included for completeness.

Tribune city, KS

Pop 711. Tribune is the county seat of Greeley County; Greeley County is one of Kansas's consolidated city–county governments. The Census place record has FUNCSTAT='N'. Included for completeness.

05Geographic enrichment

SUB-EST does not contain land area or coordinates. Land area, water area, and centroids come from the 2025 Census Gazetteer (cutoff January 1, 2025). Density is computed as pop_current / land_area_sqmi, NULL when land_area_sqmi is 0 or missing.

The join key is built from the SUB-EST STATE + PLACE (or CONCIT for SUMLEV=170) zero-padded into a 7-character GEOID. 19,483 of the 19,483 total cities match the 2025 Gazetteer cleanly. Geometry fields are NULL only when a future release has no matching gazetteer row.

06The 2019 ↔ 2020 vintage seam

The most important caveat for any growth statistic that crosses 2019/2020. The chained 2010–2025 series is not a single continuous series.

Vintage 2019 estimated July 1, 2019 by extrapolating from the 2010 Census base. Vintage 2025 re-based to the 2020 Census on April 1, 2020 (ESTIMATESBASE2020) and produced July 1, 2020 from there. The two series are independent estimates of two different reference dates, produced by different methodology generations.

These deltas are a mixture of three distinct things: (1) real population change between April 2019 and April 2020; (2) methodology-rebase from V2019’s 2010-based extrapolation to V2025’s 2020-Census anchor; and (3) noise from the 2020 Census Disclosure Avoidance system, which is embedded in the blended base that PEP used as its 2020 starting point. None of these components can be cleanly separated after the fact. They are not a clean signal of any single thing.

07Derived field recipes

Every field in the public dataset is either copied directly from a Census source or computed by an exact formula. The build script implements exactly these recipes and nothing else.

Population fields (raw)

pop_current

Alias of pop_2025. SUB-EST2025 POPESTIMATE2025 · July 1, 2025

pop_2020 … pop_2025

SUB-EST2025 POPESTIMATE{year} · July 1 of each year

pop_base_2020

SUB-EST2025 ESTIMATESBASE2020 · April 1, 2020 base

pop_2010 … pop_2019

SUB-EST2019 POPESTIMATE{year} · NULL if no V2019 record

pop_census_2010

SUB-EST2019 CENSUS2010POP parsed as int. NULL if value is "A" (place incorporated after 2010 census, 78 such places).

Within-vintage growth (never crosses the seam)

growth_2020_current_abs

pop_current − pop_base_2020 · cumulative change from 2020-census base to mid-2025 estimate

growth_2020_current_pct

100 × (pop_current − pop_base_2020) / pop_base_2020 · NULL when pop_base_2020 = 0

growth_prev_current_abs / _pct

One-year change. Within V2025.

growth_2010_2019_abs / _pct

Within V2019. NULL if either endpoint is NULL.

Geometry fields

land_area_sqmi / water_area_sqmi

Gazetteer ALAND_SQMI / AWATER_SQMI. NULL if no gazetteer match.

density_per_sqmi

pop_current / land_area_sqmi · NULL if land_area_sqmi is 0 or NULL

lat / lon

Gazetteer INTPTLAT / INTPTLONG.

Rank fields

All ranks use standard competition ranking (“1224”): tied values share the lower rank and the next rank is skipped, matching what readers expect from “tied for 5th place.” Percent-growth rankings require pop_base_2020 ≥ 5,000 to keep tiny denominator artifacts off the leaderboards. A village that grows from 12 residents to 200 is not a fastest-growing city in any product sense.

08Update cadence

Annual. Vintage YYYY of SUB-EST is typically released in May of YYYY+1. When V2026 ships we re-fetch the source, re-run the build, and republish.

Mid-cycle. No mid-year revisions are expected. If Census issues a special revision (Population Estimates Challenge Program acceptance, special census), it is recorded in the build manifest with a reason.

2030 census. A new vintage family will eventually replace V2025. At that point V2025's 2020–2025 series may itself be revised in a re-base. This page will be updated to match.

09What this is NOT for

The trustworthiness of this site depends on saying “no” honestly when a use case is outside scope.

• Not a legal boundary source. Use TIGER/Line shapefiles for boundary geometry. Our centroids are points, not polygons.
• Not a demographic source. Race, age, income, housing, commuting, and language come from the American Community Survey (ACS) — a separate Census product not in V1.
• Not a metro-area source. “New York metropolitan area” (~19.5M) is a different geography from “New York city” (~8.5M). Our pop_current is city-proper.
• Not a county-level browser. County–place relationships are not in V1 because places can span counties (cf. Indianapolis SUMLEV=071 partition records).
• Not a CDP browser (except Urban Honolulu). For Silver Spring MD, Arlington VA, East Los Angeles CA, use the decennial census or ACS directly.
• Not a Northeast-MCD browser. Edison NJ, Hempstead NY, and Brookhaven NY are not in V1. Documented gap; planned for V2.
• Not a 2010–2025 growth source. See §06. Use 2010–2019 (V2019) or 2020–2025 (V2025), but not both.
• Not a margin-of-error source. PEP estimates do not carry published MOEs the way ACS does. Treat them as administrative best-estimates with implicit uncertainty.
• Not a U.S. territories source. Puerto Rico, USVI, Guam, American Samoa, and the Northern Mariana Islands are not in V1.
• Not a daytime or commuter population source. All figures are resident population (people who live there), not workplace or daytime population. For commuter-adjusted figures, use Census LEHD or ACS journey-to-work tables.
• Not appropriate for legislative apportionment. Use decennial census counts, not PEP estimates, for any purpose that requires legally authoritative population figures (redistricting, apportionment, grant formulas that specify decennial counts).
• Not a tract, block, or block-group source. PEP only produces subcounty estimates for general-purpose government units (places, MCDs). For sub-city geographies, use the decennial census or ACS.
• Not an immigrant, citizenship, or nativity breakdown. Race, Hispanic origin, nativity, and citizenship status at the city level come from ACS, not PEP.
• Not a source for places revised in subsequent vintages. Each new vintage revises all years back to 2020. A number published today may differ from the same city’s figure in next year’s vintage. Always cite the vintage year alongside any figure. (Example: Washington, DC’s 2024 estimate was revised when the site moved from Vintage 2024 to Vintage 2025.)

10Attribution & reuse

U.S. Census Bureau publications are works of the United States Government and are in the public domain (17 U.S.C. § 105). No license fee, no required attribution. We attribute anyway because credibility flows from sourcing.

Recommended attribution language for any republished extract:

Source: U.S. Census Bureau, Population Division. Vintage V2025 Subcounty Resident Population Estimates. Geographic enrichment from the 2025 Census Gazetteer. Compiled and processed by Every City in the USA on 2026-06-17.

This site does not imply Census endorsement and must not. Census does not review or approve third-party uses of its data.

Every build is fully reproducible from the raw files recorded in MANIFEST.json (sha256, source URL, retrieval timestamp). The methodology PDF downloaded from Census at build time is also archived with its sha256 so any reader can verify that our description of the Census methodology matches the actual document we used.

11Known limitations

• MCDs (V2). The most consequential V1 gap. Tracked.
• Geometry for the 8 consolidated cities. Borrowed from the SUMLEV=162 balance entry; understates land area by the area of included enclaves.
• Gazetteer misses. The current V2025 build has no city rows without a 2025 Gazetteer match. Re-checked per release.
• CDP coverage (other than Urban Honolulu) is by design. Not a gap, but worth restating.
• Slug uniqueness may need to be re-evaluated when MCDs are added in V2.
• Disclosure Avoidance noise sensitivity for small places. The 2020 Census TopDown algorithm injects differential-privacy noise into place-level counts. For places over 50,000 the mean absolute error is on the order of 10 people; for places under 1,000 it is roughly 2 people in absolute terms but proportionally much larger. This noise is embedded in the blended base that PEP uses. Treat very small city figures as directionally correct, not precise.
• Estimates are revised in subsequent vintages. Each annual release revises all years back to the base year. The city-level figure for a given year may shift meaningfully between Vintage 2025 and future vintages. This site will always use the most recent vintage available, but archived pages or cached data may carry earlier figures. Always check the “Last built” date at the top of this page.
• “City proper” vs. metro-area trap. A city rank by pop_current is a rank of the city-proper population. San Antonio (~1.5M) is a single large incorporated city; the San Antonio metro area (CBSA) adds surrounding counties. Readers who want metro-level comparisons need CBSA/OMB data, not this dataset.

For the full source list with file sizes, sha256s, and retrieval timestamps, see /sources/.

12Demographics & income (ACS 5-Year)

City profile pages surface demographics, income, poverty, housing, and broadband adoption from the U.S. Census Bureau's American Community Survey 5-Year estimates, 2020–2024 window (released January 29, 2026). ACS is the canonical source for these fields at the place grain — the Population Estimates Program does not publish them.

Source & access path

We fetch the bulk Summary File (no API key required) from www2.census.gov/programs-surveys/acs/summary_file/2024/table-based-SF/, one pipe-delimited .dat per detailed table. The bulk path is intentionally chosen over the Census Data API because (a) the API now requires a key for every request, and (b) one bulk file per table covers all geographies including every U.S. place. V1 ships 16 priority tables. The full per-table schema lives in data/processed/acs/field_dictionary.json.

Sentinel values

ACS bulk files encode unestimable cells with sentinel values: -666666666 (insufficient sample), -555555555 (estimate not applicable), -222222222, and others. Every sentinel is mapped to NULL before the data lands in data/processed/acs/acs.csv. The current build mapped 18,206 cells (about 5.8% of place-level rows in suppression-prone tables). A bare sentinel reaching a city page is a verify failure.

Margin of error display rule

Every estimate (B19013_001E) has a margin of error (B19013_001M) at the 90% confidence level. We render both on every cell. When MOE > 0.5 × estimate, the cell is flagged “low precision.” This is most relevant for places under 1,000 population — for example, a tiny town might report median household income $170,154 with MOE ±$162,129. The estimate is technically published but should not be read as a precise dollar figure. The MVP 50k–150k population band has 100% fill and effectively zero low-precision flags.

Vintage seams (two of them)

• The PEP V2019↔V2025 population seam documented in §06 still applies. ACS uses a different production methodology and the seam is irrelevant for ACS-only fields, but cross-referencing ACS to V2019 PEP population is unsafe.
• Non-overlapping ACS 5-year windows. The 2015–2019 estimates and the 2020–2024 estimates cover non-overlapping periods and were produced under different methodology generations (post-2020-census re-basing). Comparing them as “ACS change over time” is methodologically unsound. We do not publish that comparison.

What this is NOT for

• Not a single-year income figure. ACS 5-year averages over five years; if the user wants a current-year number, ACS 1-year ships only for places ≥65k pop and we don't surface it in V1.
• Not a basis for cross-window change. See vintage seam note above.
• Not a precise dollar figure for tiny places. MOE can exceed the estimate; we surface the “low precision” flag honestly.

Refresh cadence: annual, each February, two weeks after the December/January Census release window.

13Local economy (SAIPE + LAUS)

City profile pages surface county-attached poverty (Census SAIPE) and labor-market data (BLS LAUS) alongside place-grain unemployment for the ~1,745 cities where BLS publishes sub-state LAUS. All values are labeled at their native grain — there is no manufactured city-level rate for fields that BLS or Census publish only at the county level.

Sources & vintage

SAIPE 2024

Census Small Area Income and Poverty Estimates, reference year 2024, released 07 Jan 2026. County-grain. poverty_rate_all, poverty_rate_under18, median_household_income plus 90% CI bounds. Model-based, not a direct count — always labeled as such.

BLS LAUS 2024 annual

Bureau of Labor Statistics Local Area Unemployment Statistics, 2024 annual averages. County file (3,221 counties) and sub-state file (~1,745 cities). Refresh annually each April when BLS publishes the prior-year annual averages.

Census Place→County crosswalk

Official Census file. In the current economic layer, 99.80% of the city rows available at build time matched cleanly; 38 places did not (newer incorporations) and ship without an economic block with a "county attribution unavailable" footnote.

The multi-county rule

5.7% of cities span 2+ counties in the current economic layer. At that build, 1,107 cities spanned 2+ counties. Worst cases: NYC, Dallas, and Fort Worth at 5 counties each. We list all linked counties on city pages — we do not compute population-weighted county averages. Manufacturing a single county-grain rate for a multi-county city would violate the same "no fabricated aggregates" rule that governs the V2019↔V2025 vintage seam (§6). Multi-county cities are also excluded from any sortable county-grain ranking view.

Place-grain LAUS coverage

BLS publishes LAUS for ~1,745 cities natively (effectively places ≥25,000 pop, 99.9% coverage at that threshold). For these cities the page shows a place-grain unemployment line above the county block. For smaller places (most of the long tail), only the county-grain LAUS is shown, labeled with the county name. CDPs have no place-grain LAUS by design.

What this is NOT for

• Not a city-level poverty rate for multi-county cities. Per-county listings only.
• Not a measure of city-level unemployment for places under 25k pop. County-grain fallback only.
• Not a basis for comparing SAIPE to PEP population numbers. Different production methodologies; they will not reconcile exactly.

Refresh cadence: annual, each May, alongside the existing Census PEP refresh.

14Cost of living (BEA RPP)

City profile pages surface a cost-of-living index from the U.S. Bureau of Economic Analysis Regional Price Parities (RPP) program. RPPs are spatial price indexes — they measure how much more or less a fixed basket of goods and services costs in a given metropolitan area or state relative to the U.S. average (= 100) in a given year. BEA constructs them from BLS Consumer Price Index price data, BLS Consumer Expenditure Survey expenditure weights, and Census ACS rent data.

Because BEA publishes RPPs at the metropolitan statistical area (MSA) and state grain — not at the city grain — we attach the figure to each city via a three-tier hierarchy:

• msa — the city's primary county sits in a CBSA that BEA covers at the MSA level. The MSA's RPP is used. This applies to the vast majority of cities in populated areas.
• state_nonmetro — the city's primary county is not in any MSA (or is in a micropolitan-only CBSA, which BEA rolls into the state non-metro figure). The state non-metropolitan portion RPP is used.
• state_total — defensive fallback if neither of the above resolves. Should be zero or near-zero rows in practice.

The grain tier is shown explicitly on every city page so readers know whether the figure applies to a named metro area or to a broader state portion. The city-to-CBSA join uses the OMB July 2023 CBSA delineation file (list1_2023.xlsx) bridged through the Census Place→County crosswalk already maintained for the economic section (§13). The build also asserts that every current-city row whose primary county is in a Metro CBSA resolves to a BEA MARPP row; if that ever fails, the data build stops instead of substituting a state-grain proxy.

Source: BEA Regional Price Parities · 2024 · released Feb 19, 2026 · U.S. Bureau of Economic Analysis

Source: OMB CBSA Delineation · July 2023 · U.S. Office of Management and Budget (hosted on Census.gov)

The four RPP categories

All Items

The composite index. 100 = U.S. average. Most cities use this as the headline number.

Goods

Tradeable consumer goods (food at home, apparel, vehicles, etc.). Tends to converge across areas; less variable than Rents.

Rents

Actual and imputed rental prices. The single largest source of geographic variation in U.S. cost of living. Constructed from Census ACS rent data.

Utilities

Electricity, natural gas, water, sewer, and other utility services consumed by households. Published by BEA as a separate line code (4); surfaced in our table as its own row. Highly geographically variable — Hawaii routinely runs ~50% above the U.S. average; cheap-electricity states like Louisiana run well below.

Other Services

Non-rent, non-utility services: healthcare, personal care, education, entertainment, food away from home, and financial services. BEA publishes utilities as a separate line code (4); we surface utilities as a fifth row above and exclude utilities from Other Services.

What this is NOT for

• Not an inflation measure. RPPs are cross-sectional — they compare areas in a single year, not the same area over time. A 2024 RPP of 112 means that area's prices are 12% above the U.S. average in 2024; it does not tell you how fast prices rose.
• Not a place-level number. BEA does not publish RPPs at the city grain. We do not synthesize a city-level index. The figure shown applies to the named MSA or state portion, not the city in isolation.
• Not a salary calculator. RPP tells you relative price levels, not whether a given salary is adequate. Income data comes from the ACS and SAIPE sections; combining them requires judgment this page cannot supply.
• Not a budget tool. Individual spending patterns differ; households with unusually high or low rent shares will experience a different effective COL than the RPP composite implies.
• Not precise for non-metro areas. BEA's non-metropolitan RPPs are based on thinner CPI samples and carry wider confidence intervals than metro-area figures.

Refresh cadence: annual. The current 2024 RPP release date is February 19, 2026; BEA lists the next release for December 10, 2026. Run python workflows/col/download_col.py --force && python workflows/col/build_col.py --verify and bump the year constant in both scripts. Full methodology: research/methodology-cost-of-living-2026-05-15.md.

15School districts (NCES EDGE)

City profile pages list the public school districts that serve each city, sourced from the National Center for Education Statistics' Education Demographic and Geographic Estimates (EDGE) Geographic Relationship Files. We ship the LEA-to-place crosswalk only in V1 — district names and outbound links to NCES. Enrollment, demographics, locale codes, and finance figures require the NCES Common Core of Data (CCD) and are deferred to a future workstream.

Source & vintage

GRF25 (LEA ↔ Place)

https://nces.ed.gov/programs/edge/data/GRF25.zip · TIGER 2025 boundaries / 2024–25 school year names · release pattern GRF[YY] each summer

GRF25 (LEA ↔ County)

Same zip, used as fallback for 8 consolidated city-county governments whose place GEOIDs don't appear in the LEA-place file (Indianapolis, Nashville-Davidson, Louisville/Jefferson, Athens-Clarke, Augusta-Richmond, Butte-Silver Bow, Greeley County KS, Milford CT)

The m:n join

One city can be served by many districts (Chicago: 11 districts in V1). One district can serve many cities (a county-wide district). This is not a defect — it reflects real geographic overlap. We sort districts within each city by landarea_in_place descending so the primary district is first, and we flag “edge overlap” slivers (intersections < 0.5 sq mi) so the UI can collapse them.

Coverage

19,476 of the 19,479 city rows available when the schools layer was built (99.98%) have at least one district mapping after applying place lookup, the consolidated-city county fallback, and the Milford CT special case. Three small incorporated places (Wheatland borough PA, Gann village OH, Glen Echo Park village MO — all under 600 pop) have no district intersection in TIGER 2025 and render without a schools panel.

What this is NOT for

• Not enrollment data. The GRF contains geographic intersection areas only. Enrollment, demographics, locale, and finance require NCES CCD and are deferred.
• Not a definitive enrollment-zone source. TIGER district boundaries differ from the within-district attendance zones a child is actually assigned to. Link out to NCES for authoritative information.
• Not a quality rating. No school-quality, performance, or funding judgment is implied or intended.
• Not BIE coverage. Bureau of Indian Education schools are federal and not represented in the GRF as state LEAs.

Refresh cadence: annual, each August, when NCES releases the new GRF (filename GRF[YY]).

16Climate (NOAA 1991–2020 normals)

Climate values on city profile pages come from the U.S. National Oceanic and Atmospheric Administration's 1991–2020 U.S. Climate Normals — the current canonical 30-year reference normals product. NOAA updates climate normals on a decadal cycle; the next release (2001–2030) is expected around 2031.

Hybrid product choice

We use a hybrid source path. For the contiguous 48 states + DC (~97.4% of cities), we sample NOAA's nClimGrid Monthly Gridded Normals v1.0 — a 4 km grid published by NCEI — at each city's Census Gazetteer internal point. For Alaska, Hawaii, Puerto Rico, U.S. Virgin Islands, and Pacific territories (and a small number of CONUS coastal-masked cells), we use the nearest GHCN station with 30-year normals from the v1.0.1 station product. Each city's row carries an explicit source_path (grid, station, station_far, or no_centroid) and a source_label string the page renders verbatim.

Honesty rule for Alaska

What we do not do

• No bilinear interpolation across grid cells. The grid is already an interpolated product; we sample at the nearest cell and cite the cell.
• No elevation correction. Places at unusual elevations relative to the grid cell representative inherit the grid's value as-is.
• No snowfall surfaced yet for CONUS. Snowfall is station-only in the source product and is not yet rendered on CONUS city pages. Cross-joining the nearest station is deferred to a future update.
• No anomaly vs. normal display. The 1991–2020 window ends 6 years ago and undercounts recent warming. We do not show "current year vs. normal" comparisons in V1 — only the official 30-year normal.

Unit conventions

Source product is in °C and millimeters; we store both metric and imperial columns so the public CSV is unambiguous. Display defaults to °F and inches, rounded to 1 decimal per NOAA's least_significant_digit attribute.

Refresh cadence: roughly static for the next 4–5 years. We re-pull annually to catch any v1.0.x point-release station corrections; the next major rebuild lands when NOAA publishes 2001–2030 normals (~2031).

17Internet broadband (FCC BDC)

City profile pages surface fixed broadband availability from the U.S. Federal Communications Commission's Broadband Data Collection (BDC). The current BDC layer was built against 19,479 city rows (4 fewer than the 19,483-row canonical city universe; the 4 missing cities had no FCC BDC service-area record at the city centroid at the time this layer was built and render without a broadband panel). For each row in that layer, we publish the number of providers (excluding satellite), the number of fiber providers, the share of broadband-serviceable units with ≥100/20 Mbps and ≥1 Gbps fixed service, the total broadband-serviceable units (BSL), a "+ satellite available" badge when satellite reports coverage, and the vintage stamp (bdc_as_of_date). 19,433 cities in that layer have BDC coverage; 46 of the smallest CDPs have no BSL locations and render without the panel. This layer refreshes on its own cadence.

Source & vintage

FCC BDC Census Place summary (per-state)

55 zips, one per state + DC + territories + US-wide. Field set: area_data_type × biz_res × technology rollup; total_units and speed_* share columns. We read the Total / R / Any Technology row for headline metrics. No provider_id in this file.

BDC Provider Summary by Geography (nationwide)

515,731 rows of (geography_type, geography_id, provider_id). We filter to geography_type='Census Place' and count distinct non-satellite providers per place.

BDC Fixed Broadband Provider Summary (nationwide)

3,821 rows of (provider_id, technology_code). We use this to identify satellite-only providers (every tech code they report ∈ 61) for exclusion, and fiber-capable providers (any tech code = 50) for the fiber count.

Current vintage

as-of June 30, 2025 (last revised 2026-04-29). Next expected publication: as-of December 31, 2025, ~June 2026.

The satellite-exclusion rule

The consolidated-city representation seam

The 8 consolidated city-county governments in our universe (Indianapolis, Nashville-Davidson, Louisville/Jefferson, Athens-Clarke, Augusta-Richmond, Butte-Silver Bow, Greeley County KS, Milford CT) use a SUMLEV=170 GEOID built from STATE + CONCIT. BDC publishes these cities under the SUMLEV=162 "balance" GEOID instead — for example, Indianapolis is 1836000 in our dataset but 1836003 in BDC. The build script uses geometry_source_geoid from cities.csv (already maintained for gazetteer geometry lookup) to bridge the seam. Every consolidated city resolves to a BDC row; this is asserted in the verifier.

The advertised-vs-measured speed disclosure

Coverage suppression

46 of the smallest Census-designated places have no Fabric locations and therefore no BDC row. For those we set coverage_status="no_bdc_record" and the city page suppresses the broadband panel entirely rather than misleadingly displaying "0 providers." This is the same suppression discipline as ACS sentinel-to-NULL mapping (§12) and the SAIPE "county attribution unavailable" footnote (§13).

What this is NOT for

• Not a measurement of actual delivered broadband speeds. Every speed in BDC is the ISP's advertised maximum.
• Not a quality rating. No customer satisfaction, reliability, latency, or outage data is implied.
• Not a real-time source. Each snapshot is from ~3-6 months prior to our build. New fiber buildouts and ISP withdrawals can shift between filings.
• Not a household count. "Broadband-serviceable units" are physical locations (parcels, MDU units, business sites), not occupied households or population.
• Not a price comparator. BDC has no pricing data.
• Not a basis for comparing speed shares across as-of dates. Speed thresholds and reporting rules have changed across BDC filings.

Refresh cadence: biannual. Monthly cron polls listAsOfDates, no-ops until a newer as-of date appears, then rebuilds. Next expected: as-of December 31, 2025, publishing ~June 2026.

18Natural risk (FEMA NRI)

City profile pages surface natural-hazard exposure from the U.S. Federal Emergency Management Agency's National Risk Index (NRI). NRI is the federal government's authoritative natural-hazard composite assessment — an expected-annual-loss model spanning 18 hazards, calibrated on 1996–2019 historical loss data, and published at the U.S. county grain.

Source & vintage

FEMA NRI Counties

NRI December 2025 v1.20.0 (the current published version). County-grain composite risk score (0–100), risk rating bucket, expected annual loss, social vulnerability, community resilience, plus 18 per-hazard score / rating pairs.

Join key

5-character county GEOID (state_fips + county_fips), bridged from city to county via the SAIPE-derived place_county_xwalk already maintained for the Economic section (§13). 5.7% of cities span 2+ counties; the city page renders one row per linked county.

The 18 hazards covered

Hurricane, Coastal Flooding, Riverine Flooding, Wildfire, Earthquake, Tornado, Hail, Heat Wave, Cold Wave, Drought, Tsunami, Volcanic Activity, Avalanche, Landslide, Ice Storm, Lightning, Strong Wind, and Winter Weather. Each hazard carries an independent score 0–100 and a rating bucket (Very Low / Relatively Low / Relatively Moderate / Relatively High / Very High), plus three no-rating sentinels (No Rating, Insufficient Data, Not Applicable) for hazards that do not occur at all in a county (e.g. Tsunami in Kansas).

The composite score

FEMA's composite "Risk Index" combines all 18 hazards using an expected-annual-loss methodology that multiplies historical loss frequency, exposure value of population + buildings + agriculture, social vulnerability, and community resilience. It is a relative ranking across U.S. counties, not an absolute property-level forecast. A "Relatively Moderate" county can still see a single catastrophic event in any given year.

The multi-county rule

Just like SAIPE and LAUS (§13), we never compute a single averaged risk score for cities that span multiple counties. New York City lists Bronx, Kings, New York, Queens, and Richmond counties separately. Manufacturing a population-weighted average would violate the same "no fabricated aggregates" rule that governs the V2019↔V2025 vintage seam (§6) — risk varies by hazard and a coastal county within a multi-county city can have very different hurricane exposure than an inland one.

Coastal-prominence rule

Cities with any linked county scoring HRCN_RISKS ≥ 40 get the Hurricane signal surfaced prominently above the per-county hazard table. This threshold matches the build pipeline's cities_with_hurricane_signal stat and corresponds to roughly the Atlantic + Gulf coastlines. Wave 5 ICP feedback (Tampa user) flagged the missing hurricane signal as the biggest gap on a coastal city's page.

What this is NOT for

• Not property-level. County grain only. Two adjacent properties on the same block can have very different parcel-level flood, fire, or wind risk; NRI does not resolve that.
• Not a forecast. NRI is calibrated on 1996–2019 historical loss data. It is a backward-looking expected-annual-loss model, not a forward-looking projection. Climate change, urban growth, and infrastructure investment shift forward-looking risk in ways the model does not capture.
• Not insurance pricing. Insurance carriers use proprietary catastrophe models with property-level inputs (construction type, elevation, distance to shore). NRI is a public-policy planning tool, not an underwriting tool.
• Not a city-grain product. FEMA does not publish NRI at the place grain. The per-county listing on city pages reflects that boundary honestly.
• Not an Alaska / Hawaii / territories comparator. NRI covers the 50 states + DC; coverage in Alaska is materially thinner than CONUS, mirroring the climate-data §15 honesty boundary.

Attribution

FEMA National Risk Index data is a work of the United States Government and is in the public domain (17 U.S.C. § 105). Recommended citation:

Source: U.S. Federal Emergency Management Agency, National Risk Index, December 2025 v1.20.0. County-grain risk values surfaced via the Census Place→County crosswalk maintained by Every City in the USA.

Refresh cadence: occasional. FEMA does not publish NRI on a fixed schedule. We re-poll the FEMA NRI data resources page on each annual data refresh and rebuild only when a newer release ships.

19Locator maps (Census TIGER/Line CB)

Each profiled city page carries a small state-outline thumbnail with a dot at the city's approximate location. The thumbnail is a pre-rendered PNG — there is no client-side mapping library, no tile server, and no zoom interaction. Its job is to anchor sense-of-place, not to support navigation.

Source & vintage

Census TIGER/Line Cartographic Boundary file

cb_2024_us_state_20m (2024 release, 1:20,000,000 scale, 187 KB zipped). Fetched from www2.census.gov/geo/tiger/GENZ2024; sha256 recorded in data/raw/tiger-cb-states/MANIFEST.json.

City coordinates

Reused from the 2025 Gazetteer centroid stored in cities.csv as (lat, lon). See §5 (Geographic enrichment) for the gazetteer join rule.

Projection & scale

Each state is drawn standalone in its own 480 × 360 px frame using a per-state equirectangular projection with cosine-corrected longitude. The longitude scale is multiplied by cos(centroid_lat) so the state's true east–west aspect ratio is preserved at that latitude (cosine correction is exact at the centroid and visually indistinguishable at the small scale of the thumbnail). No global projection is used, which sidesteps the Alaska/Hawaii inset problem entirely — every state is rendered on its own terms.

The state's bounding box is scaled to fit the frame with a 20 px inset and centered with letterboxing. The same projection used to draw the state outline is used to project the city's (lat, lon) into the same frame, so the dot lands on the state.

Inclusion rules

• 50 states + DC (51 outlines). U.S. territories (Puerto Rico, USVI, Guam, MP, American Samoa) are deferred in V1 — the cartographic boundary file ships them, but no profiled city is in a territory.
• Alaska Aleutian wrap-around dropped. The Aleutian island chain crosses the antimeridian, which would otherwise stretch Alaska's bounding box across ~360° of longitude and collapse the mainland to a sliver. We drop polygon rings whose mean longitude is east of –129° (well east of any mainland point) before projecting; the panhandle and full coast are preserved.
• Dot clamped to the frame. Census Gazetteer centroids occasionally land a hair outside the CB 1:20M outline (the boundary file is smoothed). We clamp the dot to the visible frame so it always renders on the state shape rather than on the white margin.

What these maps are NOT for

• Not for navigation. No streets, no neighborhoods, no labels — just state outline + dot. Use Google Maps for directions.
• Not for property identification. The dot is the city's gazetteer centroid, smoothed onto the 1:20M state boundary. It is positionally accurate at ± tens of miles, not parcel-level.
• Not for boundary disputes. The 1:20M cartographic boundary file is smoothed for thematic mapping. Use the 1:500k or full TIGER/Line edges if you need accurate state lines at zoom.
• Not at-scale across states. Each state is rendered standalone — Rhode Island fills its frame at the same visual size as Texas does. The maps answer "where in the state?", not "how big?".

Attribution

Census TIGER/Line cartographic boundary files are works of the United States Government and are in the public domain (17 U.S.C. § 105). Recommended citation:

Source: U.S. Census Bureau, Geography Division, 2024 Cartographic Boundary File cb_2024_us_state_20m (1:20,000,000 scale).

Refresh cadence: decadal. Census re-publishes the CB files infrequently, typically alongside the decennial census. Re-run workflows/maps/download_tiger_states.py --force followed by build_state_outlines.mjs after a new release.

20State energy prices (EIA)

City profile pages surface a small state-grain energy panel beneath the BEA cost-of-living section: average residential electricity rate, average residential natural-gas rate, and average retail gasoline price. The figures come from the U.S. Energy Information Administration's open data API and complement BEA's RPP Utilities component by exposing the underlying state-level price levels that drive utility-cost differences.

Grain & vintage labeling

Every energy figure is explicitly state-grain (electricity, natural gas) or PADD-region-grain (retail gasoline). EIA publishes residential electricity and natural-gas prices monthly at the state level and retail gasoline weekly at the PADD region level. The page surfaces the single most-recent observation per series with its observation date — month for electricity and natural gas, week-ending for gasoline. We do not interpolate to a place grain; the city's state (and corresponding PADD for gasoline) determines which row is shown.

Source: EIA State Energy Prices · Most-recent observation · monthly (electricity, natural gas) · weekly (gasoline) · U.S. Energy Information Administration

What this is NOT for

• Not a per-household rate. Residential averages are statewide and pooled across providers; individual utility tariffs vary by provider, plan, tier, and time-of-use.
• Not a place-level number. EIA publishes at state and PADD grain; we do not synthesize a city-level energy price even where one would be intuitive.
• Not an inflation tracker. V1 ships single most-recent observations only. Comparing two different-vintage observations as "year-over-year" is not supported by this layer — use BEA RPP component changes with grain caveats for that purpose.
• Not the same as a utility bill. The retail electricity price is a marginal rate per kWh; a household's actual monthly bill depends on consumption, fixed customer charges, riders, taxes, and climate-driven seasonality.

Refresh cadence: monthly via daily-runner cron. Full methodology: research/methodology-energy-2026-05-18.md.

21Fair Market Rents (HUD)

City profile pages surface a row for HUD Fair Market Rent (2-bedroom) next to the ACS median gross rent in the Housing section. FMR is the 40th-percentile gross rent (rent + utilities) used by the U.S. Department of Housing and Urban Development to administer the Section 8 Housing Choice Voucher program. HUD publishes FMRs annually at the metropolitan area / non-metropolitan county level, typically each October for the next federal fiscal year.

Grain & join

HUD publishes FMR at the HUD FMR Area level — usually a Metropolitan Statistical Area for metro areas, a single non-metropolitan county otherwise. We join each city to its FMR area through the same Census 2020 Place→County crosswalk used for the COL pipeline (§14). Multi-county cities use the primary-county rule — the page surfaces a one-line caveat when a city spans more than one FMR area, identical to the multi-CBSA-disagreement caveat used by the BEA RPP layer.

Source: HUD Fair Market Rents + Small Area Fair Market Rents · FY2026 · annual · U.S. Department of Housing and Urban Development

FMR vs ACS median gross rent

FMR and the ACS median gross rent are different measurements of different things. FMR is a 40th-percentile gross rent (rent plus tenant-paid utilities) constructed by HUD to ground voucher policy; it updates annually and reflects more recent rental-market conditions than the ACS 5-Year window. ACS median gross rent reflects the actual rents paid by survey respondents over a five-year window, lagging current-market conditions by 2–3 years on the trailing edge. We surface both side-by-side; FMR is not "the right" rent number and ACS is not wrong — they answer different questions on different timelines, and the gap between them is itself information.

SAFMR ZIP-grain coverage

HUD publishes Small Area Fair Market Rents (SAFMRs) for metro areas only. SAFMR ZIP-grain rents are available for approximately 11,279 cities (58% of the city universe); the remaining 8,204 cities (42%) fall back to county-grain HUD FMR. The housing budget row in the F1 single-adult and F2 family-of-four panels uses SAFMR ZIP-grain when available, county-grain FMR otherwise. Cities with SAFMR coverage show the ZIP-code-weighted rent; cities without show the HUD FMR Area rate. Coverage grain is labeled on every page where the figure appears.

What this is NOT for

• Not a market rent. FMR is a statutory benchmark, not what an individual unit lists for on Zillow today.
• Not a place-level number. FMR is FMR-area-grain; we never synthesize a city-level FMR even when a city is the dominant population center of its FMR area.
• Not a forecast. FY values are set in advance for the next HUD fiscal year (published each October), not a real-time market signal.
• Not a voucher eligibility tool. Eligibility for the Section 8 program depends on income limits, household size, and local PHA waitlist policy. FMR alone does not determine voucher amount or eligibility.

Refresh cadence: annual, each October, when HUD publishes FMRs for the next federal fiscal year. Re-run python workflows/housing/download_hud_fmr.py followed by python workflows/housing/build_hud_fmr.py --verify, bumping the FY year constant in both scripts beforehand. Full methodology: research/methodology-fmr-2026-05-18.md.

22Tax burden (Census state & local finances)

City profile pages surface a Tax burden sub-panel inside the Cost of living section showing combined state + local tax revenue per capita across five categories: total taxes, property, sales & gross receipts, individual income, and corporate income. The U.S. Census Bureau Annual Survey of State and Local Government Finances is the only federally-produced cross-state-comparable measure that combines state and local government revenue, which is what makes "tax burden" comparisons meaningful when state and local responsibilities differ across the country.

Grain & join

Tax burden is published at state grain only — one figure per state + DC. No federal program publishes a per-city tax burden, and we do not invent one. The page label always shows the state name explicitly so the reader does not mistake the figure for city-level data. Each city joins to its state's row by 2-letter postal abbreviation; per-capita figures are computed by dividing the Census state+local amount (in thousands) by the Census Population Estimates Program (PEP) mid-year state population for the same fiscal year, so numerator and denominator are on the same vintage seam.

Tennessee & New Hampshire

The Census Annual Survey records realized revenue, not whether a tax is structurally on the books. Tennessee shows a small positive individual-income-tax-revenue figure for FY2022 because the Hall Tax on interest and dividends (repealed effective January 1, 2021) still produced residual collections from delinquent payments and audit assessments. New Hampshire shows a substantial figure because its Interest & Dividends Tax was still in effect through 2024 (repealed effective January 1, 2025). Both states are correctly classified as "no broad-based income tax" by the income-tax brackets layer (§23) — but the tax-burden layer publishes what Census collected, not what the bracket structure looks like.

Source: Census Annual Survey of State and Local Government Finances · FY2022 · annual · U.S. Census Bureau, Economic Programs Directorate

What this is NOT for

• Not a household tax calculator. Per-capita revenue is total dollars divided by total residents, not the slice an individual household pays.
• Not a marginal-rate indicator. For state income tax brackets see §25 (Income tax). For combined sales tax rates see §26 (Sales tax).
• Not normalized for tax exporting. Severance taxes (AK, WY) and tourism taxes (NV, HI) are partially paid by non-residents; the per-capita figure attributes all revenue to in-state residents.
• Not combined into a composite affordability score. Every figure is a single sourced number with its own grain label.

Refresh cadence: annual, each spring, when Census publishes the next fiscal-year State & Local Summary Table. As of 2026-05 the most recent published state-grain vintage is FY2022; FY2023 has unit-level microdata only, and the FY2024 First Look is national-only. Re-run python workflows/tax/download_gov_finances.py --force followed by python workflows/tax/build_gov_finances.py --verify, bumping the FY constant in both scripts beforehand. Full methodology: research/methodology-gov-finances-2026-05-21.md.

23State income tax (state DOR)

City profile pages surface two state income tax rows inside the Tax burden sub-panel: the top marginal rate for a single filer, and the effective rate at $75,000 of income after the state standard deduction. The canonical authority is each state's Department of Revenue (50 states + DC) — official tax forms and rate schedules. The Tax Foundation's annual compilation is used as a cross-check, never as the primary source. If a state DOR rate disagrees with the cross-check, the DOR wins and the discrepancy is logged in the build manifest.

Grain & data shape

State-grain only. The committed reference at workflows/tax/income_tax_brackets.json carries one entry per state + DC with the full single-filer bracket schedule, standard deduction, and primary source URL. Manually-maintained as a manual_overlay source per DATA_PIPELINE.md §3 — tax brackets change legislatively and often retroactively, so we do NOT scrape state DOR pages. Operator updates the JSON each January after states finalize their TY rate schedules.

The nine no-income-tax states

Seven states have never had a broad-based individual income tax: AK, FL, NV, SD, TX, WA, WY. Two more recently joined: Tennessee (Hall Income Tax on interest & dividends repealed effective January 1, 2021) and New Hampshire (Interest & Dividends Tax repealed effective January 1, 2025). All nine show "no state wage income tax" on the page. (Washington has a 7% capital-gains tax above ~$262k that is excluded from this dataset, which covers wage income tax only.)

Local income taxes are excluded

Several jurisdictions impose additional local income taxes on top of the state rate — NYC resident tax (3.078%–3.876%), Yonkers surcharge, Portland-OR Metro Supportive Housing tax + Multnomah County Preschool For All, Maryland county "piggyback" tax, Philadelphia wage tax (3.75% resident), and dozens of Ohio/Kentucky/Michigan cities. V1 excludes all of these because they require city-level data that breaks the state-grain contract and is fragmented across dozens of jurisdictions with inconsistent rules. A page reader in NYC sees "10.90% top NY state rate" — the additional NYC resident tax is documented on the page as an explicit caveat.

Effective rate at $75k single filer

The build computes effective rate as tax_owed_at_75k_taxable_income / 75000, after applying each state's published single-filer standard deduction. $75,000 is roughly the U.S. median household income. The figure is illustrative only: it assumes single filer, no itemized deductions, no credits, no retirement-income exclusions, no AMT. An individual taxpayer's actual liability will differ. The page row labels these assumptions explicitly.

Source: State Departments of Revenue — Individual Income Tax Rate Schedules · TY2025 · annual · State Departments of Revenue (50 states + DC), with Tax Foundation cross-check

What this is NOT for

• Not a household tax calculator. Effective rate at $75k is illustrative; an individual taxpayer's actual liability depends on filing status, deductions, credits, and other-state income.
• Not a measure of total state+local tax burden. For combined per-capita state+local revenue see §22 (Tax burden). For sales tax see §24 (Sales tax).
• Not inclusive of local income taxes. See the local-income-tax caveat above.
• Not inclusive of investment-income-only taxes. Washington's 7% capital-gains tax is excluded.
• Not combined into a composite affordability score.

Refresh cadence: annual, each January, after state legislatures finalize TY rates and state DORs publish updated forms. Operator updates workflows/tax/income_tax_brackets.json by hand, then runs python workflows/tax/download_income_tax.py --force && python workflows/tax/build_income_tax.py --verify. The auto_update_policy: warning_hold in the registry forces a manual review pause on every change. Full methodology: research/methodology-income-tax-2026-05-21.md.

24State & local sales tax (Tax Foundation)

City profile pages surface three sales tax rows inside the Tax burden sub-panel: the statutory state sales tax rate, Tax Foundation's population-weighted average local sales tax rate within the state, and their combined total. The state-level statutory rate comes from each state's published sales tax page; the population-weighted local average is from Tax Foundation's annual "State and Local Sales Tax Rates" study — no federal agency publishes this aggregation, so Tax Foundation is the canonical source for the local component.

Grain & data shape

The combined rate is the "how much sales tax does the average resident of this state pay" answer — a state-grain figure. Not the rate at any specific point of sale. Birmingham AL's actual combined rate (~10%) is higher than Alabama's population-weighted state-average (9.29%); a reader at a city page should not interpret the figure as the rate they would pay at any specific store. The page caveat below the table makes this explicit.

The five no-state-sales-tax states

Five states have no statutory state sales tax: OR, MT, NH, DE, AK. Of these, only Alaska allows local sales taxes statewide (Juneau, Kodiak, etc.) — so AK has state_rate = 0 but avg_local_rate > 0. Montana has a small "resort tax" in a few resort areas (Whitefish, Big Sky) which is excluded from V1 because it applies only in narrow geographies. New Hampshire has meals & rooms and other excise taxes, not a general sales tax. Delaware has a gross-receipts tax on businesses, not a register-visible sales tax.

Special-case rates

Hawaii's 4% General Excise Tax (GET) is technically a gross-receipts tax on businesses, but Tax Foundation reports it as the state's effective sales tax for cross-state comparison purposes. New Mexico's 4.875% Gross Receipts Tax is similarly treated. Louisiana mid-year hiked its state rate effective January 2025; we use the year-end rate. New Jersey has a slightly negative population-weighted local average because Urban Enterprise Zones charge 50% of the state rate, dragging the state-wide pop-weighted average below zero.

Source: Tax Foundation — State and Local Sales Tax Rates (annual) · TY2025 · annual · Tax Foundation (population-weighted local averages) + state statute (state rate)

What this is NOT for

• Not a point-of-sale calculator. Combined rate is a population-weighted state average; specific local rates vary.
• Not comprehensive. Excludes excise taxes (gasoline, tobacco, alcohol), selective sales taxes (hotels, meals, car rentals), use tax, and special district taxes.
• Not a measure of total state+local tax burden. See §22 (Tax burden) and §23 (Income tax).
• Not combined into a composite affordability score.

Refresh cadence: annual, each January, when Tax Foundation publishes its updated "State and Local Sales Tax Rates" annual study. Operator updates workflows/tax/sales_tax_rates.json with new entries, bumps tax_year + last_verified_date, then runs python workflows/tax/download_sales_tax.py --force && python workflows/tax/build_sales_tax.py --verify. Full methodology: research/methodology-sales-tax-2026-05-21.md.

25Occupational wages (BLS OEWS)

City profile pages surface an Occupational wages sub-panel inside the Local economy section showing what workers earn in the city's metropolitan area. Top 10 occupations by employment plus six curated benchmark occupations: registered nurse, software developer, elementary school teacher, general and operations manager, retail salesperson, and heavy/tractor-trailer truck driver. Data comes from the U.S. Bureau of Labor Statistics' Occupational Employment and Wage Statistics (OEWS), May 2025 reference period.

Grain & join

OEWS publishes at the metropolitan area level (CBSA or NECTA), not place-grain. Each city joins to its metro through the same Census 2020 Place→County crosswalk and OMB CBSA delineation used by the BEA RPP cost-of-living layer (§16) and HUD FMR (§21). Multi-county cities use the primary-county rule; an oews_cbsa_disagreement flag fires when a city spans 2+ different CBSAs and the renderer shows a caveat. The MSA file covers ~9,500 metro-assigned cities; the remaining ~10,000 non-metro cities show "not available" because BLS does not publish per-occupation wage data at the non-metro grain in this file.

Suppressed wages

BLS suppresses wage cells when the underlying sample is too small to report reliably (typically employment below ~50). Suppressed cells stay NULL in the processed CSV — never zero, never imputed. The renderer shows "—" for suppressed wage cells so the user sees an honest gap rather than a fabricated number. In small metros, some benchmark occupations may be suppressed; the page renders 3-5 benchmarks instead of all 6.

The 3-year rolling-panel design

OEWS surveys ~1.1 million establishments over a 3-year cycle in 6 panels. The published May 2025 estimate is the rolling 3-year average of panels covering May 2023 through May 2025. This means year-over-year wage changes are unreliable (the underlying data overlaps), so we never compute or display them. We cite the reference period explicitly on every figure.

Source: BLS Occupational Employment and Wage Statistics (OEWS) · May 2025 · annual · U.S. Bureau of Labor Statistics

What this is NOT for

• Not a salary negotiation tool. Wages are metro-area medians; individual employers' pay scales differ.
• Not a measure of total compensation. Excludes benefits, bonuses, profit-sharing, equity, and self-employment income.
• Not a cost-of-living adjustment factor. For metro-grain price parities see §16 (BEA RPP).
• Not a non-metro source. ~10,000 cities show "not available."
• Not a forecast. May reference period published ~10 months later; cannot be projected forward.
• Not combined into a "purchasing power" composite.

Refresh cadence: annual, each March/April, when BLS publishes the next May vintage. Bump the OEWS_VINTAGE_YEAR + OEWS_REFERENCE_PERIOD constants in workflows/wages/build_oews.py and the YY-keyed URL in workflows/wages/download_oews.py, then run python workflows/wages/download_oews.py --force && python workflows/wages/build_oews.py --verify. Full methodology: research/methodology-oews-2026-05-21.md.

26Food costs & access (USDA)

City profile pages surface a Food & grocery access sub-panel inside the Cost of living section combining two USDA sources: the Cost of Food Plans (national reference budgets, published monthly by USDA Center for Nutrition Policy and Promotion) and the Food Environment Atlas (county-grain food access indicators, published irregularly by USDA Economic Research Service). The Thrifty Food Plan is the basis for SNAP benefit calculations and carries federal authority.

National food plans vs county food access

The four USDA Food Plans (Thrifty, Low-Cost, Moderate-Cost, Liberal) are national reference budgets — what USDA's market basket models suggest a healthy diet costs at each tier. We surface the family-of-4 monthly figure for Thrifty, Moderate-Cost, and Liberal plans (USDA's reference family is: Male 19-50 or 20-50, Female 19-50 or 20-50, Child 6-8, Child 9-11; we sum weekly costs × 4.33 weeks/month). The values are identical for every city — we do not apply BEA Regional Price Parities or any other regional adjustment to manufacture local food prices. Alaska and Hawaii shoppers will see substantially higher actual prices than the national reference; that caveat appears on every food panel.

The Food Atlas provides three county-grain indicators: grocery stores per 1,000 population (STORES.GROCPTH20, 2020), low food-access population share (ACCESS.PCT_LACCESS_POP19, 2019), and SNAP participation rate (ASSISTANCE.PCT_SNAP22, 2022). USDA's "low access" follows the ERS definition — 1 mile urban / 10 miles rural to the nearest supermarket. Suppressed cells (USDA encodes them as -9999) stay NULL and render as "—" on the page; the renderer never coerces NULL to zero.

Atlas join

Cities join to Atlas data via the primary county, using the same Census 2020 Place→County crosswalk used by every other county-grain layer in this project. Multi-county cities use the first-listed county's Atlas values and set food_atlas_disagreement = True for transparency.

Source: USDA Cost of Food Plans (Thrifty, Low-Cost, Moderate-Cost, Liberal) · Monthly · latest 2025 · USDA Center for Nutrition Policy and Promotion

Source: USDA Food Environment Atlas · Variables span 2019-2022 · USDA Economic Research Service

What this is NOT for

• Not a local grocery-price index. USDA's plans are national reference budgets, not actual prices in local stores. We surface them as the federal cost reference, not as a local food price.
• Not a recommended household budget. Plan levels describe what USDA's models suggest is achievable at each cost tier, not what any specific household should spend.
• Not an actual-spending measure. For actual food spending see BLS Consumer Expenditure Survey (not in V1).
• Not inclusive of Alaska / Hawaii premiums in V1. Mainland U.S. values are used for all cities; AK and HI premium tables exist and are a Tier 3 expansion.
• Not a nutrition quality measure. Plans are cost references for a healthy market basket; the Atlas is access/density. Neither measures what residents actually eat.
• Not combined into a composite "food cost" score.

Refresh cadence: quarterly for food plans (USDA publishes a new month each month; quarterly pull is sufficient); annually check for new Food Atlas release (releases are ~every 2-3 years). Re-run python workflows/food/download_food_plans.py --force && python workflows/food/download_food_atlas.py --force && python workflows/food/build_food.py --verify. Full methodology: research/methodology-food-2026-05-21.md.

27Monthly household budget

City profile pages surface a Monthly Household Budget Benchmark sub-panel showing the estimated monthly cost of basic needs for a single adult renting a 1-bedroom unit. The composite is a deterministic, federal-data calculation modeled after the component structure of the MIT Living Wage Calculator, with three deliberate departures: BEA Regional Price Parities substitute for Feeding America’s county-level food adjustment (a federal public-domain product replaces a nonprofit source with unclear commercial-use terms); all commercial and nonprofit-proprietary sources are omitted (federal sources only: BLS CEX, HUD FMR, USDA CNPP, BEA RPP, EIA, IRS, state DORs); and an iterative federal+FICA+state tax solver replaces any third-party policy engine. The V1 family composition is single adult, 1-bedroom rental. No composite score is published; components are presented individually with grain labels on every row.

What this dataset is NOT

• Not a wage figure. We never divide the total by 2,080 working hours or recommend a salary. For a wage-framed calculation see the MIT Living Wage Calculator; this product computes a monthly budget, not an hourly or annual wage.
• Not a recommended salary. The figure is what a modeled household would spend on basic needs. It is not financial advice and not a salary recommendation.
• Not a poverty threshold. The U.S. Census Supplemental Poverty Measure and HHS Federal Poverty Guidelines are the canonical federal poverty references.
• Not a composite cost-of-living index. Components are surfaced individually with grain labels; we never publish a weighted single-number index.
• Not adjusted for individual circumstances. Single filing status, no dependents, no homeowner deductions, no employer-subsidized healthcare beyond what BLS CEX captures as the household-paid portion.
• Not tax advice. The tax line is a deterministic estimate for the modeled household; consult a tax professional for actual liability.

Component vintages

Component formulas (summary)

All formulas operate on monthly figures. The composite total is the sum of seven non-tax monthly components plus an iteratively-solved tax line.

Tax solver

The tax line is computed by an iterative fixed-point solver: given the pre-tax basic-needs subtotal for a city, the solver finds the gross annual income at which gross − federal_income_tax(gross) − FICA(gross) − state_income_tax(gross) equals the subtotal. Federal brackets follow IRS Rev. Proc. 2024-40 (TY2025, single filer, $15,000 standard deduction). FICA: 6.2% Social Security on the first $176,100 plus 1.45% Medicare on all gross income. State income tax: per-state bracket schedules from workflows/tax/income_tax_brackets.json; the nine no-income-tax states (AK, FL, NV, SD, TX, WA, WY, TN, NH) return $0. The solver does not model EITC, Child Tax Credit, ACA premium subsidies, itemized deductions, local income taxes, or capital gains. Convergence tolerance: $1/year; maximum 50 iterations; verified to converge in 4–6 iterations for all modeled states.

Limitations

1. Single composition only in V1. Family-of-4 is scoped to a future expansion.
2. Childcare not modeled in V1. Single adult has no childcare line.
3. Employer healthcare premiums not separately modeled in V1. Out-of-pocket BLS CEX components only; employer-sponsored premiums are a future expansion.
4. Transportation uses CEX national average × state RPP, not county-level vehicle miles traveled. A future expansion will replace this with a derived ACS + BTS LATCH + IRS mileage rate model.
5. ISP retail prices have no federal sub-state source. We use BLS CEX national average; no workaround exists at this time.
6. Auto insurance has no federal sub-state source. Embedded inside CEX “Other vehicle expenses” at national grain.
7. Local income taxes not modeled. New York City, Philadelphia, and approximately 4,000 other U.S. local income tax jurisdictions are excluded.
8. EITC and ACA premium subsidies not modeled. Under-states the tax burden reduction available at low income.
9. CEX rows are per-consumer-unit average, not per-single-adult. The 2024 average consumer unit contains 2.4 people and 1.9 vehicles. CEX-derived rows are used as published, producing an over-estimate for single-adult compositions in categories that scale with household size. This decision is binding for V1; it matches the approach used by MIT and EPI for the same compositions.
10. No geographic interpolation. State-grain stays state-grain. County-grain stays county-grain. National-grain CEX adjusted by state BEA RPP is labeled “national, state price-adjusted” — never “city cost of X.”

Methodology informed by: MIT Living Wage Calculator (Glasmeier / MIT URPS; informational citation only — we do not reproduce MIT’s computed figures) · EPI Family Budget Calculator (informational citation only — we do not reproduce EPI’s computed figures)

Full methodology: research/methodology-household-budget-2026-05-22.md

28Local income tax

The Monthly Household Budget Benchmark extends the federal + FICA + state income tax solver with per-city resident local income tax. Approximately 3,100+ U.S. jurisdictions across Pennsylvania, Maryland, Indiana, and Ohio are covered by five automated state-government source pulls (Tier A). Thirteen high-population cities with bespoke rate structures are maintained in a hand-verified override file (Tier B). Cities in local-income-tax states not covered by Tier A or B receive a “not modeled” label with a link to the relevant state Department of Revenue (Tier C).

What this dataset is NOT

• Not tax advice. This is a deterministic benchmark estimate using published statutory rates for a modeled single-filer scenario. Consult a tax professional for actual liability.
• Not nonresident-rate modeling. The benchmark assumes the modeled adult lives and works in the same city. Nonresident rates (for example, a New Jersey resident commuting to Philadelphia) are documented in source data but not applied.
• Not credit-for-tax-paid modeling. Some states allow a credit for tax paid to another jurisdiction. The solver does not model this; it assumes work jurisdiction equals residence jurisdiction.
• Not comprehensive coverage of Tier C jurisdictions. Kentucky (most counties beyond Louisville/Lexington), Alabama (most cities beyond Birmingham), West Virginia (flat-fee cities), Colorado (flat-dollar occupational privilege taxes), and several other states are documented gaps in V1.
• Not modeling West Virginia flat-fee taxes. Charleston, Huntington, Wheeling, and other WV cities levy weekly fixed-dollar fees (typically $2–$5/week), not percentage rates. These are documented but not applied in the solver.
• Not modeling the Newark NJ employer payroll tax. Newark’s 1% levy is an employer-side payroll tax, not a personal income tax on residents. It is out of scope for the household budget benchmark.

Three-tier architecture

Both MIT Living Wage Calculator and EPI Family Budget Calculator confirm in their published FAQs that they do not model local income taxes. This dataset models the meaningful majority of local-income-tax-impacted U.S. residents using only federal and state government public-domain publications.

Methodology informed by: MIT Living Wage Calculator (Glasmeier / MIT URPS; informational citation only — we do not reproduce MIT’s computed figures) · EPI Family Budget Calculator (informational citation only — we do not reproduce EPI’s computed figures)

Full methodology: research/methodology-local-income-tax-2026-05-22.md

29Family-of-four composition

City profile pages show a second Monthly Household Budget Benchmark panel alongside the single-adult panel (§27): a family of four, two adults working, two children (ages 4 and 8), 3-bedroom rental. This is the same flagship pair published by MIT and EPI — but computed independently from federal public-domain sources only, with no commercial or nonprofit-proprietary data.

The family-of-four panel uses Married Filing Jointly (MFJ) tax status and models the federal Earned Income Tax Credit (EITC) and Child Tax Credit (CTC, including the refundable Additional Child Tax Credit) at TY2025 parameters. No state EITC supplements or state-level CTCs are modeled in V1 — those are deferred to a future expansion.

What this dataset is NOT

• Not a wage figure. The total is what a modeled family would spend on basic needs — not a recommended salary, not a hourly wage, not a “family-supporting wage.”
• Not a recommended salary. The figure is a basic-needs budget benchmark. It is not financial advice.
• Not inclusive of childcare subsidies. CCDF, Head Start, state pre-K subsidies, employer childcare benefits, and the Child and Dependent Care Tax Credit are all excluded. Childcare cost is gross, pre-subsidy.
• Not modeling a single-earner variant. Both adults are modeled as working. A non-working-spouse variant (with no childcare line) is deferred to F5+.
• Not modeling state EITC or state CTC supplements. California, New York, Maryland, and other states have state-level credits. Federal EITC + CTC only.
• Not a real-time childcare price. NDCP 2022 data is 3–4 years old; the national CPI adjustment is a national multiplier — counties where childcare rose faster or slower than the national average are misstated.
• Not applicable to home-based or nanny care. Center-based care anchor only, matching the MIT and EPI methodology.

Composition anchors

Childcare line

The childcare row is sourced from the U.S. Department of Labor National Database of Childcare Prices (NDCP) 2022, the largest federal dataset of county-level childcare prices. NDCP publishes two relevant age bands: preschool (ages 3–5, MCPRESCHOOL anchor) and school-age (ages 5–12, MCSCHOOL anchor); we use point ages 4 and 8 as representative within each band. The two center-based weekly rates are summed and converted to monthly cost using 4.33 weeks/month ((MCPRESCHOOL + MCSCHOOL) × 4.33). The NDCP county figure is inflated to April 2026 dollars using the BLS CPI Child Care and Nursery School subindex (CUUR0000SEEB03), with a verified inflation factor of 1.2293 (January 2022 → April 2026: index 397.290 ÷ 323.184).

The processed childcare build records IN, PA, and VT as states with no matched NDCP preschool county coverage in data/processed/childcare/build_manifest.json::decisions_log::missing_coverage_states. The family-of-four childcare row also requires both the preschool and school-age center-based anchors for the city's primary county, so a city can be marked childcare_grain='not_modeled' when either anchor is missing. Those city rows show "not modeled — county outside NDCP 2022 coverage" for the childcare row. The childcare figure is gross cost — no subsidy is modeled.

Food / childcare age-band mismatch

The USDA family-of-4 food plan reference uses children aged 6–8 and 9–11 (the standard USDA reference family). Our childcare anchor uses children aged 4 and 8. This creates a small inconsistency: the food cost is for slightly older children than the childcare cost. The magnitude is approximately 3–5% on the food line (children 4–5 eat somewhat less than 6–8). This is a documented, accepted limitation — the same inconsistency exists in the MIT Living Wage Calculator. Resolving it would require a non-standard USDA food plan age-band selection that is not published in the federal CNPP tables.

Tax solver — MFJ extension

The iterative tax solver from §27 is extended for MFJ status. The solver finds the gross combined income at which gross − federal_MFJ_tax(gross) − FICA(gross) − state_MFJ_tax(gross) − EITC(gross) − CTC(gross) equals the pre-tax subtotal. Federal EITC and CTC are modeled at TY2025 parameters (phase-in / phase-out curves for 2 qualifying children). The Child Tax Credit operative value for TY2025 is $2,200 per qualifying child (vs. the $2,000 TCJA baseline; the $200 differential reflects inflation indexing per IRC §24(h)(2)(B) and IRS Rev. Proc. 2024-40). The F2 family-of-four composite applies the operative $2,200 value. FICA applies to the combined gross as if earned equally by both adults for the wage base limit calculation. Convergence tolerance: $1/year; maximum 50 iterations.

F1 reproducibility guarantee

The single-adult F1 budget is byte-identical between the initial F1 ship and the family-of-four expansion. This is enforced by _total_tax_single(), an internal helper in the tax solver that uses the frozen F1 code path. The family-of-four verifier asserts a SHA-256 byte-equality between the post-F1 place_household_budget.csv and the family-of-four single-adult rows of place_family4_budget.csv. Any family-of-four build that breaks F1 byte-identity fails the verifier.

Full methodology: research/methodology-childcare-2026-05-28.md · research/methodology-household-budget-2026-05-22.md

See also: §27 Monthly household budget (single adult)

30Cost-of-living URL split

The cost-of-living data layer is rendered on a dedicated sub-page per city (/cities/<slug>/cost-of-living/) rather than inline on the main city profile. This section documents the split decision, the criteria used, and the methodology pointers that remain valid across both URLs.

Criteria for the split

The COL layer passes a four-criteria threshold: (a) its own search demand (<city> cost of living queries, 2,000–7,000/mo per top city), (b) three or more distinct federal data sources (BEA, HUD, EIA, USDA, IRS, state DOR, Tax Foundation, DOL NDCP, BLS CEX, Census Gov Finances), (c) eight or more data rows (30+), and (d) a distinct relocation-intent user who is not the same as the population/Census user. No other data layer on the city profile passes all four criteria; this is a conservative, single-topic split.

What moved to the sub-page

BEA RPP all-items + categories (§14), ACS owner costs — B25088 and B25103 (§12), EIA state energy prices (§20), Census Gov Finances state tax burden (§22), state income tax brackets (§23), state + local sales tax (§24), local income tax for F3-modeled jurisdictions (§28), USDA food plans + Food Atlas (§26), single-adult household budget (§27), family-of-four household budget (§29), and cross-cutting methodology footnotes.

What stayed on the hub city profile

Population (PEP V2025 + V2019), demographics (ACS), income & poverty summary (ACS B19013/B19301/B17001), housing market (ACS B25077/B25064/B25003/B25070 + HUD FMR + HUD SAFMR), local economy (SAIPE + LAUS + QCEW + OEWS), schools (NCES), climate (NOAA), risk (FEMA), broadband (FCC), travel (USGS + OurAirports), and a 6-row Cost of living summary card with a CTA to the sub-page.

Scope

The sub-page is pilot-scoped to the ~50 currently-built city profiles. Smaller cities continue to render cost-of-living data inline on the city profile until Search Console evidence justifies broader expansion.

Methodology pointer continuity

All existing anchor IDs on this page — #cost-of-living, #fmr, #energy, #food, #tax-burden, #income-tax, #sales-tax, #household-budget, #family-of-four-budget, #local-income-tax — remain valid and continue to receive deep-link traffic from both the hub city profile and the cost-of-living sub-page footnotes. Nothing on this methodology page was renamed or removed.

See also: §14 BEA Regional Price Parities · §27 Monthly household budget · §29 Family-of-four composition