Back to data catalog
Soil API
Global soil information based on SoilGrids-data
OpenAPI Spec
Specification of all endpoints available in the soil api.
Github
Explore the source code behind the soil api.
More info
Data sources
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.
Processing
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.
Examples
Example 1
Retrieving the most probable soil type at the queried location.
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}1// Get the most probable soil type at the queried location
2const response = await fetch(
3 "https://api.openepi.io/soil/type?" +
4 new URLSearchParams({
5 lon: "9.58",
6 lat: "60.1",
7 })
8)
9const json = await response.json()
10
11// Get the most probable soil type
12const mostProbableSoilType = json.properties.most_probable_soil_type
13
14console.log(`Most probable soil type: ${mostProbableSoilType}`)
151from httpx import Client
2
3with Client() as client:
4 # Get the soil type at the queried location
5 # and the probability of the top 3 most probable soil types
6 response = client.get(
7 url="https://api.openepi.io/soil/type",
8 params={"lat": 60.1, "lon": 9.58, "top_k": 3},
9 )
10
11 json = response.json()
12
13 # Get the soil type and probability for the second most probable soil type
14 soil_type = json["properties"]["probabilities"][1]["soil_type"]
15 probability = json["properties"]["probabilities"][1]["probability"]
16
17 print(f"Soil type: {soil_type}, Probability: {probability}")
18Example 2
Retrieving the mean of the soil property at the queried location and depth.
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}1// Get the mean value of the soil property at the queried location and depth
2const response = await fetch(
3 "https://api.openepi.io/soil/property?" +
4 new URLSearchParams({
5 lon: "9.58",
6 lat: "60.1",
7 depths: "0-5cm",
8 properties: "bdod",
9 values: "mean",
10 })
11)
12const json = await response.json()
13
14// Get the soil information for the bdod property
15const bdod = json.properties.layers[0]
16
17// Get the soil property unit and name
18const bdodUnit = bdod.unit_measure.mapped_units
19const bdodName = bdod.name
20
21// Get the soil property mean value at depth 0-5cm
22const bdodDepth = bdod.depths[0].label
23const bdodValue = bdod.depths[0].values.mean
24
25console.log(
26 `Soil property: ${bdodName}, Depth: ${bdodDepth}, Value: ${bdodValue} ${bdodUnit}`
27)
281from httpx import Client
2
3with Client() as client:
4 # Get the mean and the 0.05 quantile of the soil properties at the queried location and depths
5 response_multi = client.get(
6 url="https://api.openepi.io/soil/property",
7 params={
8 "lat": 60.1,
9 "lon": 9.58,
10 "depths": ["0-5cm", "100-200cm"],
11 "properties": ["bdod", "phh2o"],
12 "values": ["mean", "Q0.05"],
13 },
14 )
15
16 json_multi = response_multi.json()
17
18 # Get the soil information for the phh2o property
19 phh2o = json_multi["properties"]["layers"][1]
20
21 # Get the soil property unit and name
22 phh2o_name = phh2o["name"]
23 phh2o_unit = phh2o["unit_measure"]["mapped_units"]
24
25 # Get the soil property 0.05 quantile value at depth 100-200cm
26 phh2o_depth = phh2o["depths"][1]["label"]
27 phh2o_value = phh2o["depths"][1]["values"]["Q0.05"]
28
29 print(
30 f"Soil property: {phh2o_name}, Depth: {phh2o_depth}, Value: {phh2o_value} {phh2o_unit}"
31 )
32Example 3
Get a summary of the soil types in the queried bounding box.
1mport 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}1// Get a summary of the soil types in the queried bounding box, represented
2// by a mapping of each soil type to the number of occurrences in the bounding box
3const response = await fetch(
4 "https://api.openepi.io/soil/type/summary?" +
5 new URLSearchParams({
6 min_lon: "9.5",
7 max_lon: "9.6",
8 min_lat: "60.1",
9 max_lat: "60.12",
10 })
11)
12const json = await response.json()
13
14// Get the summary of the soil types in the bounding box
15const summaryList = json.properties.summaries
16
17// Get the soil type and the number of occurrences
18const soilType1 = summaryList[0].soil_type
19const count1 = summaryList[0].count
20const soilType2 = summaryList[1].soil_type
21const count2 = summaryList[1].count
22console.log(`Soil type: ${soilType1}, Count: ${count1}`)
23console.log(`Soil type: ${soilType2}, Count: ${count2}`)
241from httpx import Client
2
3with Client() as client:
4 # Get a summary of the soil types in the queried bounding box, represented
5 # by a mapping of each soil type to the number of occurrences in the bounding box
6 response = client.get(
7 url="https://api.openepi.io/soil/type/summary",
8 params={"min_lon": 9.5, "max_lon": 9.6, "min_lat": 60.1, "max_lat": 60.12},
9 )
10
11 json = response.json()
12
13 # Get the summary of the soil types in the bounding box
14 summary_list = json["properties"]["summaries"]
15
16 # Get the soil type and the number of occurrences
17 soil_type_1 = summary_list[0]["soil_type"]
18 count_1 = summary_list[0]["count"]
19 soil_type_2 = summary_list[1]["soil_type"]
20 count_2 = summary_list[1]["count"]
21
22 print(f"Soil type: {soil_type_1}, Count: {count_1}")
23 print(f"Soil type: {soil_type_2}, Count: {count_2}")
24