Find NHD flowlines (streams, rivers, canals, artificial paths) intersecting a geometry.

Uses NHDPlus HR NetworkNHDFlowline (layer 3), which carries stream order, total drainage area (totdasqkm), slope, smoothed elevation, and EROM mean-annual flow (qama, cfs) / velocity (vama, fps) estimates.

Use lat+lon when: "What river runs through 45.5, -122.6?" Use geometry when: "What streams cross this project polygon / pipeline corridor?" Set include_non_network=True to also capture isolated (non-routed) flowlines. Set verbose=True for the full attribute set (network IDs + full EROM suite).

Returns: { "finding": str, # plain-language summary "count": int, "truncated": bool, # true if capped at max_records "features": [...], # flowline attributes (+ ftype_label / fcode_label) "non_network": {...}, # present only when include_non_network=True "provenance": {...}, "query_geometry": {"type": str, "crs_epsg": int} }

ftype/fcode are integer codes; ftype_label/fcode_label give readable names.

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

Find NHD waterbodies (lakes, ponds, reservoirs, swamps) and areal water features.

Queries NHDWaterbody (layer 9) and/or NHDArea (layer 8) polygons intersecting the geometry. Both carry gnis_name, ftype/fcode, areasqkm, and elevation.

Use when: "Is there a lake within this parcel?", "What reservoirs intersect this bounding box?", "Name the waterbody at this point."

Returns: { "finding": str, "waterbody": {count, truncated, features, provenance}, # if requested "area": {count, truncated, features, provenance}, # if requested "query_geometry": {"type": str, "crs_epsg": int} }

ftype/fcode are integer codes; ftype_label/fcode_label give readable names.

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

Find NHDPlus stream gages intersecting a geometry (NHDPlusGage, layer 0).

Each gage links to NWIS via sourceid + sourceagency and reports the monitored drainage area (dasqmi, in SQUARE MILES) and reach location.

Use when: "What stream gages are in this watershed / bounding box?", "Which gage monitors this river reach?"

Because gages are point features, supply a Polygon or BoundingBox to find gages within an area (a bare point rarely coincides exactly with a gage).

Returns: { "finding": str, "count": int, "truncated": bool, "features": [...], # station_nm, sourceid, sourceagency, dasqmi (SQ MILES), ... "provenance": {...}, "query_geometry": {"type": str, "crs_epsg": int} }

NOTE: dasqmi is drainage area in SQUARE MILES (not sq km).

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

Find NHD point & line water features (springs, waterfalls, dams, gates, levees, ...).

Queries NHDPoint (layer 2) and/or NHDLine (layer 7) intersecting the geometry. Both carry gnis_name and ftype/fcode; point features also carry reachcode.

Use when: "Are there any waterfalls or springs near this point?", "What dams/weirs cross this river within the bounding box?"

Because these are point/line features, supply a Polygon or BoundingBox to find features within an area.

Returns: { "finding": str, "point": {count, truncated, features, provenance}, # if requested "line": {count, truncated, features, provenance}, # if requested "query_geometry": {"type": str, "crs_epsg": int} }

ftype/fcode are integer codes; ftype_label/fcode_label give readable names.

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

Identify the HUC12 watershed(s) containing/intersecting a geometry (WBDHU12, layer 12).

Returns the watershed name, 12-digit HUC code, downstream HUC (tohuc, for routing), hydrologic-unit type (hutype + label), area, and states.

Use when: "What watershed is this point in?", "Which HUC12 does this river reach drain to?", "List the sub-watersheds this project boundary spans."

A point returns the single containing HUC12; a polygon/bbox may intersect several.

Returns: { "finding": str, "count": int, "truncated": bool, "features": [...], # huc12, name, tohuc, hutype (+ hutype_label), areasqkm, states, ... "provenance": {...}, "query_geometry": {"type": str, "crs_epsg": int} }

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

Return ONLY how many features of a layer intersect a point or geometry (size check).

Use before the find_* tools to gauge result size without fetching full attributes -- useful for large polygons or densely mapped areas. A count of 0 means the geometry is outside coverage or has no features of that type.

Returns: { "count": int, "layer": str, "query_geometry": {"type": str, "crs_epsg": int}, "provenance": {...} }

Error responses:

• "Error: supply either lat+lon or geometry, not both (or neither)"

• "Error: unsupported geometry type ..."

• "Error: NHDPlus HR request failed: ..."

List the layers available in the NHDPlus HR service (id, name, geometry type).

Use when: You need to discover available layers beyond those wrapped by the find_* tools (e.g. NHDPlusCatchment, NHDPlusSink, FlowDirection, NHDPlusBoundaryUnit) or to confirm current layer IDs.

Returns: { "layers": [{"id": int, "name": str, "geometry_type": str}, ...], "provenance": {...} }

Error responses:

• "Error: NHDPlus HR request failed: ..." -- network or service error