Skip to contents

This function obtains SoilGrids properties information (250m raster resolution) given a data.frame containing site IDs, latitudes and longitudes. SoilGrids API and maps return values as whole (integer) numbers to minimize the storage space used. These values are converted by to produce conventional units by `fetchSoilGrids()``


  loc.names = c("id", "lat", "lon"),
  depth_intervals = c("0-5", "5-15", "15-30", "30-60", "60-100", "100-200"),
  variables = c("bdod", "cec", "cfvo", "clay", "nitrogen", "phh2o", "sand", "silt",
    "soc", "ocd"),
  verbose = FALSE,
  progress = FALSE



A data.frame containing 3 columns referring to site ID, latitude and longitude.


Optional: Column names referring to site ID, latitude and longitude. Default: c("id", "lat", "lon")


Default: "0-5", "5-15", "15-30", "30-60", "60-100", "100-200"


Default: "bdod", "cec", "cfvo", "clay", "nitrogen", "phh2o", "sand", "silt", "soc", "ocd"


Print messages? Default: FALSE


logical, give progress when iterating over multiple requests; Default: FALSE


A SoilProfileCollection



NameDescriptionMapped unitsConversion factorConventional units
bdodBulk density of the fine earth fractioncg/cm^3100kg/dm^3
cecCation Exchange Capacity of the soilmmol(c)/kg10cmol(c)/kg
cfvoVolumetric fraction of coarse fragments (> 2 mm)cm^3/dm^3 (vol per mil)10cm^3/100cm^3 (vol%)
clayProportion of clay particles (< 0.002 mm) in the fine earth fractiong/kg10g/100g (%)
nitrogenTotal nitrogen (N)cg/kg100g/kg
phh2oSoil pHpH*1010pH
sandProportion of sand particles (> 0.05 mm) in the fine earth fractiong/kg10g/100g (%)
siltProportion of silt particles (= 0.002 mm and = 0.05 mm) in the fine earth fractiong/kg10g/100g (%)
socSoil organic carbon content in the fine earth fractiondg/kg10g/kg
ocdOrganic carbon densityhg/m^310kg/m^3
ocsOrganic carbon stocks (0-30cm depth interval only)t/ha10kg/m^2

SoilGrids predictions are made for the six standard depth intervals specified in the GlobalSoilMap IUSS working group and its specifications. The default depth intervals returned are (in centimeters): "0-5", "5-15", "15-30", "30-60", "60-100", "100-200" for the properties "bdod", "cec", "cfvo", "clay", "nitrogen", "phh2o", "sand", "silt", "soc", "ocd"--each with 5th, 50th, 95th, mean and uncertainty values. Soil organic carbon stocks (0-30cm) (variables="ocs") are returned only for depth_intervals="0-30". The uncertainty values are the ratio between the inter-quantile range (90% prediction interval width) and the median : (Q0.95-Q0.05)/Q0.50. All values are converted from "mapped" to "conventional" based on above table conversion factors. Point data requests are made through "properties/query" endpoint of the SoilGrids v2.0 REST API. Please check ISRIC's data policy, disclaimer and citation:

Find out more information about the SoilGrids and GlobalSoilMap products here:


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


Andrew G. Brown


if (FALSE) {
  your.points <- data.frame(id  = c("A", "B"), 
                           lat = c(37.9, 38.1), 
                           lon = c(-120.3, -121.5), 
                           stringsAsFactors = FALSE)
  x <- try(fetchSoilGrids(your.points))
  if (!inherits(x, 'try-error'))
   aqp::plotSPC(x, name = NA, color = "socQ50")
  # organic carbon stocks use 0-30cm interval
  y <- try(fetchSoilGrids(your.points[1, ], 
                          depth_interval = c("0-5", "0-30", "5-15", "15-30"),
                          variables = c("soc", "bdod", "ocd", "ocs")))
  # extract horizons from a SoilProfileCollection where horizon 2 overlaps 1, 3, and 4
  h <- aqp::horizons(y)
  # "ocs" (organic carbon stock 0-30cm interval)
  h[2, ]
  h$thickness_meters <- ((h$hzdepb - h$hzdept) / 100)

  # estimate "ocs" from modeled organic carbon and bulk density in 0-5, 5-15, 15-30 intervals
  #  (sum the product of soc, bdod, and thickness in meters)
  #  (1 gram per cubic decimeter = 1 kilogram per cubic meter)
  sum(h$socmean * h$bdodmean * h$thickness_meters, na.rm = TRUE)
  # estimate "ocs" from modeled organic carbon density in 0-5, 5-15, 15-30 intervals
  #  (sum the product of "ocd" and thickness in meters)
  sum(h$ocdmean * h$thickness_meters, na.rm = TRUE)