Back to data catalog
OpenAPI Spec
Explore the OpenAPI spec for OpenEPI SoilGrids API
Git Repository
Explore the source code behind OpenEPI SoilGrids API
Client Libraries
Explore the client libraries for OpenEPI SoilGrids API
Documentation
Explore the documentation for OpenEPI SoilGrids API
The API is exclusively fetching data from ISRIC (International Soil Reference and Information Centre) - World Soil Information's WebDAV functionality. The service uses SoilGrids data, which is licensed under the CC BY 4.0 license. The data are available at 250 meter resolution.
The nature of the available soil data can be separated into two categories: soil type and soil properties. Soil type data is categorical and represents the dominant soil type at the queried location. The 30 available soil types are: Acrisols, Albeluvisols, Alisols, Andosols, Arenosols, Calcisols, Cambisols, Chernozems, Cryosols, Durisols, Ferralsols, Fluvisols, Gleysols, Gypsisols, Histosols, Kastanozems, Leptosols, Lixisols, Luvisols, Nitisols, Phaeozems, Planosols, Plinthosols, Podzols, Regosols, Solonchaks, Solonetz, Stagnosols, Umbrisols, and Vertisols. More information about the soil types can be found here.
Soil property data is continuous and represents the value of a specific soil property at the queried location and depth. The available soil properties are: Bulk density (bdod), Cation exchange capacity (cec), Coarse fragments (cfvo), Clay (clay), Nitrogen (nitrogen), Organic carbon density (ocd), Organic carbon stocks (ocs), pH water (phh2o), Sand (sand), Silt (silt), and Soil organic carbon (soc). The available depths are: 0-5cm, 5-15cm, 15-30cm, 30-60cm, 60-100cm, 100-200cm, and 0-30cm (the ocs property is only available for the 0-30cm depth and vice versa.) The available values are: mean, 0.05 quantile, median, 0.95 quantile, and uncertainty.
For more information about the data, please visit the SoilGrids FAQ.
The data is retrieved from the ISRIC WebDAV service through various raster files and processed to be served through the API. For example, soil types are mapped from integer values to the corresponding soil type names, and the units of the soil properties are added to responses. Additionally, some aggregation is performed to produce a summary of the soil types, which, given a bounding box, provides a mapping of each soil type to its number of occurrences in the bounding box.
Spatial Resolution
250m x 250m
Returns the values of the soil properties for the given location and depths. Note: The ocs property is only available for the 0-30cm depth and vice versa. If the depth and property are incompatible, the response will not include the property
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.soil import SoilClient
3from openepi_client.soil import AsyncSoilClient
4
5# sync
6
7# Get the mean and the 0.05 quantile of the soil
8# properties at the queried location and depths
9properties = ["clay", "silt"]
10depths = ["0-5cm", "5-15cm"]
11values = ["mean", "Q0.05"]
12soil_property = SoilClient.get_soil_property(
13 geolocation=GeoLocation(lat=60.1, lon=9.58),
14 depths=depths,
15 properties=properties,
16 values=values
17)
18
19# async
20
21# Get the mean and the 0.05 quantile of the soil
22# properties at the queried location and depths
23properties = ["clay", "silt"]
24depths = ["0-5cm", "5-15cm"]
25values = ["mean", "Q0.05"]
26soil_property = await AsyncSoilClient.get_soil_property(
27 geolocation=GeoLocation(lat=60.1, lon=9.58),
28 depths=depths,
29 properties=properties,
30 values=values
31)1import io.openepi.soil.api.SoilApi;
2import io.openepi.soil.model.*;
3import io.openepi.common.ApiException;
4import java.math.BigDecimal;
5import java.util.List;
6
7public class Main {
8 public static void main(String[] args) {
9 BigDecimal lon = new BigDecimal("9.58");
10 BigDecimal lat = new BigDecimal("60.1");
11 List<SoilDepthLabels> depths = List.of(SoilDepthLabels._0_5CM);
12 List<SoilPropertiesCodes> properties = List.of(SoilPropertiesCodes.BDOD);
13 List<SoilPropertyValueTypes> values = List.of(SoilPropertyValueTypes.MEAN);
14 SoilApi api = new SoilApi();
15 try {
16 // Get the soil information for the bdod property
17 SoilPropertyJSON response = api.getSoilPropertyPropertyGet(lon, lat, depths, properties, values);
18 SoilLayer bdod = response.getProperties().getLayers().get(0);
19
20 // Get the soil property unit and name
21 SoilMappedUnits bdodUnit = bdod.getUnitMeasure().getMappedUnits();
22 String bdodName = bdod.getName();
23
24 // Get the soil property mean value at depth 0-5cm
25 SoilDepthLabels bdodDepth = bdod.getDepths().get(0).getLabel();
26 BigDecimal bdodValue = bdod.getDepths().get(0).getValues().getMean();
27
28 System.out.println("Soil property: " + bdodName + ", Depht: " + bdodDepth + ", Value: " + bdodValue + " " + bdodUnit);
29 } catch (ApiException e) {
30 System.err.println("Exception when calling SoilApi#getSoilPropertyPropertyGet");
31 e.printStackTrace();
32 }
33 }
34}1import { SoilClient } from 'openepi-client';
2
3const client = new SoilClient();
4
5client.getSoilProperty({ lon: 9.58, lat: 60.1, depths: "0-5cm", properties: ["bdod"], values: "mean" }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});Returns the most probable soil type for the given location
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.soil import SoilClient
3from openepi_client.soil import AsyncSoilClient
4
5# sync
6
7# Get the most probable soil type at the queried location
8# and the probability of the top 4 most probable soil types
9soil_type = SoilClient.get_soil_type(
10 geolocation=GeoLocation(lat=60.1, lon=9.58),
11 top_k=4
12)
13
14# async
15
16# Get the most probable soil type at the queried location
17# and the probability of the top 4 most probable soil types
18soil_type = await AsyncSoilClient.get_soil_type(
19 geolocation=GeoLocation(lat=60.1, lon=9.58),
20 top_k=4
21)1import io.openepi.soil.api.SoilApi;
2import io.openepi.soil.model.SoilTypeJSON;
3import io.openepi.common.ApiException;
4import io.openepi.soil.model.SoilTypes;
5import java.math.BigDecimal;
6
7public class Main {
8 public static void main(String[] args) {
9 BigDecimal lon = new BigDecimal("9.58");
10 BigDecimal lat = new BigDecimal("60.1");
11 SoilApi api = new SoilApi();
12 try {
13 SoilTypeJSON response = api.getSoilTypeTypeGet(lon, lat, null);
14
15 SoilTypes mostProbableSoilType = response.getProperties().getMostProbableSoilType();
16 System.out.println("Most probable soil type: " + mostProbableSoilType);
17 } catch (ApiException e) {
18 System.err.println("Exception when calling SoilApi#getSoilTypeTypeGet");
19 e.printStackTrace();
20 }
21 }
22}1import { SoilClient } from 'openepi-client';
2
3const client = new SoilClient();
4
5client.getSoilType({ lon: 9.58, lat: 60.1 }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});Returns the a summary of the soil types present in the given bounding box, represented by a mapping of each soil type to the number of occurrences in the bounding box
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.soil import SoilClient
3from openepi_client.soil import AsyncSoilClient
4
5# sync
6
7# Get a summary of the soil types in the queried bounding box,
8# represented by a mapping of each soil type to the number
9# of occurrences in the bounding box
10soil_type_summary = SoilClient.get_soil_type_summary(
11 bounding_box=BoundingBox(
12 min_lat=60.1,
13 max_lat=60.12,
14 min_lon=9.58,
15 max_lon=9.6,
16 )
17)
18
19# async
20
21# Get a summary of the soil types in the queried bounding box,
22# represented by a mapping of each soil type to the number
23# of occurrences in the bounding box
24soil_type_summary = await AsyncSoilClient.get_soil_type_summary(
25 bounding_box=BoundingBox(
26 min_lat=60.1,
27 max_lat=60.12,
28 min_lon=9.58,
29 max_lon=9.6,
30 )
31)1import io.openepi.soil.api.SoilApi;
2import io.openepi.soil.model.*;
3import io.openepi.common.ApiException;
4import java.math.BigDecimal;
5import java.util.List;
6
7public class Main {
8 public static void main(String[] args) {
9 BigDecimal minLon = new BigDecimal("9.5");
10 BigDecimal maxLon = new BigDecimal("9.6");
11 BigDecimal minLat = new BigDecimal("60.1");
12 BigDecimal maxLat = new BigDecimal("60.12");
13
14 SoilApi api = new SoilApi();
15 try {
16 SoilTypeSummaryJSON response = api.getSoilTypeSummaryTypeSummaryGet(minLon, maxLon, minLat, maxLat);
17
18 // Get the summary of the soil types in the bounding box
19 List<SoilTypeSummary> summaryList = response.getProperties().getSummaries();
20
21 // get the soil type and the number of occurrences
22 SoilTypes soilType1 = summaryList.get(0).getSoilType();
23 int count1 = summaryList.get(0).getCount();
24 SoilTypes soilType2 = summaryList.get(1).getSoilType();
25 int count2 = summaryList.get(1).getCount();
26
27 System.out.println("Soil type: " + soilType1 + ", count: " + count1);
28 System.out.println("Soil type: " + soilType2 + ", count: " + count2);
29 } catch (ApiException e) {
30 System.err.println("Exception when calling SoilApi#getSoilTypeSummaryTypeSummaryGet");
31 e.printStackTrace();
32 }
33 }
34}1import { SoilClient } from 'openepi-client';
2
3const client = new SoilClient();
4
5client.getSoilTypeSummary({ min_lon: 9.58, max_lon: 10.58, min_lat: 60.1, max_lat: 62.1 }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});