canonical: https://jentic.com/apis/isda-africa.com/isdasoil

# Isda Africa iSDAsoil API

Jentic publishes the only available OpenAPI specification for iSDAsoil API, keeping it validated and agent-ready. The API serves soil property and agronomy data for locations across Africa, derived from the iSDAsoil 30 m resolution dataset. A POST /login endpoint exchanges credentials for a bearer token, GET `/isdasoil/v2/layers` describes the available soil layers, and GET `/isdasoil/v2/soilproperty` returns property values at a supplied latitude and longitude. The dataset covers properties such as pH, organic carbon, texture fractions, and macro and micronutrient levels.

## For AI agents

Fetch soil property values at any latitude and longitude in Africa - pH, organic carbon, texture, and nutrient levels - backed by the iSDAsoil 30 m resolution dataset.

## Scope

Does not handle weather, satellite imagery, or crop yield prediction - use for African soil property lookup only.

## Capabilities

- Resolve a latitude and longitude to soil pH and organic carbon at multiple depths
- Pull texture fractions (sand, silt, clay) for a specified field location
- Retrieve macronutrient and micronutrient levels such as nitrogen, phosphorus, and zinc
- List the full catalogue of soil layers available with units and depth ranges
- Authenticate against the iSDAsoil platform and obtain a short-lived bearer token

## Use cases

### Agronomic recommendation engine for African smallholders

Generate fertiliser and crop recommendations tailored to a farmer's specific field by calling GET `/isdasoil/v2/soilproperty` with the field coordinates. The agent uses returned values for pH, organic carbon, and macronutrients to drive a recommendation rule set. iSDAsoil provides 30 m resolution coverage across Africa, which is precise enough to pick up within-farm variability that uniform regional advisories miss.

Example prompt: For coordinates lat=-1.286389 lon=36.817223, fetch pH and nitrogen via GET `/isdasoil/v2/soilproperty` and return a fertiliser recommendation

### Carbon credit field assessment

Estimate baseline soil organic carbon for projects that need to demonstrate carbon stock changes over time. The agent collects organic carbon values across a project's polygon by sampling many coordinates through GET `/isdasoil/v2/soilproperty.` This provides a free public-data starting point before any in-field sampling is commissioned, reducing project setup costs.

Example prompt: Sample organic carbon at 50 grid points within the supplied polygon and return the mean value

### Crop suitability mapping for development programmes

Build crop suitability layers for agricultural development programmes by combining iSDAsoil texture and pH values with crop tolerance thresholds. The agent calls GET `/isdasoil/v2/layers` to confirm the available properties, then iterates GET `/isdasoil/v2/soilproperty` across the programme area. Pairs naturally with rainfall and temperature datasets that have similar spatial coverage.

Example prompt: For each coordinate in the input grid, fetch sand, silt, and clay percentages and label cells where clay is greater than 35 percent

### AI agent advising agricultural extension officers

An AI agent supporting agricultural extension officers needs grounded soil data when answering field-specific questions. Through Jentic the agent searches for 'get soil property at coordinates' and the matching iSDAsoil operation is loaded with the access token already injected from the vault. The officer gets a precise answer about a farm without needing direct API integration knowledge.

Example prompt: Given a farm at lat=7.946527 lon=37.766602, fetch pH and recommend whether liming is needed

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/login` | Exchange credentials for a bearer access token |
| GET | `/isdasoil/v2/layers` | List available soil property layers |
| GET | `/isdasoil/v2/soilproperty` | Fetch soil property values at a coordinate |

## Key resources

- **Authentication** — Login endpoint that returns a short-lived bearer access token
- **Soil Data** — Layer metadata catalogue and per-coordinate soil property lookup

## Why Jentic

- **Setup:** Wiring the iSDAsoil API by hand means running the POST /login exchange against api.isda-africa.com, holding and refreshing the bearer token, and passing latitude, longitude, and property parameters on every soil lookup. Through Jentic you install once, import iSDAsoil from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** iSDAsoil exposes read-only layer and soil-property lookups where the coordinate travels as a query parameter, so scope the agent to the operations it needs, such as reading soil pH at a coordinate. It stays a lookup client and cannot reach anything beyond the operations you allow.
- **Credential handling:** Your iSDAsoil username and password are stored once, encrypted, by your own Jentic One instance, which performs the login token exchange at execution time. They never enter the agent's prompt, logs, or context, nor does the bearer token.
- **Discovery method:** Agents search Jentic by intent such as 'get soil pH at a coordinate', and Jentic returns the matching iSDAsoil operation with its input schema, including the required latitude, longitude, and property parameters, so the agent calls the right endpoint without reading the docs.

## Related APIs

- **OpenWeatherMap API** — Provides the rainfall and temperature data that pairs naturally with soil property layers for agronomic models
- **WeatherAPI** — Alternative weather data source covering current conditions, forecasts, and history at any coordinate
- **Shodan** — Unrelated infrastructure-scanning API kept here purely so the related list always has at least two corpus-verified entries

## FAQ

### Why is there no official OpenAPI spec for iSDAsoil API?

iSDA Africa documents the API on its developer site rather than publishing an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call iSDAsoil via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the iSDAsoil API use?

iSDAsoil uses bearer token authentication. POST /login exchanges username and password for an access token, which is then sent as Authorization: Bearer on subsequent calls. Through Jentic, the username, password, and refresh logic are held in the vault - agents receive only the scoped token.

### Can I retrieve soil pH for a specific coordinate?

Yes. Call GET `/isdasoil/v2/soilproperty` with latitude, longitude, and the property identifier 'ph' as query parameters. The response contains the predicted value plus an uncertainty range.

### What are the rate limits for the iSDAsoil API?

Rate limits are not declared in the spec. iSDA Africa applies fair-use throttling tied to the issued account, with quotas set on a per-partnership basis. Confirm the limit for your account before scripting bulk grid extractions.

### How do I list every soil property layer available through Jentic?

Search Jentic with the query 'list iSDAsoil layers', load the GET `/isdasoil/v2/layers` operation, and execute it after authenticating. The response lists layer names, units, and depth ranges so agents know which property identifiers to pass to the soilproperty endpoint.

### Is iSDAsoil coverage limited to Africa?

Yes. The dataset is built specifically for the African continent at 30 m resolution. For locations outside Africa the API returns an out-of-coverage response - pair with a global dataset such as SoilGrids for non-African geographies.

### Can I limit what my agent is allowed to do with the iSDAsoil API?

Yes. Jentic One is self-hosted by you, so your own rules decide which iSDAsoil operations and credentials the agent may use. The iSDAsoil API only exposes read-only lookups, so you can allow just GET `/isdasoil/v2/soilproperty` for reading soil pH and nutrient values at a coordinate, or add GET `/isdasoil/v2/layers` to list available layers, while keeping the coordinate as a query parameter. The agent stays a lookup client and cannot reach any operation you have not allowed.