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.1.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. Only supported means a functional, tested adapter is deployed.

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 provider in 0.1.0
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.

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.

Pagination

No current endpoint paginates. Catalogs are bounded registries and the point query is bounded in the provider adapter. Future collection and area endpoints will use explicit cursors rather than silent truncation.