Skip to content

Getting started

1. Check the service

curl --fail https://api.opensoil.net/health

The response identifies the service and version. It does not call a provider, so use it to check the OpenSoil process—not USDA availability.

2. Inspect supported providers and properties

curl --fail https://api.opensoil.net/v1/providers
curl --fail https://api.opensoil.net/v1/properties

Only a provider with status supported has a deployed adapter and routine tests. planned and researching records are catalog entries, not promises that queries work.

3. Query one point

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

Read the top-level warnings before the observations. For USDA SSURGO, the requested coordinate selects a mapped unit; it does not prove which component exists at that exact point.

4. Trace one value

Every observation includes:

  • data_kind, currently mapped_survey for USDA SDA;
  • original property name, value, unit, depth, and method;
  • provider, organization, source record identifier, retrieval time, and citation;
  • map-unit, component, and horizon context;
  • transformations and warnings;
  • cache storage time, hit state, and age.

5. Inspect the raw provider result

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

The raw route uses the same bounded provider query but returns USDA's JSON+COLUMNNAME payload inside an explicitly labeled wrapper. Do not assume raw schemas are stable.