{
  "api": "homestats.app/api",
  "version": "1",
  "documentation": "https://homestats.app/api/",
  "license": "Free use with attribution. Link to canonical (https://homestats.app/states/{slug}/) when republishing.",
  "rateLimits": {
    "perMinute": 60,
    "perHour": 600,
    "enforcement": "per-IP at the edge; 429 with Retry-After when exceeded",
    "caching": "CDN serves the same JSON for up to 1 hour, stale-while-revalidate 7 days; please cache responses client-side instead of repolling",
    "userAgent": "A User-Agent header is required. Scriptable UAs (curl/wget/python-requests/node-fetch/Go-http-client) must include contact info (email or URL) in the UA string.",
    "contact": "joshua.a.watte@gmail.com — email if you need higher limits for an attribution-licensed integration"
  },
  "endpoints": {
    "GET /api/states/index.json": "List all 50 states with summary metrics (score, median price, slug)",
    "GET /api/states/{slug}.json": "Full per-state dataset (40+ fields including market, demographics, taxes, hazards)",
    "GET /api/states/{slug}/places.json": "Counties + top cities for a state, ranked by best-value composite score"
  },
  "fields": {
    "market": [
      "medianSalePrice",
      "inventory",
      "daysOnMarket",
      "priceDropPct",
      "saleToListRatio",
      "yoyPriceChange"
    ],
    "demographics": [
      "population",
      "medianHouseholdIncome",
      "ownershipRate",
      "vacancyRate",
      "rentBurdenPct"
    ],
    "affordability": [
      "valueToIncome",
      "valueToRent",
      "buyVsRent"
    ],
    "housingCosts": [
      "propertyTax",
      "insurance",
      "electricity",
      "utilities",
      "naturalGas"
    ],
    "taxes": [
      "stateIncomeTax (topRate, noIncomeTax)"
    ],
    "jobs": [
      "occupations.groups (medianSalary, aiExposurePct, canAfford)",
      "stateUnemployment"
    ],
    "safety": [
      "crime (violent, property, murder, rape, burglary, autoTheft)"
    ],
    "hazards": [
      "hazardRisk.hazards (hail, wildfire, flood, hurricane, tornado, ...)"
    ],
    "migration": [
      "migration (netFlow, topInbound, topOutbound)"
    ],
    "environmental": [
      "waterQuality",
      "climate",
      "humidity"
    ]
  },
  "sources": [
    "Redfin",
    "FRED",
    "Census",
    "FHFA",
    "HUD",
    "BLS",
    "BEA",
    "EPA SDWIS",
    "FEMA NRI",
    "FBI UCR",
    "IRS SOI"
  ],
  "contact": "joshua.a.watte@gmail.com",
  "generatedAt": "2026-06-11T10:45:12.904Z"
}