# Loam — Soil Data API — for AI agents and LLMs

> Soil data by latitude/longitude. Send a WGS84 coordinate; get the USDA SSURGO
> soil map unit at that point — components, depth-resolved horizon properties
> (texture, pH, organic matter, available water capacity, Ksat), drainage class,
> hydrologic group, and farmland class — as one clean, aggregated JSON object.
> US coverage. Public-domain data (USDA-NRCS SSURGO via Soil Data Access).
> Informational only — describes a map unit (area), not a point measurement.
> Distributed via RapidAPI.

## Authentication
Sold on RapidAPI. Subscribe to a plan, then call through the RapidAPI gateway:
  X-RapidAPI-Key: <your-rapidapi-key>
  X-RapidAPI-Host: <your-rapidapi-host>
RapidAPI authenticates, meters, and proxies the request. No separate API keys.

## Base URL
https://loam.rgtz.dev   (or your RapidAPI host)

## Endpoints
- GET /v1/soil?lat=&lon=  — Soil profile (map unit, components, horizons) at a point.
- GET /v1/manifest        — Machine-readable capabilities (no auth).
- GET /openapi.yaml       — OpenAPI 3.1 spec (no auth).
- GET /health             — Health check (no auth).

## Request
GET /v1/soil?lat=42.03&lon=-93.65
- lat: latitude, decimal degrees WGS84 (-90..90)
- lon: longitude, decimal degrees WGS84 (-180..180)

## Response (trimmed)
{
  "disclaimer": "Soil data is derived from the USDA-NRCS SSURGO database ...",
  "source": { "name": "USDA-NRCS SSURGO via Soil Data Access", "license": "public domain" },
  "location": { "lat": 42.03, "lon": -93.65 },
  "mapunit": { "mukey": "2800480", "name": "Nicollet loam, 1 to 3 percent slopes", "farmland_class": "All areas are prime farmland" },
  "dominant_component": {
    "name": "Nicollet", "percent": 85, "major": true,
    "drainage_class": "Somewhat poorly drained", "hydrologic_group": "B/D",
    "taxonomic_order": "Mollisols", "slope_pct": 2,
    "horizons": [
      { "name": "Ap", "top_cm": 0, "bot_cm": 20, "texture": "loam",
        "sand_pct": 31, "silt_pct": 43, "clay_pct": 26,
        "organic_matter_pct": 6, "ph": 6.2, "available_water_capacity": 0.21, "ksat_um_s": 9.17 }
    ]
  },
  "components": [ { "name": "Nicollet", "percent": 85, ... }, { "name": "Clarion", "percent": 10, ... } ],
  "summary": {
    "surface_texture": "loam", "drainage_class": "Somewhat poorly drained",
    "hydrologic_group": "B/D", "depth_window_cm": [0, 30],
    "avg_texture": "loam", "avg_ph": 6.2, "avg_organic_matter_pct": 5.2,
    "avg_available_water_capacity": 0.21
  }
}

## Notes
- A map unit may hold 1–3 major components plus minors, each with a percent.
  `dominant_component` is the highest-percent major component; `components` lists
  them all. The true soil at an exact point may be a minor component.
- Horizons are ordered top-down by depth (cm). `texture` is the USDA texture
  class derived from the sand/silt/clay fractions.
- `summary` gives depth-weighted 0–30 cm roll-ups for quick consumption.
- Numeric fields may be null where SSURGO has no representative value.
- Coverage is the US + territories; open water and some unsurveyed areas return
  404 soil_not_found.

## Errors
Envelope: { "error": { "code", "message", "hint", "request_id" } }
Codes: forbidden, invalid_request, soil_not_found, upstream_failed, internal_error