soil-survey

Soil Survey

Readable soil report for any US location from live USDA data. Two keyless public HTTP APIs — call them with curl (shell) or Python (sandbox), whichever your runtime has. Zero installs.

First, read reference.md in this skill's directory — it has the tested SQL templates (Q1, Q2, Q3, Q3b, Q4, D), the HTTP request specs with shell + Python examples, the network-access note, table docs for ad-hoc queries, and glossaries. Do not compose SDA SQL from scratch when a template fits.

These APIs are external; sandboxes (ChatGPT, claude.ai) block outbound internet by default. If a call fails with a network error, see the "Network access required" note in reference.md (allowlist the two domains, then retry in a fresh conversation).

Modes

Pick based on what the user asked; all share the same plumbing (see reference.md):

• Point report (default) — soil at a single address/coordinate. The workflow below.
• Area — soils across a parcel/area. If the user pastes a WKT or GeoJSON polygon, use it; otherwise build a radius circle around the geocoded point. Run template AQ for the area-weighted map units, then Q2/Q3/Q4 on the dominant unit(s). Lead the report with the dominant-units table (map unit · acres · % of AOI).
• Compare — two or more locations. Run the point workflow for each, then a side-by-side table + a short narrative diff.
• Series lookup — the user names a soil series, not a place. Use template SQ (taxonomy + extent) plus a representative profile, and link the OSD / SoilWeb. No geocoding.

Workflow

1. Get coordinates.
   • Lat/lon given → use directly.
   • Street address → Census geocoder (scaffold in reference.md). No match → tell the user (campus buildings, PO boxes, and new construction often miss) and ask for a cross-street or coordinates.
   • Well-known place name → you may use approximate coordinates from your own knowledge, but disclose that in the report.
2. Point → map unit: template Q1. ⚠️ WKT order is POINT(lon lat) — longitude first. Empty {} response → outside SSURGO coverage (open water or unmapped): say so and offer to try a nearby point.
3. Pull data: templates Q2 (overview), Q3 (components + horizons), Q3b (restrictions), Q4 (interpretations) with the mukey. They are independent — run all four in parallel.
4. Write the report.

Report format

If the user asked a specific question ("will a septic system work?"), lead with that answer, then include only supporting sections. Otherwise, all sections:

🗺️ Location & map unit — matched address/coordinates, map unit name + symbol. ALWAYS include: SSURGO is 1:24,000-scale survey mapping — this describes soils mapped in this area, not a measurement at this exact point.

🌱 Your soil — dominant component: series name, taxonomy translated to plain English (what the soil is and how it formed), horizon-by-horizon profile with depths and textures. Name other components ≥ 10% with their percentages — they may behave very differently.

📊 Key properties — table for the dominant component: drainage class · surface texture · pH · organic matter % · AWC · Ksat · depth to restrictive layer (or "none within 2 m").

🏠 What works here — each Q4 interpretation as a plain verdict with the official rating in parentheses, e.g. "Septic: poor fit (Very limited)". "Very limited" means costly mitigation, not impossible. When the user cares about one rating, find what drives it (ruledepth > 0 rows) and explain.

🚜 Farming — farmland classification · land capability class with meaning (1 best → 8, subclass letter = the limitation) · NCCPI in context (0–1, higher = more inherently productive).

💧 Hazards & water — flooding & ponding frequency · min water table depth (null = none within 2 m) · hydric % · hydrologic soil group with one-line meaning.

For non-soil map units (Water, Urban land, NOTCOM, Pits): report what the map unit is, explain why there is no soil interpretation, offer to check a nearby point.

Hard rules

• Never fabricate a value. Every number traces to a query response in this conversation. Null field → "not populated in SSURGO", not a guess.
• Always include the map-scale caveat.
• API failure → report it honestly (SDA has bad days; use a ~60s timeout). A network/connection error usually means sandbox internet is blocked — point the user to the allowlist note in reference.md. Offer to retry. Never substitute remembered soil facts for live data.
• Show original SSURGO units (cm, µm/s, cm/cm); add friendly conversions in parentheses where it helps.
• Questions beyond the templates (vineyards, solar, compaction...): run discovery template D — survey areas carry state-specific interpretations — then query the exact rule name it returns.