# bim-site

> Site assessment for AEC workflows: flood zones, elevation, contamination, parcel data, seismic hazard, transit proximity, CA hazard zones, Taiwan urban planning zones, and more. Returns a STAC-tagged layer stack with per-layer provenance. No API keys required for core functionality.

## When to use bim-site

Use `bim site assess` early in a project to answer site compliance questions from a single call: flood risk, elevation, contamination history, parcel ownership, seismic exposure, transit access, historic resources, and hazard zone designations — all in one parallel fan-out. For individual data points, use the single-layer verbs directly.

**Taiwan support (v0.6.0):** Pass a Taiwan address in Chinese script (e.g. `台中市西屯區市政路200號`) or English (e.g. `Taichung, Taiwan`) — country is detected automatically. No flag required.

## Requirements

Network access to:
- `hazards.fema.gov` — FEMA NFHL flood zones (US)
- `epqs.nationalmap.gov` — USGS 3DEP elevation (US)
- `echodata.epa.gov` — EPA ECHO contamination (US)
- `fwspublicservices.wim.usgs.gov` — USFWS National Wetlands Inventory (US)
- `earthquake.usgs.gov` — USGS seismic hazard (US)
- `SDMDataAccess.sc.egov.usda.gov` — USDA SSURGO soil data (US)
- `overpass-api.de` — OSM Overpass (historic, airport, transit — global)
- `services.arcgis.com` — HUD Opportunity Zones + QCT, FEMA NRI (US)
- `egis.fire.ca.gov` — CAL FIRE FRAP wildfire (CA only)
- `maps.conservation.ca.gov` — CGS fault zones (CA only)
- `geocoding.geo.census.gov` — US Census Geocoder (US addresses)
- `nominatim.openstreetmap.org` — OSM Nominatim (Taiwan addresses + US fallback)
- `nces.ed.gov` — NCES school districts (US)
- `educationdata.urban.org` — school finance/enrollment (US)
- `services5.arcgis.com` — NYC zoning (US)
- `api.open-meteo.com` — SRTM elevation (Taiwan)
- `luz.tcd.gov.tw` — Taiwan urban planning zones (Taiwan, geo-IP restricted to TW)
- County ArcGIS endpoints — parcel data (16 US counties, no auth)

All endpoints are public. No API keys required for core functionality.
Optional: `BIM_REGRID_API_KEY` for US parcel fallback; `BIM_SITE_TGOS_APPID`/`BIM_SITE_TGOS_APIKEY` for Taiwan house-number geocoding (free registration at api.tgos.tw).

## Address vs coordinates

All verbs accept either:
- `--lat F --lon F` (WGS84)
- `--address "123 Main St, City, State"` — Census Geocoder (US) or Nominatim (Taiwan)

`assess` accepts `--address "..."` directly (no `--geocode` flag needed).

## assess — primary entry point

```
bim site assess --address "847 Meridian Ave, San Jose, CA 95125"
bim site assess --address "台中市西屯區市政路200號"
```

Detects country from address, geocodes, resolves jurisdiction, then fans out all applicable layers in parallel:

**US — Federal (always):** flood, elevation, wetlands, contamination, seismic, transit, hazard_score, opportunity, historic, airport, soil
**US — State CA only:** wildfire, faults (return `not_applicable` for non-CA)
**US — State NY only:** hurricane-zone, landmark (return `not_applicable` outside NYC)
**US — County (registry-routed):** parcel — resolves FIPS, queries registered endpoint; Regrid fallback if `BIM_REGRID_API_KEY` set
**US — Municipality (registry-routed):** zoning — NYC DCP 8-layer bundle; other cities via ArcGIS

**Taiwan — All:** elevation, faults, seismic, school, parcel, zoning, flood, airport, historic, transit
- Country auto-detected from address (Han characters or keywords: TAICHUNG, TAIPEI, etc.)
- Geocoder: Nominatim (default, no key) → TGOS (if `BIM_SITE_TGOS_APPID`+`APIKEY` set)
- Zoning downloads and caches all zone polygons on first use (~30s), then answers via PIP

### Response shape

```json
{
  "address": "...",
  "lat": 37.313, "lon": -121.915,
  "jurisdiction": {
    "country": "TW",
    "state_fips": "66",
    "state": "臺中市",
    "municipality": "西屯區",
    "lat": 24.1622, "lon": 120.6320
  },
  "layers": [
    {
      "layer": "elevation",
      "jurisdiction": "country:TW",
      "authority": "Open-Meteo",
      "attribution": "Open-Meteo SRTM (Taiwan)",
      "coverage": "covered",
      "data": { "elevation_m": 86.0, "elevation_ft": 282.2 }
    },
    {
      "layer": "seismic",
      "jurisdiction": "country:TW",
      "coverage": "covered",
      "data": { "pga_475yr": 0.33, "hazard_class": "high", "source": "static-zone-lookup" }
    }
  ],
  "missing": [
    { "layer": "zoning", "reason": "luz.tcd.gov.tw WAF rejection — accessible from Taiwan only" }
  ]
}
```

`coverage` values: `covered` | `not_covered` | `not_applicable` | `key_required`

## Single-layer verbs (US)

All accept `--lat F --lon F [--address STR] [--timeout 10s]`.

### flood
- `bim site flood lookup` — zone (AE/A/VE/X/D), sfha flag, BFE (NAVD88 ft), panel_id
- `bim site flood map --out FILE [--width 800] [--height 500]` — PNG: FEMA overlay + Esri basemap + pin. Accepts `--address` or `--lat`/`--lon`.
- `bim site flood vector --out FILE` — DXF R12, metres, local coords. Imports into Revit, AutoCAD, Rhino. Accepts `--address` or `--lat`/`--lon`.

### elevation
- `bim site elevation` — elevation_ft, elevation_m (USGS 3DEP EPQS; Open-Meteo SRTM for Taiwan)

### soil
- `bim site soil` — soil_name, drainage_class, farmland_class, hydric_soil (bool), expansive_soil_risk (USDA SSURGO)

### wetlands
- `bim site wetlands` — present (bool), wetland_type (NWI code), area_acres (USFWS NWI)

### contamination
- `bim site contamination` — facilities_1mi, facilities_3mi, top_facilities (up to 3 names), has_violations (EPA ECHO)

### seismic
- `bim site seismic` — pga_2pct_50yr (g), hazard_class: low/moderate/high/very_high (USGS ASCE 7-22; Taiwan Building Code static zones for TW)

### transit
- `bim site transit` — stops_within_half_mile, nearest_stop_name, route_types (GTFS codes: 0=tram, 1=subway, 2=rail, 3=bus, 4=ferry)
- **AB2097 note:** If `stops_within_half_mile > 0` and route_types includes light rail (1) or heavy rail (2), CA parking minimums cannot be imposed on new residential construction.

### hazard-score
- `bim site hazard-score` — risk_score, risk_rating, top_hazards (top 3 by score), hazard_scores map (FEMA National Risk Index)

### wildfire
- `bim site wildfire` — applicable (bool), vhfhsz (bool), haz_class — CA only, `not_applicable` elsewhere (CAL FIRE FRAP)

### faults
- `bim site faults` — applicable (bool), alquist_priolo (bool), ap_zone_name, liquefaction (bool), landslide (bool) — CA only (CGS)

### opportunity
- `bim site opportunity` — opportunity_zone (bool), qualified_census_tract (bool), lihtc_bonus_eligible (bool) (HUD ArcGIS)

### historic
- `bim site historic` — features_within_1mi (int), names (up to 5) (OSM Overpass — global)

### airport
- `bim site airport` — airports_within_5mi (int), nearest_name, nearest_icao, nearest_dist_mi, nearest_type (OSM Overpass — global)

### parcel
- `bim site parcel` — apn, owner, area_sf, land_use (US, registry-routed); county/district/road (Taiwan, NLSC/Nominatim)

### zoning
- `bim site zoning lookup` — zone_code, commercial_overlay, special_district, inclusionary_housing, transit_zone, lot, historic, rules_urls (NYC only v0.1)

### school
- `bim site school lookup` — leaid, district name, enrollment, grade range
- `bim site school enrich --leaid LEAID` — finance (rev_total, exp_total, etc. in **actual USD**), enrollment, staffing
- `bim site school map --out FILE` — PNG district boundary map
- `bim site school vector --out FILE` — DXF district boundary
- `bim site school search --bbox minLon,minLat,maxLon,maxLat` — individual schools in bbox

## US Parcel registry coverage (v0.3.0)

16 counties with free no-key ArcGIS or Socrata endpoints:

| County | Metro | Adapter |
|--------|-------|---------|
| Alameda (06001) | Oakland/Berkeley | arcgis_feature |
| Contra Costa (06013) | East Bay | arcgis_feature |
| Marin (06041) | North Bay | arcgis_feature |
| Sacramento (06067) | Sacramento | arcgis_feature |
| San Francisco (06075) | SF | arcgis+socrata (two-hop) |
| San Mateo (06081) | Peninsula | arcgis_feature |
| Santa Clara (06085) | San Jose | arcgis_feature |
| Solano (06095) | Napa/Vallejo | arcgis_feature |
| Sonoma (06097) | Santa Rosa | arcgis_feature |
| Yolo (06113) | Davis/Sacramento | arcgis_feature |
| Maricopa (04013) | Phoenix | arcgis_feature |
| Cook (17031) | Chicago | arcgis_feature |
| New York/Manhattan (36061) | NYC | nyc_pluto |
| Travis (48453) | Austin | arcgis_feature |
| King (53033) | Seattle | arcgis_feature |
| St. Louis City (29510) | St. Louis | arcgis_feature |

Outside these counties: set `BIM_REGRID_API_KEY` for Regrid fallback, or `parcel` returns `not_covered` with hint.

## Taiwan — layer details

| Layer | Source | Key required? | Notes |
|-------|--------|---------------|-------|
| elevation | Open-Meteo SRTM | No | Global, ~1m accuracy |
| faults | GSMMA ArcGIS + NCDR | No | Active fault zones; accessible from TW |
| seismic | Static zone lookup | No | Taiwan Building Code; Taichung = 0.33g/high |
| school | OSM Overpass | No | Schools/universities within 1 km |
| parcel | NLSC Open API + Nominatim | No | County/district/road; lot# needs NLSC WFS gov credentials |
| zoning | luz.tcd.gov.tw (PIP cache) | No | Downloads zone polygons on first use, caches 30 days |
| flood | NCDR ArcGIS | No | Endpoint pending; accessible from TW |
| airport | OSM Overpass | No | Global |
| historic | OSM Overpass | No | Global |
| transit | Transitland | No | Global |

## Flood zone codes

| Code | Meaning |
|------|---------|
| `AE` | High risk (1% annual chance); BFE available |
| `A` | High risk; no BFE (older maps) |
| `VE` | Coastal high risk; wave action + BFE |
| `X` shaded | Moderate risk (0.2% annual chance) |
| `X` unshaded | Minimal risk |
| `D` | Undetermined — FEMA study not completed |

BFE (`bfe` field) is NAVD88 datum, feet. `null` for Zone A and X.

## Workflow patterns

**US lot assessment:**
```
bim site assess --address "3507 East 12th Street, Austin TX"
```

**Taiwan lot assessment:**
```
bim site assess --address "台中市西屯區市政路200號"
```

**Pipe to Excel:**
```
bim site assess --address "..." | bim excel write site-report.xlsx
```

**Flood boundary into Revit:**
```
bim site flood vector --lat 37.313 --lon -121.915 --out flood.dxf
# or by address:
bim site flood vector --address "847 Meridian Ave, San Jose, CA 95125" --out flood.dxf
bim revit exec --file import-flood.cs --no-transaction
```

**CA transit + AB2097 check:**
```
bim site transit --lat 37.313 --lon -121.915
# stops_within_half_mile > 0 + route_types includes [1] → AB2097 parking exemption applies
```

## Gotchas

- `assess` timeout is 60s by default — covers parallel fan-out; reduce with `--timeout 30s` if some endpoints are slow
- Taiwan `zoning` first call takes ~30s to download zone polygons from luz.tcd.gov.tw; subsequent calls are instant from cache. luz.tcd.gov.tw is geo-IP restricted to Taiwan — returns WAF rejection outside Taiwan, shown as `missing` not an error.
- OSM Overpass (historic, airport, transit) may return 504 if queried in rapid parallel succession — individual verbs are more reliable than parallel scripting
- `soil` returns partial data if SSURGO has incomplete coverage; `hydric_soil: false` is reliable, other fields may be empty
- `seismic` for US: PGA is ASCE 7-22 MCEr level (risk-targeted); for Taiwan: static zone from Taiwan Building Code, not live PSHA
- `parcel` for US needs jurisdiction resolution (Census geography call) — adds ~1s; already included in `assess` fan-out. For Taiwan: returns county/district/road from Nominatim reverse geocode; cadastral lot# requires NLSC WFS government credentials.
- CA layers (`wildfire`, `faults`) return `{"applicable": false}` for non-CA coordinates — not an error, use `coverage: not_applicable` to filter
- DXF output uses **local coordinates centred on the queried point** — not georeferenced. Import as overlay, not absolute position.
- All API calls are live; `missing` array in `assess` output lists failed layers with `hint` for follow-up