API Reference

curl https://api.homequotr.com/v1/pricing/hvac/dallas \
  -H "X-API-Key: hq_live_a1b2c3d4..."

// Enterprise-tier response. Lower tiers see a subset (field-gated per api-specification.md §9.1.2).
{
  "data": {
    "median_price": 6100,
    "min_price": 2100,
    "max_price": 18200,
    "p25_price": 4300,
    "p75_price": 8600,
    "p90_price": 11400,
    "p95_price": 13900,
    "severity_distribution": [
      { "bucket": 1, "min": 2100, "max": 3200, "count": 42 }
    ],
    "permit_count": 847,
    "permit_count_quality_score": 87,
    "source_attribution": "City of Dallas Building Safety Department",
    "scope": "city",
    // Growth+ only
    "confidence_interval_low": 5850,
    "confidence_interval_high": 6410,
    // Scale+ only
    "cpi_normalized_median": 6314,
    "material_cost_indexed_median": 6480,
    "labor_rate_msa_indexed_median": 6255,
    // Enterprise+ only
    "covered_peril_mapping": [
      { "peril_type": "hail", "frequency_weight": 0.42, "severity_adjustment": 1.18, "source_reference": "NOAA SPC 2020-2024", "specificity_tier": "per_metro" }
    ],
    "frequency_estimate": {
      "lambda": 0.087, "ci_low": 0.078, "ci_high": 0.096, "observation_years": 12.3, "permit_count": 4844
    }
  },
  "meta": {
    "tier": "enterprise",
    "methodology_version": "hq_methodology_v1.0_2026",
    "last_updated": "2026-04-08",
    "data_source": "municipal_permits"
  }
}

curl https://api.homequotr.com/v1/pricing/roofing/houston/history \
  -H "X-API-Key: hq_live_a1b2c3d4..."

// Growth-tier response. Scale+ adds cpi / material / labor normalized medians per row.
{
  "data": {
    "quarterly": [
      { "period": "2024-Q1", "median": 11000, "permit_count": 892, "confidence_interval_low": 10620, "confidence_interval_high": 11380 }
    ],
    "yearly": [
      { "period": "2024", "median": 11200, "permit_count": 3841, "confidence_interval_low": 10850, "confidence_interval_high": 11550 }
    ]
  },
  "meta": {
    "tier": "growth",
    "methodology_version": "hq_methodology_v1.0_2026",
    "data_source": "municipal_permits"
  }
}

curl https://api.homequotr.com/v1/contractors/hvac/chicago?status=active&limit=2 \
  -H "X-API-Key: hq_live_a1b2c3d4..."

{
  "data": [
    {
      "name": "Midwest Comfort HVAC",
      "license_number": "IL-058-012345",
      "license_status": "active",
      "city": "Chicago",
      "state": "IL"
    }
  ],
  "pagination": {
    "total": 847,
    "limit": 2,
    "offset": 0
  },
  "meta": {
    "last_updated": "2026-04-08",
    "data_source": "state_licensing_boards"
  }
}

curl https://api.homequotr.com/v1/trades \
  -H "X-API-Key: hq_live_a1b2c3d4..."

{
  "data": [
    { "slug": "hvac", "name": "HVAC", "display_name": "HVAC" },
    { "slug": "roofing", "name": "Roofing", "display_name": "Roofing" },
    { "slug": "electrical", "name": "Electrical", "display_name": "Electrical" },
    { "slug": "plumbing", "name": "Plumbing", "display_name": "Plumbing" },
    { "slug": "foundation", "name": "Foundation", "display_name": "Foundation/Structural" },
    { "slug": "solar", "name": "Solar", "display_name": "Solar" }
  ]
}

curl https://api.homequotr.com/v1/cities \
  -H "X-API-Key: hq_live_a1b2c3d4..."

{
  "data": [
    { "slug": "new-york", "name": "New York", "state": "NY", "tier": "A", "population": 19979477 },
    { "slug": "los-angeles", "name": "Los Angeles", "state": "CA", "tier": "A", "population": 12997353 }
  ],
  "meta": { "total": 100 }
}

curl https://api.homequotr.com/v1/usage \
  -H "X-API-Key: hq_live_a1b2c3d4..."

{
  "data": {
    "calls_used": 3842,
    "calls_remaining": 1158,
    "quota": 5000,
    "overage_count": 0,
    "period_start": "2026-04-01",
    "period_end": "2026-04-30"
  }
}

curl https://api.homequotr.com/v1/peril/wind/dallas \
  -H "X-API-Key: hq_live_a1b2c3d4..."

// Enterprise-tier response. Trade splits for a peril with per-trade frequency weight and severity adjustment.
{
  "data": {
    "peril_type": "wind",
    "city": "Dallas",
    "state": "TX",
    "trade_splits": [
      { "trade": "roofing", "trade_display_name": "Roofing", "sub_category": null, "frequency_weight": 0.55, "severity_adjustment": 1.22, "source_reference": "NOAA SPC 2020-2024", "effective_date": "2024-01-01", "specificity_tier": "per_metro" },
      { "trade": "foundation", "trade_display_name": "Foundation", "sub_category": null, "frequency_weight": 0.20, "severity_adjustment": 1.05, "source_reference": "NOAA SPC 2020-2024", "effective_date": "2024-01-01", "specificity_tier": "per_metro" }
    ]
  },
  "meta": {
    "tier": "enterprise",
    "methodology_version": "hq_methodology_v1.0_2026"
  }
}

curl https://api.homequotr.com/v1/frequency/hvac/dallas \
  -H "X-API-Key: hq_live_a1b2c3d4..."

// Enterprise-tier response. Lambda + 95% CI on events per insured-home-year.
{
  "data": {
    "trade": "hvac",
    "city": "dallas",
    "events_per_insured_home_year": 0.087,
    "poisson_lambda": 0.087,
    "ci_low": 0.078,
    "ci_high": 0.096,
    "permit_count": 4844,
    "estimated_households": 2680000,
    "observation_years": 12.3
  },
  "meta": {
    "tier": "enterprise",
    "methodology_version": "hq_methodology_v1.0_2026"
  }
}