SoilGrids API User Guide

Table of Contents

Setup
Construct the URL
Make the Request
Parse the Response
Error Handling
Use the Data
Examples
Soil Characteristics Mapping

This guide provides step-by-step instructions on how to use the SoilGrids API to retrieve soil characteristics for a specific location. The aim is to replicate the logic in the CFT, which retrieves the soil class for a given latitude and longitude. for more information on SoilGrids API visit https://rest.isric.org/soilgrids/v2.0/docs

Setup 

Before we begin, make sure you have a tool to make HTTP requests. This could be a command-line tool like curl, a library in a programming language (e.g., requests in Python), or a graphical interface like Postman.

Construct the URL 

The URL you will request data from depends on the endpoint you are using. There are two endpoints used in the Python function: properties and classification.

The base URL is: https://rest.isric.org/soilgrids/v2.0/

For the properties endpoint, the URL is:

https://rest.isric.org/soilgrids/v2.0/properties/query?lon={longitude}&lat={latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty

For the classification endpoint, the URL is:

https://rest.isric.org/soilgrids/v2.0/classification/query?lon={longitude}&lat={latitude}&number_classes=0

Replace {longitude} and {latitude} with the actual longitude and latitude of the location you’re interested in.

Make the Request 

Send a GET request to the constructed URL. The server will return a JSON object with the requested data.

Parse the Response 

The response from the properties endpoint contains mean values for the clay and sand properties. You will need to parse the JSON to extract these values.

If the mean value of sand is greater than 70 and clay is less than 8, the soil is classified as sandy. If not, you will need to make another request to the classification endpoint.

The response from the classification endpoint contains a wrb_class_name which represents the soil class. This class name can be mapped to a set of predefined soil characteristics.

Error Handling 

If the response status code is not 200, handle the error appropriately. Depending on your application, you may want to retry the request, log the error, or inform the user.

Use the Data 

Once you have the soil class, you can use this information in your application.

Examples 

Below are examples of how to use the SoilGrids API in different programming languages:

Using the Soil Grids Web API interface 

The SoilGrids Web API interface is a graphical interface that allows you to make requests to the SoilGrids API and view the response. You can use this interface to test your requests and see the response.

To use the interface to replicate the results shown in the CFT, follow these steps:

Sand and Clay

Navigate to https://rest.isric.org/soilgrids/v2.0/
Select the 3rd request in the list: properties/query
Click on the Try it out button
Substitute the {longitude} and {latitude} placeholders with the actual longitude and latitude of the location you’re interested in
Remove all properties except clay and sand
For Depth, select 0-5cm
For Value, select mean and uncertainty
Press the Execute button

Determining the Soil Class

Navigate to https://rest.isric.org/soilgrids/v2.0/
Select the 1st request in the list: classification/query
Click on the Try it out button
Substitute the {longitude} and {latitude} placeholders with the actual longitude and latitude of the location you’re interested in
For Number of classes, select 0
Press the Execute button

Python 

import requests

# replace with actual longitude and latitude
longitude = 0
latitude = 0

# make request to properties endpoint
response = requests.get(f"https://rest.isric.org/soilgrids/v2.0/properties/query?lon={longitude}&lat={latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty")

# parse response
data = response.json()
# continue with your application logic...

Node.js 

const axios = require('axios');

// replace with actual longitude and latitude
const longitude = 0;
const latitude = 0;

// make request to properties endpoint
axios.get(`https://rest.isric.org/soilgrids/v2.0/properties/query?lon=${longitude}&lat=${latitude}&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty`)
  .then(response => {
    const data = response.data;
    // continue with your application logic...
  })
  .catch(error => {
    console.error(error);
  });

Curl (Command Line)

# replace with actual longitude and latitude
longitude=0
latitude=0

# make request to properties endpoint
curl "https://rest.isric.org/soilgrids/v2.0/properties/query?lon=$longitude&lat=$latitude&property=clay&property=sand&depth=0-5cm&value=mean&value=uncertainty"

Remember to replace the 0 values for longitude and latitude with the actual coordinates of the location you’re interested in.

Soil Characteristics Mapping 

The soil class obtained from the API response corresponds to a set of soil characteristics defined in your application. Below is a table that outlines this mapping:

Soil Class Mapping
Soil Class (API Response)	Soil Characteristic (Application Value)	Description
Sandy Soils (mean sand > 70%, mean clay < 8%)	1	Sandy Soils
Gleysols	2	Wetland Soils
Andosols	3	Volcanic Soils
Podzols	4	Spodic Soils
Leptosols, Vertisols, Kastanozems, Chernozems, Phaeozems, Luvisols, Alisols, Albeluvisols, Solonetz, Calcisols, Gypsisols, Umbrisols, Cambisols, Regosols	5	High Activity Clay Soils
Others (or when soil class is not available)	6	Low Activity Clay Soils

Please note that if the mean sand content is greater than 70% and the mean clay content is less than 8%, the soil is classified as sandy. Otherwise, the classification endpoint is used to determine the soil class.