earthkit-data-soilgrids

Global 250 m soil maps, one from_source() call away.

An earthkit-data source plugin that exposes ISRIC SoilGrids — global 250 m maps of pH, texture, organic carbon, bulk density, water retention and more — through the familiar from_source(...) interface.

You ask in soil-scientist terms (property / depth / statistic / bounding box); the plugin translates that into OGC Web Coverage Service (WCS) GetCoverage requests and hands them to earthkit's built-in url source, so download, caching and GeoTIFF reading all come for free.

import earthkit.data as ekd

ds = ekd.from_source(
    "soilgrids",
    property="phh2o",              # pH in water
    depth=["0-5cm", "5-15cm"],     # one or many depths
    stat="mean",                   # mean | Q0.05 | Q0.5 | Q0.95 | uncertainty
    bbox=[9.5, 51.3, 10.2, 51.7],  # W, S, E, N in lon/lat (EPSG:4326)
)

da = ds.to_xarray()   # xarray Dataset, via rioxarray

📓 See it in action:

• examples/quickstart.ipynb — fetching, unit conversion, mapping, depth profiles and uncertainty.
• examples/interactive_map.ipynb — draw a box on a live map, pick property/depth/statistic from dropdowns, and overlay the result (needs ipyleaflet + ipywidgets).

Install

pip install earthkit-data-soilgrids
# or, from a checkout:
pip install -e .

Runtime dependencies: earthkit-data>=1.0, pyproj (bbox reprojection), rioxarray (GeoTIFF reading).

Once installed, the plugin registers itself via the earthkit.data.sources entry point — no imports or configuration needed; ekd.from_source("soilgrids", ...) just works.

Windows note. earthkit-data declares a dependency on ecCodes, which has no Windows wheels — but it is only needed for GRIB, not for the GeoTIFFs this plugin reads. Install without it:

pip install --no-deps earthkit-data
pip install numpy pandas xarray rioxarray pyproj filelock jinja2 markdown multiurl pyyaml tqdm dask lru-dict deprecation
pip install --no-deps earthkit-data-soilgrids

Parameters

argument	default	notes
property	—	service id / property, e.g. phh2o, sand, clay, silt, soc, bdod, cec, cfvo, nitrogen, ocd, ocs, wv0010, wv0033, wv1500
depth	"0-5cm"	str or list: 0-5cm, 5-15cm, 15-30cm, 30-60cm, 60-100cm, 100-200cm (ocs → 0-30cm)
stat	"mean"	str or list: mean, Q0.05, Q0.5, Q0.95, uncertainty
bbox	—	[west, south, east, north] in crs units (required)
crs	"EPSG:4326"	CRS of bbox. Use "native" to pass the box directly in SoilGrids' Homolosine metres
output_crs	"EPSG:4326"	CRS of returned rasters. "native" keeps the Homolosine projection
coverage_id	—	explicit coverage id(s) that bypass property/depth/stat composition (pass service_id too)

Passing several depth/stat values fetches every combination. to_xarray() then returns a Dataset with one variable per coverage id (e.g. phh2o_0-5cm_mean, phh2o_5-15cm_mean), all on the same grid, with nodata masked to NaN. A single coverage returns the raster as-is (band_1).

Properties and units

SoilGrids stores integers; divide by the conversion factor to get conventional units (ISRIC FAQ):

property	description	mapped units	÷	conventional
phh2o	pH in water	pH × 10	10	pH
sand, silt, clay	texture fractions	g/kg	10	%
soc	soil organic carbon	dg/kg	10	g/kg
bdod	bulk density	cg/cm³	100	kg/dm³
cec	cation exchange capacity	mmol(c)/kg	10	cmol(c)/kg
cfvo	coarse fragments	cm³/dm³	10	vol%
nitrogen	total nitrogen	cg/kg	100	g/kg
ocd	organic carbon density	hg/m³	10	kg/m³
ocs	organic carbon stock (0–30 cm)	t/ha	10	kg/m²
wv0010, wv0033, wv1500	water content @ 10/33/1500 kPa	0.1 vol%	10	vol%

Why WCS?

SoilGrids offers three access routes. WCS is the one intended for "obtain a spatial subset and feed it into a modelling pipeline", which matches what an earthkit source should do. WebDAV/VRT is for whole-globe downloads (use that directly for global work), and the REST API is a beta service that ISRIC has intermittently paused, so it's a poor foundation for a plugin.

Projection handling

SoilGrids is published on the Interrupted Goode Homolosine projection (ISRIC code EPSG:152160). Because that code isn't in the PROJ database, the plugin reprojects your lon/lat box to Homolosine with the equivalent proj4 string (+proj=igh +datum=WGS84 +units=m), densifying the box edges before transforming so the axis-aligned extent stays valid. The WCS request itself subsets in the native grid using the ISRIC CRS URI, and by default asks the server to return rasters warped to lon/lat for easier downstream analysis.

Development

pip install -e ".[test]"
pytest        # unit tests: no network required

The tests validate request construction (including against ISRIC's documented Senegal example box), the multi-coverage merger, and entry-point discovery.

License and citation

Apache-2.0. SoilGrids data is © ISRIC — World Soil Information, released under CC-BY 4.0. When you publish, please cite:

Poggio, L., de Sousa, L. M., Batjes, N. H., Heuvelink, G. B. M., Kempen, B., Ribeiro, E., and Rossiter, D. (2021). SoilGrids 2.0: producing soil information for the globe with quantified spatial uncertainty. SOIL, 7, 217–240. https://doi.org/10.5194/soil-7-217-2021