Endpoints and responses

The generated OpenAPI schema is authoritative for parameter types and response fields. This page explains behavior and scientific meaning.

GET /health

Returns OpenSoil process health and version. It deliberately avoids an upstream call.

{"status":"healthy","service":"OpenSoil API","version":"0.2.0"}

GET /v1

Returns version, maturity, documentation links, supported providers, and an experimental warning.

GET /v1/providers

Lists working and candidate source systems. Status values are researching, planned, experimental, supported, temporarily_unavailable, and deprecated. Both experimental and supported can be operational; only supported carries the stronger reliability maturity claim.

GET /v1/properties

Publishes canonical identifiers, names, units, aliases, conversion notes, method warnings, and support status. The vocabulary covers pH, carbon, organic matter, texture, CEC, bulk density, nitrogen, phosphorus, EC, base cations, micronutrients, selenium, and arsenic.

GET /v1/soil/location

Parameter	Required	Rules
latitude	yes	WGS84, −90 to 90
longitude	yes	WGS84, −180 to 180
providers	no	Defaults to usda_sda; one mapped-location provider per request
properties	no	Comma-separated; maximum eight; defaults to pH, OM, sand, silt, clay
depth_top_cm	no	0–199; defaults to 0
depth_bottom_cm	no	greater than top, at most 200; defaults to 200

The response contains query echo, mapped_survey data kind, zero or more observations, intersecting map-unit summaries, cache metadata, and warnings. A valid empty result is HTTP 200 with a warning; provider and validation failures use structured non-200 responses.

GET /v1/providers/{provider_id}/raw/location

Accepts the same bounded location and property inputs. The wrapper labels the provider and cache while upstream_response preserves the exact provider JSON. Raw responses are not normalized and are not promised to remain stable.

GET /v1/pedons

Returns an RFC 7946-style GeoJSON FeatureCollection of NCSS laboratory pedon points. The collection uses GeoJSON foreign members for provider, query, cache, truncation, and warnings.

Parameter	Required	Rules
bbox	yes	min_lon,min_lat,max_lon,max_lat in WGS84; ordered southwest to northeast
provider	no	Defaults to ncss_lab_data_mart; aliases ncss, kssl, and lab_data_mart are accepted
limit	no	1–500; defaults to 100

Bounding boxes are limited to five degrees in either dimension and four square degrees overall. Results are ordered by provider pedon key. When another matching record exists beyond limit, truncated is true; narrow the bounding box rather than treating the response as complete.

Each feature explicitly sets representative_of_bbox to false. Coordinates are provider records whose accuracy varies, especially for older pedons.

GET /v1/pedons/{pedon_key}

Returns overlapping laboratory layers and requested observations for one NCSS provider pedon key. Parameters include up to eight canonical properties, depth_top_cm, and depth_bottom_cm. Version 0.2 normalizes pH in water, Walkley-Black organic carbon, sand, silt, clay, one-third-bar bulk density, ammonium-acetate CEC at pH 7, total nitrogen, and saturated-paste electrical conductivity when reported.

The response preserves lab sample and layer keys, horizon depth/designation, original column, reported string, canonical numeric value when uncensored, method code, location, citation, cache time, and warnings. For a value such as <0.1, value remains null, reported_value is <0.1, value_qualifier is less_than, and reporting_limit is 0.1. OpenSoil does not replace a censored result with its limit.

GET /v1/providers/{provider_id}/raw/pedons/{pedon_key}

Runs the same fixed, bounded laboratory query as the normalized detail endpoint and exposes USDA's JSON+COLUMNNAME table in the raw wrapper. Companion morphological pedon data are not part of SDA's lab tables and are not silently joined.

Canonical observation excerpt

{
  "property": {"id": "ph", "name": "Soil pH"},
  "value": 7.2,
  "unit": "pH",
  "depth": {"top_cm": 0, "bottom_cm": 15},
  "data_kind": "mapped_survey",
  "measurement_method": "1:1 soil-water suspension",
  "source": {
    "provider": "usda_sda",
    "organization": "USDA Natural Resources Conservation Service",
    "record_id": "provider horizon key",
    "original_property_name": "ph1to1h2o_r",
    "original_value": 7.2,
    "original_unit": "pH"
  },
  "transformations": [],
  "warnings": ["Mapped survey data are not a laboratory observation at this point."]
}

The actual response includes complete original depth, method, retrieval time, citation, URL, location, uncertainty, licensing placeholder, and map-unit/component/horizon context.

Collection limits

Catalogs are bounded registries and point/detail queries are bounded in their adapters. Pedon discovery uses an explicit limit plus truncated; it does not claim pagination stability over a continuously updated provider database. Future larger collections will use explicit cursors rather than silent truncation.