API quickstart

cURL

curl --get 'https://api.opensoil.net/v1/soil/location' \
  --data-urlencode 'latitude=39.7102' \
  --data-urlencode 'longitude=-111.8363' \
  --data-urlencode 'properties=ph,organic_matter,clay' \
  --data-urlencode 'depth_top_cm=0' \
  --data-urlencode 'depth_bottom_cm=30'

JavaScript

const params = new URLSearchParams({
  latitude: "39.7102",
  longitude: "-111.8363",
  properties: "ph,organic_matter,clay",
  depth_top_cm: "0",
  depth_bottom_cm: "30",
});

const response = await fetch(
  `https://api.opensoil.net/v1/soil/location?${params}`,
  { headers: { Accept: "application/json" } },
);

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.error.code}: ${problem.error.message}`);
}

const result = await response.json();
console.table(result.observations.map((observation) => ({
  property: observation.property.id,
  value: observation.value,
  unit: observation.unit,
  top_cm: observation.depth.top_cm,
  bottom_cm: observation.depth.bottom_cm,
  data_kind: observation.data_kind,
  provider: observation.source.provider,
})));

Search observed laboratory pedons

The response is GeoJSON and can be passed directly to D3 or another mapping library.

curl --get 'https://api.opensoil.net/v1/pedons' \
  --data-urlencode 'bbox=-112.5,39.5,-111.5,40.0' \
  --data-urlencode 'limit=100'

After choosing a feature's provider pedon_key, inspect its reported horizons:

curl --get 'https://api.opensoil.net/v1/pedons/922' \
  --data-urlencode 'properties=ph,organic_carbon,sand,silt,clay' \
  --data-urlencode 'depth_top_cm=0' \
  --data-urlencode 'depth_bottom_cm=100'

Do not select the nearest pedon and present it as a measurement for another location. The search endpoint is for discovery; scientific representativeness requires separate evidence.

Python over HTTP

This is an ordinary HTTP example, not an OpenSoil Python package.

import json
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({
    "latitude": 39.7102,
    "longitude": -111.8363,
    "properties": "ph,organic_matter,clay",
    "depth_top_cm": 0,
    "depth_bottom_cm": 30,
})
request = Request(
    f"https://api.opensoil.net/v1/soil/location?{query}",
    headers={"Accept": "application/json"},
)

with urlopen(request, timeout=15) as response:
    result = json.load(response)

for observation in result["observations"]:
    print(observation["property"]["id"], observation["value"], observation["unit"])

Before using a value

Check data_kind, depth, measurement_method, source, transformations, warnings, and cache. A successful HTTP response does not establish fitness for an agronomic, environmental, engineering, or regulatory decision.