r.in.ssurgo

Download and import SSURGO data from the USDA for a specified soil survey area.

Command linePython (grass.tools)Python (grass.script)

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] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.in.ssurgo soils=name

grass.tools.Tools.r_in_ssurgo(ssurgo_path=None, soils, hydgrp=None, ksat_h=None, ksat_r=None, ksat_l=None, mukey=None, desgnmaster="A", hzdept_r=0, hzdepb_r=25.4, depths=None, nprocs=0, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_in_ssurgo(soils="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.run_command("r.in.ssurgo", ssurgo_path=None, soils, hydgrp=None, ksat_h=None, ksat_r=None, ksat_l=None, mukey=None, desgnmaster="A", hzdept_r=0, hzdepb_r=25.4, depths=None, nprocs=0, flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.in.ssurgo", soils="name")

Parameters

Command linePython (grass.tools)Python (grass.script)

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
-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
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

ssurgo_path : str, optional
    Path to the SSURGO ZIP file downloaded from Web Soil Survey
    Used as: input, file, name
soils : str, required
    Name for output soil vector layer containing the source SSURGO map unit polygons and attributes.
    Used as: output, vector, name
hydgrp : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Hydrologic soil group (HSG) raster map output
    Used as: output, raster, name
ksat_h : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Saturated Hydraulic Conductivity of Soil Ksat (high) [mm/hr]
    Used as: output, raster, name
ksat_r : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Saturated Hydraulic Conductivity of Soil Ksat (regular) [mm/hr]
    Used as: output, raster, name
ksat_l : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Saturated Hydraulic Conductivity of Soil Ksat (low) [mm/hr]
    Used as: output, raster, name
mukey : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Map unit key
    Used as: output, raster, name
desgnmaster : str, optional
    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, optional
    Horizon depth top (cm)
    Default: 0
hzdepb_r : float, optional
    Horizon depth bottom (cm)
    Default: 25.4
depths : float | list[float] | str, optional
    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 : int, optional
    Number of threads for parallel computing
    0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
    Default: 0
flags : str, optional
    Allowed values: s
    s
        Force the SQLite/OGR backend for local SSURGO import (skip DuckDB)
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

Raises:

grass.tools.ToolError: When the tool ended with an error.

ssurgo_path : str, optional
    Path to the SSURGO ZIP file downloaded from Web Soil Survey
    Used as: input, file, name
soils : str, required
    Name for output soil vector layer containing the source SSURGO map unit polygons and attributes.
    Used as: output, vector, name
hydgrp : str, optional
    Hydrologic soil group (HSG) raster map output
    Used as: output, raster, name
ksat_h : str, optional
    Saturated Hydraulic Conductivity of Soil Ksat (high) [mm/hr]
    Used as: output, raster, name
ksat_r : str, optional
    Saturated Hydraulic Conductivity of Soil Ksat (regular) [mm/hr]
    Used as: output, raster, name
ksat_l : str, optional
    Saturated Hydraulic Conductivity of Soil Ksat (low) [mm/hr]
    Used as: output, raster, name
mukey : str, optional
    Map unit key
    Used as: output, raster, name
desgnmaster : str, optional
    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, optional
    Horizon depth top (cm)
    Default: 0
hzdepb_r : float, optional
    Horizon depth bottom (cm)
    Default: 25.4
depths : float | list[float] | str, optional
    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 : int, optional
    Number of threads for parallel computing
    0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
    Default: 0
flags : str, optional
    Allowed values: s
    s
        Force the SQLite/OGR backend for local SSURGO import (skip DuckDB)
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

r.in.ssurgo - Import soil data from the USDA NRCS Soil Survey Geographic Database (SSURGO) into GRASS from either a local copy of the the SSURGO file geodatabase or from the Soil Data Access (SDA) online API interface. The module is heavily inspired by the SoilDB (2.8.9) R package (Beaudette et al., 2025).

The tool will either use the SDA API to query and download data for the current computational region or read from a local copy of the SSURGO file geodatabase. The SDA API is used unless a local path to the SSURGO file geodatabase is provided to ssurgo_path. The SSURGO data can be downloaded from USDA NRCS at the following links:

• SSURGO CONUS
• SSURGO by State

The downloaded gSSURGO files can be used directly without unzipping the file geodatabase. r.in.ssurgo can read the zipped file geodatabase directly using GDAL's virtual file system.

ssurgo_path="path/to/gSSURGO_NC.zip"

However, you may also pass the path to an unzipped file geodatabase if you prefer.

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

NOTES

The Saturated Hydraulic Conductivity (Ksat) and the Hydrologic Soil Group (HSG) are aggregated for the specified depth range or master horizon using the Map Unit Key (mukey) as the spatial unit. Ksat is the rate at which water moves vertically through saturated soil; values are provided in mm/hr (SSURGO stores them as µm/s and the module multiplies by 3.6) and include the low (ksat_l), representative (ksat_r), and high (ksat_h) estimates per map unit.

The HSG is a soil classification system that groups soils based on their runoff potential, which is influenced by factors such as texture, structure, and permeability. The HGS raster (hydgrp) are used in rainfall excess models such as the SCS Curve Number method to estimate runoff from rainfall events (see r.curvenumber).

The soils output is a vector layer containing the source SSURGO Map Unit polygons and attribute data. This can be used for reference or to create custom rasters for Curve Number or other applications based on the SSURGO attributes.

Attributes on the soils vector

In addition to mukey / mukey_int, the soils vector carries the following dominant-component and depth-weighted attributes for the requested [hzdept_r, hzdepb_r] range and master horizon designation. Use them with v.to.rast use=attr attribute_column=<field> to derive any of these as rasters on demand.

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 (A, B, C, D, A/D, …)
compname	TEXT	Component name
drainagecl	TEXT	Drainage class
slope_r	REAL	Component slope (%)
ksat_l	REAL	Saturated hydraulic conductivity, low (mm/hr)
ksat_r	REAL	Saturated hydraulic conductivity, representative (mm/hr)
ksat_h	REAL	Saturated hydraulic conductivity, high (mm/hr)
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

The user can specify a depth range [cm] (top and bottom) or a master horizon designation (desgnmaster). The master horizon is the most representative horizon of a soil profile and is designated by a capital letter (A, E, B, C, R) in the SSURGO database. If a master horizon is specified, the Ksat and HSG values will be based on the specified master horizon. If a depth range is specified, the Ksat and HSG values will be aggregated for the specified depth range.

Aggregation Methods

Soils are aggregated using either the dominant component or a weighted average of all components in the map unit, depending on the specified depth range or master horizon.

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 always 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; slice 0 is at z=0 to z=depths[1], slice N-1 is at z=depths[-2] to z=depths[-1]. Adjust with g.region -3 if you prefer a different convention.

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)

tools.r_in_ssurgo(
    ssurgo_path="../data/gSSURGO_CONUS.zip",
    soils="soil_areas",
    ksat_r="ksat_r",
    depths="0,15,30,60,100",
    desgnmaster="A",
)

The intermediate per-slice columns (ksat_r__s0, ksat_r__s1, …) also appear on the soils vector if you want to access them as 2D rasters or query them via v.db.select.

Choosing the local-import backend

When importing from a local SSURGO file geodatabase, r.in.ssurgo uses the DuckDB Python package by default if it is installed. If DuckDB is unavailable, the tool falls back to a pure GDAL/OGR + SQLite implementation that uses GRASS's bundled attribute database. The -s flag forces the SQLite/OGR backend even when DuckDB is importable, which is useful for testing the fallback path or running on environments where DuckDB should be avoided. The flag has no effect on Soil Data Access (SDA) queries (used when ssurgo_path is not set).

SSURGO Download

• SSURGO CONUS
• SSURGO by State

If you choose to use the downloaded dataset instead of the SDA API you do not need to unzip the folder. r.in.ssurgo expects the data to be zipped.

REQUIREMENTS

duckdb>=1.4.4 Python package for querying and processing data from the SSURGO file geodatabase.

pip install duckdb

GDAL>=3.1 for reading and writing geospatial data formats. DuckDB uses FlatGeobuf for spatial data, which is supported in GDAL 3.1 and later.

EXAMPLES

Import Ksat data for the current region from a local copy of the SSURGO file geodatabase:

=== Command line

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) for a local import:

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",
)

=== Command line

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"

Import hydrologic soil group (HSG) data for the current region from the Soil Data Access (SDA) online API interface:

=== Python (grass.script)

gs.run_command(
    "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",
)

=== Python (grass.tools)

tools = Tools()
tools.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, United States Department of Agriculture. Web Soil Survey. Available online at https://websoilsurvey.nrcs.usda.gov/. Accessed [04/23/2025].

SEE ALSO

r.curvenumber, r.runoff, r.sim.water

AUTHORS

Corey T. White

Sponsors

r.in.ssurgo was developed as part of an agreement between the U.S. Department of Agriculture (USDA), Natural Resources Conservation Service (NRCS) and North Carolina State University (NCSU) (Recipient), to adapt the SIMulation of Water and Erosion (SIMWE) model for the integration of Dynamic Soil Survey data.

SOURCE CODE

Available at: r.in.ssurgo source code (history)
Latest change: Monday Jun 01 16:13:42 2026 in commit b22d0ca