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

Providers with experimental or supported status can have deployed, tested adapters. Supported carries the stronger reliability maturity claim. 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.