{
  "meta": {
    "name": "HouseBuildCalc Data API",
    "description": "Machine-readable construction cost data for the United States. All files are static JSON — no authentication required.",
    "provider": "HouseBuildCalc",
    "url": "https://housebuildcalc.com",
    "contact": "https://housebuildcalc.com/contact/",
    "license": "Creative Commons Attribution 4.0 (CC BY 4.0) — free for any use with attribution to housebuildcalc.com",
    "dataYear": 2026,
    "lastUpdated": "2026-01-01"
  },
  "endpoints": [
    {
      "url": "https://housebuildcalc.com/data/index.json",
      "description": "This file. Lists all available data endpoints.",
      "contentType": "application/json",
      "updateFrequency": "annually"
    },
    {
      "url": "https://housebuildcalc.com/data/costs.json",
      "description": "National average construction costs per square foot by quality tier (basic/mid/premium), style multipliers, line-item cost breakdown percentages, and mortgage rate reference.",
      "contentType": "application/json",
      "updateFrequency": "annually",
      "fields": [
        "nationalAverages.tiers.basic.perSqft — builder-grade cost per sq ft (national avg)",
        "nationalAverages.tiers.mid.perSqft — mid-range cost per sq ft (national avg)",
        "nationalAverages.tiers.premium.perSqft — premium cost per sq ft (national avg)",
        "styleMultipliers — cost multiplier for ranch, two-story, colonial, craftsman, modern, cape-cod",
        "lineItemBreakdown — percentage of total cost for 10 construction phases, by quality tier"
      ],
      "exampleQuery": "fetch('https://housebuildcalc.com/data/costs.json').then(r => r.json())"
    },
    {
      "url": "https://housebuildcalc.com/data/states.json",
      "description": "Construction cost data for all 50 U.S. states plus D.C. Includes cost per sq ft by quality tier, regional cost multiplier, labor index, material index, average permit cost, climate, region, and building notes.",
      "contentType": "application/json",
      "updateFrequency": "annually",
      "recordCount": 51,
      "fields": [
        "code — 2-letter state code",
        "name — full state name",
        "slug — URL slug used on housebuildcalc.com/state/{slug}/",
        "multiplier — cost multiplier relative to national average (1.00 = avg)",
        "laborIndex — labor cost index relative to national average",
        "materialIndex — material cost index relative to national average",
        "avgPermitCost — typical building permit cost in dollars",
        "costPerSqft.basic — builder-grade cost per sq ft",
        "costPerSqft.mid — mid-range cost per sq ft",
        "costPerSqft.premium — premium cost per sq ft",
        "region — geographic region",
        "climate — primary climate classification",
        "notes — array of building considerations specific to this state"
      ],
      "exampleQuery": "fetch('https://housebuildcalc.com/data/states.json').then(r => r.json()).then(d => d.states.find(s => s.code === 'TX'))"
    },
    {
      "url": "https://housebuildcalc.com/data/materials.json",
      "description": "National average prices for 40+ residential construction materials with annual price history from 2022 to 2026. Covers framing lumber, concrete, roofing, insulation, drywall, flooring, windows, electrical, plumbing, HVAC, and exterior siding.",
      "contentType": "application/json",
      "updateFrequency": "annually",
      "recordCount": 40,
      "fields": [
        "name — material name and specification",
        "unit — unit of measure",
        "category — one of: framing, concrete, roofing, insulation, drywall, flooring, windows, electrical, plumbing, hvac, exterior",
        "price2022 through price2026 — annual national average price",
        "changeFrom2022Pct — percentage change from 2022 to 2026",
        "yoyChangePct — year-over-year change (2025→2026)",
        "note — context about the material and its use"
      ],
      "exampleQuery": "fetch('https://housebuildcalc.com/data/materials.json').then(r => r.json()).then(d => d.materials.filter(m => m.category === 'framing'))"
    }
  ],
  "calculatorLogic": {
    "description": "How to compute a construction cost estimate using this data",
    "formula": "totalCost = sqft × baseCostPerSqft[quality] × styleMultiplier[style] × stateMultiplier[stateCode]",
    "confidenceRange": "±12% for basic/mid quality, ±15% for premium",
    "example": {
      "inputs": { "sqft": 2000, "quality": "mid", "style": "two-story", "state": "TX" },
      "calculation": "2000 × $188 × 0.95 × 0.92 = $328,768",
      "note": "stateMultiplier for TX is 0.92; styleMultiplier for two-story is 0.95; base mid-range is $188/sqft"
    }
  },
  "humanReadablePages": {
    "calculator": "https://housebuildcalc.com/calculator/",
    "reverseCalculator": "https://housebuildcalc.com/reverse/",
    "stateIndex": "https://housebuildcalc.com/state/texas/",
    "materialsTracker": "https://housebuildcalc.com/materials/",
    "costTrends": "https://housebuildcalc.com/trends/",
    "guides": "https://housebuildcalc.com/learn/",
    "sitemap": "https://housebuildcalc.com/sitemap.xml",
    "llmsTxt": "https://housebuildcalc.com/llms.txt"
  }
}