Benchmarks vertical

What's in it

BuildCalc API's benchmarks vertical exposes derived typical duration + cost ranges so AI agents and developers can ground project-cost reasoning against federal data instead of paywalled industry reports (NAHB Cost vs Value, RSMeans Light Construction, Dodge).

• 15 standardized project types: new construction SFH; kitchen + bath remodels (midrange + major); exterior replacements (roof / siding / window / painting); interior systems (flooring / HVAC / electrical panel); additions (deck / garage / basement finish).
• 5 geography tiers per project: national + msa_large (>1M pop) + msa_medium (250k-1M) + msa_small (<250k) + rural (non-MSA counties).
• 4-level confidence taxonomy: measured (direct federal row) / derived (federal-data formula) / derived_industry_method (BuildCalc-curated scope + federal labor) / interpolated (regional fallback).
• Per-row metadata: cost_usd_p25/p50/p75 (base year stamped), duration_days_p25/p50/p75, labor_pct + materials_pct, labor_hours_breakdown (per-trade JSONB), trade_dependencies (array for ANY() filter), methodology_id + methodology_version for audit reproducibility.
• Federal-only sources: Census C30 + Census BPS + Census BCC price index + BLS OEWS labor wages (via Phase 6 cost_labor_oews) + BLS Productivity + EIA RECS (HVAC) + HUD SOC duration. NO scraping. NO paywalled benchmarks reproduced.

All endpoints carry the data:benchmarks tag so they're exposed through the MCP server alongside codes, calculators, and costs.

Auth + rate limits

Same as the rest of the API — Authorization: Bearer bcapi_… header, per-tier rate limits, metered overage billing. Every authenticated request to /v1/benchmarks/* records one usage event.

Endpoints

4 endpoints under /v1/benchmarks/* (4 catalog + 0 raw escape hatch).

GET /v1/benchmarks/list

Discovery — surfaces per-project status (live / coming_soon) + geographies available + latest period.

curl https://api.buildcalcapi.dev/v1/benchmarks/list \
  -H "Authorization: Bearer bcapi_test_..."

{
  "projects": [
    {
      "project_type": "new_construction_sfh",
      "status": "live",
      "geographies_available": 5,
      "latest_period": "2026"
    },
    {
      "project_type": "kitchen_remodel_midrange",
      "status": "live",
      "geographies_available": 5,
      "latest_period": "2026"
    },
    "..."
  ]
}

GET /v1/benchmarks/projects/{project_type}?geography_tier=&msa=

Returns all benchmark rows for one project_type, optionally filtered by geography_tier (national / msa_large / msa_medium / msa_small / rural) and by MSA area_code.

# All geographies for new SFH construction
curl https://api.buildcalcapi.dev/v1/benchmarks/projects/new_construction_sfh \
  -H "Authorization: Bearer bcapi_test_..."

# Only large-MSA tier for kitchen remodel midrange
curl "https://api.buildcalcapi.dev/v1/benchmarks/projects/kitchen_remodel_midrange?geography_tier=msa_large" \
  -H "Authorization: Bearer bcapi_test_..."

{
  "project_type": "new_construction_sfh",
  "rows": [
    {
      "project_type": "new_construction_sfh",
      "geography_tier": "national",
      "area_code": "US00000",
      "duration_days_p25": 165,
      "duration_days_p50": 210,
      "duration_days_p75": 275,
      "cost_usd_p25": 346800,
      "cost_usd_p50": 462400,
      "cost_usd_p75": 578000,
      "cost_usd_base_year": 2026,
      "labor_pct": null,
      "materials_pct": null,
      "labor_hours_breakdown": null,
      "trade_dependencies": null,
      "confidence": "measured",
      "confidence_reason": "Census C30 per-permit valuation, national avg, latest published year, escalated to cost_usd_base_year via Census BCC Price Index for New One-Family Houses Under Construction",
      "methodology_id": "new_construction_sfh.national",
      "methodology_version": "2026-07-15-v1",
      "period": "2026",
      "fetched_at": "2026-07-15T14:00:42Z",
      "sources": [
        {
          "source_type": "census_c30",
          "source_url": "https://www.census.gov/construction/nrc/",
          "source_name": "Census C30 New Residential Construction",
          "source_period": "2024",
          "fetched_at": "2026-07-15T14:00:38Z"
        },
        {
          "source_type": "census_bcc",
          "source_url": "https://www.census.gov/construction/cpi/",
          "source_name": "Census BCC Price Index One-Family Houses",
          "source_period": "2026",
          "fetched_at": "2026-07-15T14:00:38Z"
        },
        {
          "source_type": "hud_soc",
          "source_url": "https://www.census.gov/construction/soc/",
          "source_name": "HUD Survey of Construction",
          "source_period": "2024",
          "fetched_at": "2026-07-15T14:00:38Z"
        }
      ]
    },
    "...4 more geography rows..."
  ]
}

GET /v1/benchmarks/sources/{source_type}/{period}

Raw source-citation escape hatch — returns all benchmark_sources rows matching a (source_type, period). Used by auditors to trace which benchmarks cite a given federal release.

curl https://api.buildcalcapi.dev/v1/benchmarks/sources/census_c30/2024 \
  -H "Authorization: Bearer bcapi_test_..."

{
  "source_type": "census_c30",
  "period": "2024",
  "count": 15,
  "rows": [
    {
      "source_type": "census_c30",
      "source_url": "https://www.census.gov/construction/nrc/",
      "source_name": "Census C30 New Residential Construction",
      "source_period": "2024",
      "fetched_at": "2026-07-15T14:00:38Z"
    },
    "..."
  ]
}

Valid source_type values: census_c30, census_bps, census_bcc, bls_oews, bls_productivity, eia_recs, hud_soc, industry_norm.

GET /v1/benchmarks/methodology/{project_type}

Returns the derivation formula + confidence_level + primary_sources for a project type. Useful for AI agents that need to explain why a benchmark looks the way it does.

curl https://api.buildcalcapi.dev/v1/benchmarks/methodology/kitchen_remodel_midrange \
  -H "Authorization: Bearer bcapi_test_..."

{
  "project_type": "kitchen_remodel_midrange",
  "version": "2026-07-15-v1",
  "geographies": {
    "national": {
      "confidence_level": "derived_industry_method",
      "formula": "Census BPS alterations valuation × scope_norms.kitchen_remodel_midrange materials_share + OEWS labor wages × expected_total_labor_hours; uses BuildCalc-authored scope_norms (not NAHB tables)",
      "scope_citation": "Consistent with general industry methodology concepts; numerical values independently derived",
      "primary_sources": ["census_bps", "bls_oews", "industry_norm"]
    },
    "msa_large": {"...": "..."},
    "msa_medium": {"...": "..."},
    "msa_small": {"...": "..."},
    "rural": {"...": "..."}
  }
}

Project type catalog

15 project types in v1, with their primary scope drivers:

Geographic granularity

We surface 5 tiers:

Tier thresholds are BuildCalc-defined, NOT Census-endorsed; documented in every msa-tier row's confidence_reason field. See Methodology for the full classification rationale.

Confidence + reproducibility

Every benchmark row carries:

• confidence — 4-level taxonomy (see Methodology page).
• confidence_reason — prose explanation.
• methodology_id — key into the live methodology config (e.g. "new_construction_sfh.national").
• methodology_version — version string of the methodology that produced this row (e.g. "2026-07-15-v1").
• cost_usd_base_year — dollar year for the cost columns (handles multi-year datasets cleanly).
• sources — array of citation rows with source_url + source_period
  • fetched_at per source.

The methodology_version lets external auditors verify any DB row against the snapshot of the methodology config that produced it, stored at app/benchmarks/seed_data/methodology_history/<version>.json. If we refine a formula, old rows still reflect the original derivation.

See also

• Methodology — full derivation framework, 4-level confidence taxonomy, federal-source matrix, BuildCalc-curated scope norms, methodology versioning, legal posture.
• Costs vertical — per-MSA + per-ZIP labor wage estimates fueling the labor side of every benchmark.
• Codes vertical — IRC/IBC/NEC/IECC/IPC code sections that define minimum scope for many project types.
• ADR-0016 (in repo at docs/adr/0016-benchmarks-vertical-legal-posture.md) — per-source legal tier classification.

Refresh cadence

Annual Render cron bcapi-etl-benchmarks runs July 15 (after BLS OEWS April release + Census C30 May release). Better Stack heartbeat alerts on missed runs. Refresh produces a new methodology_version stamp on every row.