Changelog

Format: Keep a Changelog. Versioning: Semantic Versioning.

Unreleased

0.2.0 — 2026-05-19

Phase 6 costs vertical SHIPPED. Full federal-data labor + permits + materials coverage with 4-level confidence taxonomy.

Added

• Costs vertical — county + ZIP labor paths live. Sub-deliverable 4 closes the labor endpoint with two new geographic paths. See Costs vertical for curl + response examples and Methodology for the formula + the 7 known limitations.
  • GET /v1/costs/labor?trade=&county={FIPS} — OEWS x QCEW geographic-scaled hourly wage estimate. Returns confidence from the 4-level taxonomy plus confidence_reason + methodology + inputs.* + paired_trades + all_trades_share_ratio + degenerate_msa + systematic_error_pct_range + bid_markup_factor_range + limitations_note + wage_vs_bid_note + sources + see_also. Full fallback chain: 5-digit NAICS county -> state-level -> parent NAICS 238 -> OEWS MSA direct.
  • GET /v1/costs/labor?trade=&zip={ZIP} — ZIP resolves to dominant county via HUD zip_county_crosswalk (max res_ratio), then treated as the county path. Response surfaces resolved_county_fips + resolved_msa_code.
  • GET /v1/costs/sources/qcew?area=&naics= — raw QCEW escape hatch.
• Costs vertical — permits endpoint live. Census Building Permits Survey for ~3,100 US counties + ~930 CBSAs:
  • GET /v1/costs/permits?jurisdiction=US-XX-NNNNN or US-MSA-NNNNN — 4 structure-type breakouts (1u / 2u / 3-4u / 5+u) for buildings, units, and valuation.
  • GET /v1/costs/sources/permits/{jurisdiction_code} — raw escape hatch.
• Methodology page at /docs/methodology/costs documents the OEWS x QCEW formula, 4-level confidence taxonomy, full fallback chain, and 7 known limitations (occupational composition, NAICS suppression bias, trade-pair coupling, dominant-county degeneracy, wage-vs-bid distinction, time-series misalignment, geographic completeness over precision).
• 2 new Render crons for Phase 6 costs:
  • bcapi-etl-bls-qcew (quarterly) populates cost_labor_qcew + cost_labor_qcew_coverage from the BLS QCEW single-file CSV.
  • bcapi-etl-census-bps (monthly) populates cost_permits_bps from Census BPS county + CBSA monthly files.
• openpyxl 3.1.* runtime dependency — required by the BLS OEWS XLSX parser. Adds ~1MB; no transitive vulnerabilities at pinning.
• Costs vertical — labor endpoint (MSA path) live. BLS OEWS hourly wages for 11 construction trades across ~390 US MSAs. See the Costs vertical docs for full curl + response examples.
  • GET /v1/costs/labor?trade=&msa= — median + p25 + p75 hourly wage plus employment count for one (trade x MSA) cell. Returns confidence: "measured" (direct OEWS, no scaling).
  • GET /v1/costs/sources/oews?msa=&soc= — raw escape hatch returning integer-cents wages for one (MSA, SOC) cell.
• Annual Render cron bcapi-etl-bls-oews runs app/etl/bls_oews.py on April 3 at 14:00 UTC after BLS's early-April release. Better Stack heartbeat with 7-day grace. Year-fallback tries current_year - 1 first.
• Costs vertical — materials endpoint (PPI for 15 categories) live. Three new endpoints under /v1/costs/*. See the Costs vertical docs for full curl + response examples.
  • GET /v1/costs/list — dynamic per-vertical status (live / coming_soon) based on DB presence checks.
  • GET /v1/costs/materials?category=&period= — BLS Producer Price Index value + 12-month history for 15 construction categories. Multi-series categories (flooring / doors-windows / site) get equal-weight averaging.
  • GET /v1/costs/sources/ppi/{series_id} — raw escape hatch (24 trailing months of one BLS series).
• Monthly Render cron bcapi-etl-bls-ppi runs app/etl/bls_ppi.py on day 16 at 14:00 UTC, after BLS's second-Thursday release. Better Stack heartbeat alerts on missed runs.
• HUD USPS ZIP-CBSA crosswalk bootstrap (47k rows) prepping for the county / MSA labor and permits endpoints in subsequent sub-deliverables.
• Codes vertical FTS integration tests + @pytest.mark.integration marker for the whole DB-touching subset of the test suite. Default pytest tests/ is now clean (325 passed / 48 skipped / 0 failed).
• RequestIdMiddleware unit tests (6 new tests, 0 DB needed).
• Public status page at buildcalc-api.betteruptime.com — Better Stack Uptime free tier monitors api / docs / landing + a heartbeat for the hourly overage cron.
• Sitemap at docs.buildcalcapi.dev/sitemap.xml + crawl-permissive robots.txt (was still Disallow: / from staging hardening).
• Custom 404 page on the marketing site with dark theme and next-step CTAs. CF Pages now returns HTTP 404 for unknown URLs.
• metadataBase + root title template on the docs site — OG image refs are now absolute, social previews (Twitter / LinkedIn / Discord) no longer break.
• /v1/openapi.json documented in the Quickstart with a note about the auth-gated schema and intentionally-disabled Swagger UI / ReDoc.
• Account-management endpoints (/v1/account/{usage,api-keys}) now have full curl + sample-response docs — see Authentication → Account management.
• NEC 2026 dual-edition seed (107 sections) — calc_links.py maps the Article 220 → 120 renumber. code_sections total: 937.
• IRC stairs calculators (/v1/calc/stairs/*) accept optional irc_edition: "2021" | "2024" and return the citation in the requested edition's numbering.

Changed

• ICC adoption scraper failures (URL break or 0 rows from the PDF) are now FATAL — the cron exits non-zero so a silent ICC outage no longer hides behind a green Render run.

0.1.0 — 2026-05-15

Initial production release. Public launch.

Added

• 79 calculators across 16 categories (concrete, lumber, roofing, drywall, paint, flooring, HVAC, insulation, masonry, electrical, plumbing, doors-windows, gutters, stairs, site, misc). Every formula cites a US code section or manufacturer spec sheet.
• Codes vertical — 830 hand-curated sections across IRC 2021/2024, IBC 2024, NEC 2023, IECC 2024, IPC 2024 + per-state adoption matrix for 49 states (codecheck.com NEC/IRC + ICC Master Chart Jan 2024 for IBC/IECC/IPC). See the Codes vertical docs.
• MCP server at https://api.buildcalcapi.dev/mcp exposing all calculator + codes endpoints as auto-generated MCP tools (Streamable HTTP transport, MCP spec 2025-03-26). See the MCP integration docs.
• Stripe metered billing — 4 tiers (Free 1k/mo · Starter $49 25k · Growth $249 250k · Enterprise custom from $1500). Hourly overage processor cron pushes usage records.
• Programmatic signup at POST /v1/account/signup — supports both human flow (Cloudflare Turnstile + Stripe SetupIntent) and AI-agent flow (Stripe payment method on file, no challenge). See Authentication.
• Mini-dashboard at buildcalcapi.dev/dashboard — self-service usage + key management + Stripe portal.
• RFC 7807 problem+json error responses + Idempotency-Key support per IETF draft on mutating endpoints. See Errors.
• Legal: Terms of Service (Common Paper CSA v2.1 + custom Cover Page) and Privacy Policy (hand-written, CCPA + multi-state).
• Sentry error tracking (Developer free tier).

Not yet shipped

These verticals were originally scoped for v0.1.0 but are deferred to later milestones:

• Costs vertical — BLS PPI/OEWS + HUD + Census derived indices.
• Products vertical — ~6k SKUs across 10 categories with manufacturer spec attributes.
• Benchmarks vertical — typical timelines + cost ranges across 15 project types.
• Auto-generated SDKs (Python + TypeScript) — /v1/openapi.json is available auth-gated for SDK-generator tooling in the meantime.