Skip to main content

​
What a signal is

A signal is a permit-backed decision for a location scope. Each signal row returns:
  • decision: positive, negative, or insufficient_data
  • score: normalized 0.0 to 1.0
  • confidence: confidence level for that decision
  • reasons: deterministic reason codes explaining the decision
  • computed_at: timestamp of the scoring run

​
Signal families

​
Geo-scoped signals

Geo-scoped signals use a location anchor and are exposed through:
  • GET /v1/signals/geo/location/{geo_id}
  • GET /v1/signals/geo/search
  • GET /v1/signals/catalog
Quick examples: 
# One location
GET /v1/signals/geo/location/{geo_id}?signal_keys=roofing_activity_hotspot,hvac_activity_hotspot

# Ranked search across WA
GET /v1/signals/geo/search?state=WA&geo_type=county&signal_keys=roofing_activity_hotspot&decision=positive&min_score=0.60
These reads are keyed by location scope such as city, zip, county, jurisdiction, or state. For the current customer-facing signal catalog, see Signals Catalog.

​
Permit-scoped signals

Permit-scoped signals use a non-property geo_id and are exposed through:
  • GET /v1/signals/permit/leads
  • GET /v1/signals/permit/stats
These reads require:
  • geo_id
  • a non-property anchor
  • customer-facing permit signal keys such as site_prep_issued_nowcast, new_construction_issued_nowcast, framing_nowcast_early, framing_window_late, rough_in_nowcast_early, and rough_in_window_late
Freshness defaults to the last 60 days. Pass include_stale=true to disable the freshness window, or set max_freshness_days between 1 and 3650. Lead rows include the trust fields used for ranking and review:
  • event_date_used
  • signal_basis
  • confidence
  • reason_codes
  • freshness_lag_days
Public basis labels are observed_event and inferred_timing. The signal catalog includes both geo-scoped and permit-signal entries, so discovery stays in one place.

​
Current production signals (WA)

Current public geo signals:
  • roofing_activity_hotspot
  • hvac_activity_hotspot
Current public permit-pack signals:
  • site_prep_issued_nowcast
  • new_construction_issued_nowcast
  • framing_nowcast_early
  • framing_window_late
  • rough_in_nowcast_early
  • rough_in_window_late

​
How signals are computed (conceptual)

Geo-scoped signals compare recent permit activity to prior activity for the same location scope.
At a high level, we evaluate:
  • current activity level
  • change vs previous periods
  • minimum support needed to make a reliable call

​
Decision logic (high level)

Signals are deterministic and profile-driven.
  1. Eligibility check
    If data support is too low for a reliable decision, output is insufficient_data.
  2. Positive check
    If activity and momentum meet the profile requirements, output is positive.
  3. Otherwise
    Output is negative.
Reason codes explain why the decision was assigned (for example activity threshold met, trend up, or low support).

​
Confidence interpretation

Confidence reflects how much supporting evidence exists for that location decision.
  • lower support typically yields lower confidence
  • stronger support yields higher confidence
This is designed to avoid over-confidence in sparse geographies.

​
Timing guidance

Observed nowcasts are best when you want the most literal read on the permit record. Early inferred windows are best when you want more lead time and can accept more uncertainty. Late inferred windows are best when you want tighter timing and fewer premature leads. Freshness still matters: if your source data lands monthly, the support behind a valid signal can still be several days old.

​
Versioning and release control

Signal reads are controlled by active pointers.
signal_release_pointers selects active versions by state + signal_key. This allows:
  • predictable production behavior
  • pointer-based rollback
  • safe promotion of new runs without breaking clients

​
Product boundaries

  • Signals are ranking inputs, not guarantees.
  • Signals do not replace underwriting, legal, or compliance review.
  • Confidence can vary across geographies based on data availability.
Use signals as ranking and prioritization inputs, then combine with your own workflow logic.