API reference

Base URL: https://soilpoint.dev · Free · US coverage only · No key required to start

Endpoint

GET /v1/soil

Parameter	Type	Required	Description
`lat`	number	yes	Latitude in WGS84 decimal degrees (−90 to 90)
`lon`	number	yes	Longitude in WGS84 decimal degrees (−180 to 180)

Keyless example:

curl "https://soilpoint.dev/v1/soil?lat=37.368402&lon=-121.771"

API keys & rate limits

Keys are optional. Without one you share an IP-based bucket; with one you get a dedicated, higher-limit bucket. Keys never expire.

How to get a key: use the homepage — try a coordinate, then hit "Get my key" in the panel that appears.

Send your key in the x-api-key request header:

curl -H "x-api-key: sp_live_..." "https://soilpoint.dev/v1/soil?lat=42.024&lon=-93.648"

Tier	Per minute	Per day
Keyless (per IP)	60 req	1,000 req
Keyed (per key)	300 req	20,000 req

Over the limit → 429 with {"error":{"code":"RATE_LIMITED",...}} and a Retry-After header indicating seconds to wait.

Response fields

All fields are present in every 200 response. Fields marked nullable return null for Miscellaneous land areas (urban land, water bodies, pits) where soil properties are undefined by design.

Field	Type	Nullable	Description
`lat`	number		Echoed latitude from your request
`lon`	number		Echoed longitude from your request
`mukey`	string		SSURGO map unit key for this point
`mapUnitName`	string		Human-readable map unit name (e.g. "Diablo clay, 9 to 15 percent slopes")
`soilSeries`	string	yes	Soil series name of the dominant component
`componentKind`	string		Component kind — "Series" for named soils; "Miscellaneous area" for urban/water/etc.
`componentPct`	number		Percentage of the map unit this dominant component occupies (0–100)
`texture`	string	yes	USDA textural class of the dominant surface horizon (e.g. "clay", "sandy loam")
`drainageClass`	string	yes	USDA drainage class (e.g. "well drained", "somewhat poorly drained")
`hydrologicGroup`	string	yes	NRCS hydrologic soil group — A, B, C, D, or dual (e.g. "B/D")
`awc`	number	yes	Available water capacity (cm/cm fraction), depth-weighted over 0–30 cm
`ph`	number	yes	pH (1:1 water method), depth-weighted over 0–30 cm
`organicMatter`	number	yes	Organic matter (% by weight), depth-weighted over 0–30 cm
`nccpi`	number	yes	National Commodity Crop Productivity Index (0–1). Best-effort; often null for non-cropland.
`nccpiClass`	string	yes	Qualitative NCCPI class (e.g. "High", "Medium") derived from the index value
`depthWindowCm`	array		Depth range used for weighted averages, as `[min, max]`. Default `[0, 30]`.
`dataVintage`	string	yes	SSURGO survey version date for this area (ISO 8601 date string)
`stale`	boolean		`true` when the response was served from cache during an upstream outage
`cachedAt`	string	yes	ISO 8601 timestamp of when this result was last fetched from upstream
`dataSource`	string		Data source identifier — currently `"SSURGO/SDA"`
`surveyDisclaimer`	string		Short disclaimer string from the survey authority

Errors

All errors return a JSON envelope: {"error":{"code":"...","message":"..."}}

Code	HTTP	Meaning
`INVALID`	400	Missing or out-of-range `lat` or `lon` parameter
`NO_SOIL_DATA`	404	Point is in the ocean, outside US coverage, or in a gap in the survey
`RATE_LIMITED`	429	Rate limit exceeded — see `Retry-After` response header
`SDA_UPSTREAM_ERROR`	502	USDA Soil Data Access returned malformed or unexpected data
`SDA_UNAVAILABLE`	503	Upstream is down and no cached result is available for this point

Notes & honest limits

US coverage only. SSURGO covers the contiguous US, Alaska, Hawaii, and US territories. Ocean and off-coverage points return NO_SOIL_DATA.
Dominant component. Each map unit may contain several soil components. SoilPoint returns the one with the highest percentage. Use componentPct to judge how representative it is.
NCCPI is best-effort. NCCPI is fetched in a separate query after the main response so it never blocks your request. It is null for non-cropland and some survey areas.
Not for regulatory determinations. Soil data is provided as-is for planning and exploration. It is not a substitute for on-site investigation and is not for regulatory or legal purposes. SoilPoint is not a USDA-endorsed product.
Resilience. SoilPoint caches results and continues serving stale answers during upstream outages. When stale is true, check cachedAt for the age of the cached result.
See our privacy notice for what we record when you call the API.

← Back to SoilPoint · Blog