How do I sign up to use the iSDAsoil API?

Sign up by creating a username and password on our sign up page. This will be required to obtain an access token.

What can I do with the iSDAsoil API?

Our API will allow you to retrieve soil property and agronomy information for any location within Africa (excluding water bodies and deserts) by providing values for latitude and longitude. Most of our layers are at 30m resolution, except those provided by third parties. For further details on the available data, see our FAQ.

How do I query iSDAsoil?

You can access the full interactive documentation here. Data is accessed via the isdasoil/v2/soilproperty endpoint. If you are a first-time API user, you should begin by querying the isdasoil/v2/layers endpoint. Doing so will return metadata on the layers (soil properties) that can be accessed via the API, such as depths, units, uncertainty and the type of data returned. The property name (specified by value of the “property” object, e.g. “carbon_organic”) can then be used to request a property from the isdasoil/v2/soilproperty endpoint.

You must specify the latitude and longitude of the desired location, whereas other query parameters (depth and property) are optional. If you don’t specify the optional parameters, all of them are returned by default. If you require only a single property or depth, it’s always best to specify these other parameters, as doing so will improve performance compared to requesting all properties.

In order to access the API, you will first need to obtain a token from the /login endpoint. This token must then be used to make authenticated calls. See below for a Python code sample.

import requests

username = "<ADD YOUR USERNAME HERE>"
password = "<ADD YOUR PASSWORD HERE>"

base_url = "https://api.isda-africa.com"

# First call the login endpoint to get the access token. Token expiry: 60 minutes
payload = {"username": username, "password": password}
response = requests.post(f"{base_url}/login", data=payload)
access_token = response.json().get("access_token")

# Then use the access token to call the soilproperty endpoint. Get the ph value for a location in Kenya at 0-20cm depth.
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
    f"{base_url}/isdasoil/v2/soilproperty?lat=-0.7196&lon=35.2400&property=ph&depth=0-20",
    headers=headers,
)

response = response.json()

print(
    f"ph value: {response['property']['ph'][0]['value']['value']}"
    f" (uncertainty: {response['property']['ph'][0]['uncertainty'][1]['lower_bound']}-"
    f"{response['property']['ph'][0]['uncertainty'][1]['upper_bound']})"
)