# ToolMint Address Risk Bundle

> One paid call for US location risk: Census geocoder → county/tract, active NWS weather alerts, nearby USGS earthquakes, and FEMA NFHL flood zone. Useful for insurance, logistics, events, travel and real-estate screening. Public US government data only; informational, not an official determination.

- Status: Coming soon
- Price: $0.05 / call (x402 exact, USDC on Base eip155:8453, payTo 0xfbF7413bcB3a604936775C96FDbe0b0C9c9E37F5)
- Planned URL: https://toolmint-address-risk-bundle-json.toolmint.workers.dev
- OpenAPI: https://toolmint.toolmint.workers.dev/tools/address-risk-bundle-json/openapi.json

## Routes

- `GET /risk` $0.05: Risk bundle by lat/lon or address
- `GET /risk/point` $0.05: Risk bundle by point
- `GET /risk/address` $0.05: Risk bundle by address

## When to use it

Quick location screening for insurance triage, logistics, events, travel or real-estate research: one object with area, hazards and flags. Not for: official determinations, appraisals, parcel data, or anywhere outside the US.

## Example

```bash
curl -i "https://toolmint-address-risk-bundle-json.toolmint.workers.dev/risk/address?address=1600%20Pennsylvania%20Ave%20NW%2C%20Washington%2C%20DC"
```

That hostname is the planned Worker name. The tool is **not deployed yet**. Allow up to about 60 seconds: the Census geocoder can be slow on a cold start.

Trimmed response (values illustrative):

```json
{
  "tool": "address-risk-bundle-json",
  "version": "0.1.0",
  "partial": false,
  "failedComponents": [],
  "location": {
    "lat": 38.9, "lon": -77.0,
    "matchedAddress": "...",
    "addressMatchCount": 1,
    "coordinatesNote": "Census address coordinates are interpolated along the street segment, not the building footprint.",
    "census": { "state": {"name":"...","stusab":"DC","geoid":"11","fips":"11"}, "county": {"name":"...","geoid":"..."}, "tract": {"name":"...","geoid":"...","tract":"..."}, "place": {"name":"...","geoid":"..."}, "zcta": {"name":"...","geoid":"..."} }
  },
  "weatherAlerts": { "ok": true, "error": null, "count": 0, "totalActive": 0, "alerts": [] },
  "earthquakes": { "ok": true, "error": null, "count": 0, "truncated": false, "maxMagnitude": null,
                   "query": { "radiusKm": 100, "days": 30, "minMagnitude": 2.5, "startTime": "..." }, "events": [] },
  "floodZone": {
    "ok": true, "error": null, "found": true, "specialFloodHazardArea": false,
    "zone": { "fldZone": "X", "zoneSubtype": "...", "sfha": false, "staticBfe": null,
              "verticalDatum": null, "floodAreaId": "...", "dfirmId": "..." },
    "note": null,
    "disclaimer": "Informational point lookup of FEMA's public NFHL GIS service. NOT an official flood zone determination ... Verify at https://msc.fema.gov. Not endorsed by FEMA."
  },
  "riskFlags": ["flood_zone:X"],
  "provenance": {
    "fetchedAt": "2026-10-31T12:00:00.000Z",
    "sources": [ { "component": "census", "source": "...", "sourceUrl": "...", "license": "...", "fetchedAt": "..." },
                 { "component": "weatherAlerts" }, { "component": "earthquakes" }, { "component": "floodZone" } ],
    "note": "Informational only. Not an insurance underwriting, lending, appraisal or official flood determination. No county/parish parcel GIS."
  },
  "cached": false
}
```

`riskFlags` is a list of short strings, for example `active_nws_alerts:2(Severe,Moderate)`, `recent_quakes:3,maxM3.1`, `sfha:true`, `flood_zone:AE`, `flood_zone:not_mapped_at_point`, `component_failed:floodZone`. `no_active_flags` appears only when every part answered and nothing was flagged.

## Data sources and licence

U.S. Census Bureau Geocoder, NWS (api.weather.gov), USGS earthquake service, FEMA National Flood Hazard Layer. US Government data, public domain or free to use; none endorses this product. Per-source URL, licence and fetch time are in `provenance.sources`. Check each source's own terms.

## Freshness and caching

Complete bundles are cached in memory for 10 minutes. Partial bundles are never cached. FEMA maps can be outdated and preliminary data is excluded.

## Limits

- Informational, not an official determination.
- US only. Address matching is the Census geocoder's (first match is used).
- Up to 50 earthquakes returned (`truncated` shows when capped).
- Slow cold starts: allow around 60 seconds.