Streaming location-risk analysis for a US address
POST /api/properties/red-flags/stream/
5 credits
What it returns
A Server-Sent Events stream of location-risk findings for a US property — flood, crime, environmental hazards, school-district decline, and other neighborhood red flags. Emits five sequential events:
- geocoded — the address has been resolved to coordinates
- area_classified — neighborhood + ZIP context loaded
- flags_detected — text-based risk lookup complete
- vision_analyzed — aerial-imagery analysis complete
- complete — final report with aggregated findings
Plus error if any stage fails. The complete event is augmented with from_cache: true + cached_at (ISO 8601 UTC, Z suffix) when served from cache.
When to use it
- Render a real-time risk-analysis page where each stage animates as it loads.
- Pre-screen wholesale leads for hidden risk factors before outreach.
- Disclose neighborhood risk to buyers in a transparent format.
Pricing
5 credits per fresh request. Cache hits (re-running the same address+detection_mode for the same user within the cache TTL) cost 0 credits and replay the full event sequence so client UIs animate identically.
Streaming protocol
Content-Type: text/event-stream. Each event follows the SSE spec — event: <name> newline, data: <json> newline, blank-line separator. Errors return as event: error; errored runs are never persisted to cache.
FAQ
What if I don't want streaming?
The endpoint is streaming-only. Consume the full stream and use the complete event's payload as the final response.
Why is detection_mode not a parameter?
The proxy forces detection_mode: single and ignores client-supplied values. Multi-mode is reserved for future expansion.
How long do cached results live?
Until the cache TTL expires. Stale rows are self-purged on next lookup — no scheduled task. Cache key is per-user + sha256(normalized address).
Responses
200400— Bad request — a required parameter is missing or failed validation. Costs 0 credits.401— Authentication failed — missing or invalid API key. Costs 0 credits.402— Payment required — no active subscription or insufficient credit balance. Costs 0 credits.502