Sub-document

Peril mapping v1

version 1.0
key hq_methodology_v1.0_2026

Methodology version key: hq_methodology_v1.0_2026

Effective: January 1, 2026

Scope

This document defines how HomeQuotr maps insurance perils to trade categories for consumption by the Enterprise tier /api/v1/peril/[peril_type]/[city] endpoint. Peril mapping is gated by the FEATURE_PERIL_FREQUENCY environment flag and never surfaces below Enterprise tier per the P6.5 tier-projection contract.

Perils covered

The v1 mapping covers eight perils that account for the majority of U.S. residential property and casualty claims volume:

  1. Freeze
  2. Hail
  3. Wind
  4. Fire
  5. Water damage (non-flood)
  6. Mechanical breakdown
  7. Lightning
  8. Earth movement

Flood is excluded from v1 because flood claims under NFIP are handled separately from standard homeowners and the trade-level repair pattern differs materially from non-flood water damage.

Mapping schema

Each row in peril_trade_mappings represents the contribution of a single peril-trade pair to the overall claims pattern for that peril:

  • peril_type text, one of the eight perils above
  • trade_id UUID, foreign key to trades
  • sub_category text nullable, optional finer-grained scope
  • frequency_weight decimal 0.000 to 1.000, share of this peril's claims attributable to this trade, expressed as events per insured home-year
  • severity_adjustment decimal multiplier, cost multiplier vs the city-trade baseline median when the repair is caused by this peril
  • metro_id UUID nullable, NULL = national default; metro-specific overrides land post-Enterprise contract signing
  • climate_region text nullable, used when an override applies to a climate region rather than a specific metro
  • source_reference text, citation for the row
  • methodology_version text, stamps the row to this revision
  • effective_date date, when this row becomes the active mapping

Sources

The v1 seed contains 34 hand-curated rows derived from publicly verifiable U.S. property and casualty claims data:

  • Insurance Information Institute (III) Facts + Statistics, including the 2024 Frozen Pipes and Freeze Damage report
  • NAIC Severe Storm and Catastrophe state filings, 2023 and 2024
  • FM Global Property Risk Engineering reports, 2023
  • NFIP loss-cause statistics (used only as a cross-reference for non-flood water damage scope)
  • Internal HomeQuotr methodology for peril-to-trade allocation where public data was insufficiently granular

No single peril row is sourced solely from internal methodology; every row is anchored to at least one third-party reference visible in source_reference.

Use

A claims-frequency estimate at the city-trade-peril level composes as:

claims_frequency = trade_frequency_per_home_year * peril_frequency_weight
claims_severity  = trade_baseline_median * peril_severity_adjustment

This composition is performed client-side by underwriters; HomeQuotr returns the components, not the product, so the consumer can swap in their own internal frequency or severity priors as needed.

Stamping and versioning

Every row carries methodology_version = 'hq_methodology_v1.0_2026'. Future revisions ship under a new key. The idx_peril_trade_unique index permits a metro_id NOT NULL override to coexist with the NULL national default at the same effective date, so re-running the seed never wipes metro-specific overrides shipped under Enterprise contracts.

Limitations

  1. National default rows are point estimates, not distributions. Confidence intervals on peril weights are a v2 candidate.
  2. The 34-row v1 seed does not exhaust the cross-product of 8 perils x 6 trades; trade-peril pairs with negligible attribution are omitted rather than recorded as zero.
  3. Weights are calibrated against U.S. national averages and may diverge materially from a specific metro's experience. Metro-specific overrides ship under Enterprise contracts and inherit the national default until overridden.
  4. The mapping does not currently distinguish covered-peril repairs from out-of-pocket repairs; both flow through the same trade-level severity baseline.
  5. Earth movement weights exclude California earthquake (handled by separate CEA policies in most cases) and follow conventional homeowners exclusions.
Back to methodology