r.in.ssurgo - GRASS manual

NAME

r.in.ssurgo - Download and import SSURGO data from the USDA for a specified soil survey area.

KEYWORDS

SYNOPSIS

r.in.ssurgo

r.in.ssurgo --help

r.in.ssurgo [-s] [ssurgo_path=name] soils=name [hydgrp=name] [ksat_h=name] [ksat_r=name] [ksat_l=name] [mukey=name] [desgnmaster=string] [hzdept_r=float] [hzdepb_r=float] [depths=float[,float,...]] [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-s: Force the SQLite/OGR backend for local SSURGO import (skip DuckDB)
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

ssurgo_path=name: Path to the SSURGO ZIP file downloaded from Web Soil Survey
soils=name [required]: Name for output soil vector layer containing the source SSURGO map unit polygons and attributes.
hydgrp=name: Hydrologic soil group (HSG) raster map output
ksat_h=name: Saturated Hydraulic Conductivity of Soil Ksat (high) [mm/hr]
ksat_r=name: Saturated Hydraulic Conductivity of Soil Ksat (regular) [mm/hr]
ksat_l=name: Saturated Hydraulic Conductivity of Soil Ksat (low) [mm/hr]
mukey=name: Map unit key
desgnmaster=string: Designation of master horizon. Common values include O, A, B, C and E, but you can specify any master horizon designation present in the chorizon table.; Default: A
hzdept_r=float: Horizon depth top (cm); Default: 0
hzdepb_r=float: Horizon depth bottom (cm); Default: 25.4
depths=float[,float,...]: Comma-separated depth boundaries in cm (>=2 values, strictly increasing). When set, depth-weighted double precision outputs (ksat_l/r/h) become 3D rasters with slices defined by these boundaries; hzdept_r/hzdepb_r are ignored.
nprocs=integer: Number of threads for parallel computing; 0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs; Default: 0

DESCRIPTION
NOTES
REQUIREMENTS
EXAMPLES
REFERENCES
SEE ALSO
AUTHORS
Sponsors

DESCRIPTION

r.in.ssurgo imports soil data from the USDA NRCS Soil Survey Geographic Database (SSURGO) into GRASS, either from a local copy of the SSURGO File Geodatabase or from the Soil Data Access (SDA) online API. The module is heavily inspired by the soilDB R package (Beaudette et al., 2025).

The tool uses the SDA API to query and download data for the current computational region by default, and switches to a local file when an ssurgo_path is given. The data can be downloaded from USDA NRCS:

The downloaded ZIP can be passed directly — *r.in.ssurgo* reads the geodatabase inside through GDAL's virtual file system:

ssurgo_path="path/to/gSSURGO_NC.zip"

You may also pass an unzipped .gdb directory:

ssurgo_path="path/to/gSSURGO_NC/gSSURGO_NC.gdb"

NOTES

The module produces depth- and component-aggregated estimates of Saturated Hydraulic Conductivity (Ksat) and the Hydrologic Soil Group (HSG), keyed by the SSURGO Map Unit Key (mukey). Ksat values are reported in mm/hr as low (ksat_l), representative (ksat_r), and high (ksat_h) estimates per map unit.

HSG (hydgrp) classifies soils by runoff potential. It is consumed by rainfall-excess models such as the SCS Curve Number method (see r.curvenumber).

The soils output is the source SSURGO Map Unit polygon vector with all aggregated attributes attached. Use it for reference or to derive custom rasters from the SSURGO attribute set with v.to.rast use=attr attribute_column=<field>.

In addition to mukey / mukey_int, the soils vector carries the following dominant-component and depth-weighted attributes:

Field Type Description

cokey TEXT Component key of the dominant component

comppct_r REAL Dominant component's percentage of the map unit

hydgrp TEXT Hydrologic Soil Group

compname TEXT Component name

drainagecl TEXT Drainage class

slope_r REAL Component slope (%)

ksat_l / ksat_r / ksat_h REAL Saturated hydraulic conductivity (mm/hr); low / representative / high

sandtotal_r REAL Sand content (%)

silttotal_r REAL Silt content (%)

claytotal_r REAL Clay content (%)

awc_r REAL Available water capacity (cm/cm)

om_r REAL Organic matter (%)

dbthirdbar_r REAL Bulk density at 1/3 bar (g/cm³)

ph1to1h2o_r REAL Soil reaction (pH 1:1 H₂O)

cec7_r REAL Cation exchange capacity at pH 7 (meq/100 g)

Field	Type	Description
`cokey`	TEXT	Component key of the dominant component
`comppct_r`	REAL	Dominant component's percentage of the map unit
`hydgrp`	TEXT	Hydrologic Soil Group
`compname`	TEXT	Component name
`drainagecl`	TEXT	Drainage class
`slope_r`	REAL	Component slope (%)
`ksat_l` / `ksat_r` / `ksat_h`	REAL	Saturated hydraulic conductivity (mm/hr); low / representative / high
`sandtotal_r`	REAL	Sand content (%)
`silttotal_r`	REAL	Silt content (%)
`claytotal_r`	REAL	Clay content (%)
`awc_r`	REAL	Available water capacity (cm/cm)
`om_r`	REAL	Organic matter (%)
`dbthirdbar_r`	REAL	Bulk density at 1/3 bar (g/cm³)
`ph1to1h2o_r`	REAL	Soil reaction (pH 1:1 H₂O)
`cec7_r`	REAL	Cation exchange capacity at pH 7 (meq/100 g)

Depth-weighted REAL fields are aggregated as SUM(thk × value) / SUM(thk) over horizons that overlap the requested depth range, where thk is each horizon's thickness clipped to that range.

Filtering by depth or master horizon

A depth range (hzdept_r, hzdepb_r in cm) and/or a master horizon designation (desgnmaster) select the chorizon rows that contribute to the aggregation. Horizons whose depth interval overlaps the requested range are included; thickness is clipped to that range when computing the weighted mean.

Aggregation methods

Aggregation uses the dominant component (the largest comppct_r within each map unit). A weighted-component method is planned.

r3 (3D raster) output for depth profiles

When depths is set (a comma-separated, strictly-increasing list of cm boundaries with at least 2 values), the depth-weighted Ksat outputs (ksat_l, ksat_r, ksat_h) are produced as 3D rasters with one z-slice per depth bin instead of a single 2D average. The number of slices is len(depths) - 1. hzdept_r and hzdepb_r are ignored when depths is set; the aggregation runs once per slice.

hydgrp and mukey remain 2D — they're profile-level / identity values, not depth-dependent. The 3D region is set with b=0, t=max(depths) so the z-axis represents depth (cm) from the surface.

r.in.ssurgo \
    ssurgo_path="gSSURGO_NC.zip" \
    soils="soil_areas" \
    hydgrp="hydgrp" \
    ksat_r="ksat_r" \
    depths="0,15,30,60,100" \
    desgnmaster="A"
# produces: hydgrp (2D), ksat_r (3D, 4 slices)

The intermediate per-slice columns (ksat_r__s0, ksat_r__s1, ...) also appear on the soils vector so you can query them with v.db.select or rasterize any one slice with v.to.rast use=attr.

Choosing the local-import backend

For local-file imports, *r.in.ssurgo* uses DuckDB when the Python package is installed, and falls back to a pure ogr2ogr + Python stdlib sqlite3 implementation otherwise. The -s flag forces the SQLite/OGR backend even when DuckDB is importable, which is useful for testing the fallback path. The flag has no effect on SDA queries.

REQUIREMENTS

GDAL ≥ 3.1 — required by GRASS; provides ogr2ogr and the FlatGeobuf driver.
DuckDB ≥ 0.10 (Python package) — optional, accelerates local-file imports. Install with pip install duckdb. The SQLite fallback is used automatically when DuckDB is not available.

EXAMPLES

Import from a local SSURGO geodatabase

r.in.ssurgo \
    ssurgo_path="gSSURGO_NC.zip" \
    soils="soil_areas" \
    hydgrp="hydgrp" \
    ksat_l="ksat_l" \
    ksat_r="ksat_r" \
    ksat_h="ksat_h" \
    mukey="mukey" \
    hzdept_r=0 \
    hzdepb_r=100 \
    desgnmaster="A"

Python (grass.script):

gs.run_command(
    "r.in.ssurgo",
    ssurgo_path="gSSURGO_NC.zip",
    soils="soils",
    hydgrp="hydgrp",
    ksat_l="ksat_l",
    ksat_r="ksat_r",
    ksat_h="ksat_h",
    mukey="mukey",
    hzdept_r=0,
    hzdepb_r=100,
    desgnmaster="A",
)

Python (grass.tools):

tools = Tools()
tools.r_in_ssurgo(
    ssurgo_path="../data/gSSURGO_CONUS.zip",
    soils="soils",
    hydgrp="hydgrp",
    ksat_l="ksat_l",
    ksat_r="ksat_r",
    ksat_h="ksat_h",
    mukey="mukey",
    hzdept_r=0,
    hzdepb_r=100,
    desgnmaster="A",
)

Force the SQLite/OGR backend (skip DuckDB)

r.in.ssurgo -s \
    ssurgo_path="gSSURGO_NC.zip" \
    soils="soils" \
    hydgrp="hydgrp" \
    ksat_r="ksat_r" \
    hzdept_r=0 \
    hzdepb_r=100 \
    desgnmaster="A"

tools.r_in_ssurgo(
    ssurgo_path="../data/gSSURGO_CONUS.zip",
    soils="soils",
    hydgrp="hydgrp",
    ksat_r="ksat_r",
    hzdept_r=0,
    hzdepb_r=100,
    desgnmaster="A",
    flags="s",
)

Import via the SDA API (no local file)

r.in.ssurgo \
    soils="soils" \
    hydgrp="hydgrp" \
    ksat_l="ksat_l" \
    ksat_r="ksat_r" \
    ksat_h="ksat_h" \
    mukey="mukey" \
    hzdept_r=0 \
    hzdepb_r=100 \
    desgnmaster="A"

REFERENCES

Beaudette, D., Skovlin, J., Roecker, S., Brown, A. (2025). soilDB — Soil Database Interface. R package version 2.8.9. https://CRAN.R-project.org/package=soilDB
Soil Survey Staff, Natural Resources Conservation Service, USDA. Web Soil Survey. https://websoilsurvey.nrcs.usda.gov/

AUTHORS

Corey T. White

SOURCE CODE

Available at: r.in.ssurgo source code (history)

Latest change: Wednesday Jul 15 06:13:42 2026 in commit: 6f000f937de28c770c20049ccee90c83d52310f1