UFFDA Developer API

crop_history

USDA NASS Cropland Data Layer (CDL). Annual crop classification at 30m resolution (2024 and 2025 vintages are natively 10m at the source), the contiguous United States (CONUS) only, 2008 through the latest published vintage (currently 2025). Request any 1–10 years via options.cdl_years — default is the trailing 8 years from the latest vintage. Per-year value_label reads like "Corn" or "Soybeans". Fields outside CONUS get a null value and a note in properties.errors.

How the crop is sampled — read this before you trust a year. Each year's value is a single 30 m CDL pixel, read at one representative point inside your field polygon. It is not a majority vote, an area-weighted mode, or any other summary of the whole field. For a uniform field that distinction does not matter. For a field that was split, planted in strips, or is genuinely mixed, the answer is whatever crop happens to sit at that one point — not necessarily what covers most of the field. That point is chosen to sit inside the field, including on fields with holes or concave, oddly shaped boundaries — a plain average of the corner coordinates can land outside those. The point is inside your boundary; the 30 m pixel around it may not be, so near a road or farmstead you can still get a read that isn't your crop. If you need a field-level answer on heterogeneous ground, sample several points yourself and reconcile them. The method string and the sampling block on crop_history say the same thing in machine-readable form.

What the accuracy figure does — and does not — measure. crop_history.confidence.accuracy_pct (~92% for US corn/soy, lower for minor crops) is the user's accuracy USDA publishes in the 2024 CDL metadata — one pixel, measured nationwide. It describes the CDL dataset, not your field and not the one point sampled above. Treat it as background on the source, not a confidence score for the value you just got back.

Each year in crop_history.values[] carries a status field:

• okA CDL crop class was returned for this year. value and value_label are populated.
• nodataGenuine absence — CDL has no classification at this point for this year (unreleased year, off-coverage pixel). Not a failure; retrying will return the same answer.
• unavailableThe lookup didn't come back — a transient upstream issue. The year entry also carries retryable: true and a plain-language note. Retrying the call is the right move; a future call will re-fetch rather than serve the failed result from cache.

The block also carries an availability roll-up across all requested years: "complete" (all years returned a result), "partial" (some years unavailable — retry will fill gaps), or "unavailable" (no years came back). Check this field first if you need a complete history; branch on individual status values for per-year handling.

soil

SSURGO (the USDA’s detailed US soil survey) as primary for CONUS fields (survey-grade, area-weighted over map units intersecting your polygon); SoilGrids 2.0 as companion (global model estimate, read at a single representative point inside your polygon, with SoilGrids’ own Q0.05/Q0.95 uncertainty band). Outside CONUS, SoilGrids is primary — the whole soil answer rather than a second opinion.

SSURGO contributes Soil Organic Matter (SOM, % by weight) as a single 0–30 cm topsoil aggregate (key: som@0-30). SOC and per-depth carbon slices come only from the SoilGrids companion (keys: soc@0-15, soc@15-30, soc@0-30, units: g/kg). SOM and SOC are different numbers — the Van Bemmelen conversion (SOM ÷ 1.724) appears in the units block as a clearly-labeled illustrative estimate, never a measured value.

Other metrics: pH, clay, sand, silt, CEC (cation exchange capacity), nitrogen, bulk density. Both sources return per-depth slices for these (0–15, 15–30, 0–30 cm) — the single 0–30 cm key applies to soil organic matter alone, which is the one metric SSURGO genuinely publishes only as a topsoil aggregate. A depth_note field on CONUS soil blocks spells that out.

One exception worth planning for: nitrogen is a SoilGrids metric only. SSURGO does not carry it, so on a CONUS field whose SoilGrids companion has not hydrated — or has no coverage at all — nitrogen is absent from the response entirely rather than present-and-null. Read it off the companion, not the primary block.

On CONUS, the first (cold) call for a field returns SSURGO quickly (sub-2s typical) with companion_state: "pending" — the SoilGrids companion is deferred. An immediate re-hit attempts to hydrate the SoilGrids companion; ISRIC's response time varies and can run 20+ seconds, occasionally exceeding our per-layer timeout — in that case soil comes back null with a note in properties.errors for that call. That's upstream ISRIC latency, not a bug on our end; retry after a short wait rather than immediately. To know whether the companion is there and whole, read enrichment.soil.companion_state. Do not test enrichment.soil.companion !== null as a completeness check — a companion object can be present and still be missing readings. Outside CONUS, SoilGrids is computed on the first call and this two-step pattern does not apply.

The companion_state field on CONUS responses tells you whether the SoilGrids companion is still hydrating, ready, incomplete, or never coming, without inspecting the companion object itself. Four values, plus absence:

• "pending"Not computed yet. Call again in a moment and it will hydrate.
• "partial"Some readings came back and some didn't. We fetch SoilGrids in two halves, and one half can fail on its own — so you may get bulk density, cation exchange capacity, nitrogen and silt while soil organic carbon, pH, clay and sand are absent, or the reverse. companion_missing_metrics lists exactly which readings are missing. We don't store a partial result, so calling again can still fill it in.
• "no_coverage"Terminal. ISRIC answered and has no SoilGrids values at this point. This is the one that matters for your retry logic: unlike "pending", calling again will never populate the companion. Treat SSURGO as the whole answer for this field.
• nullThe companion is present and complete — every metric we publish, at every depth. A half-filled companion reports "partial" instead.
• (absent)No companion_state key at all — the field is outside CONUS, where SoilGrids is the primary source. Read primary_state there instead.

Outside CONUS, read primary_state instead. Everything above answers a CONUS question — is the second opinion whole? Outside CONUS there is no second opinion: SoilGrids is the entire soil answer. So those responses carry primary_state with the same three meanings — null for present and complete, "partial" when some readings are missing (named in primary_missing_metrics, not cached, so calling again can still fill it), and "no_coverage" when ISRIC has nothing at this point. There is no "pending" — outside CONUS soil is computed on the first call.

Until 19 August 2026 these responses said nothing at all when a reading was missing, so a half-filled answer looked exactly like a whole one. If you cached soil values for non-US fields before that date, re-fetch them and check primary_state.

When soil comes back null, check whether it can ever come back. soil is null in two situations that used to be indistinguishable, and properties.errors now tells them apart. If the entry says the location has no soil data mapped, that is permanent — open water and permanent ice sit outside the soil model, and retrying returns the same answer. Any other soil error is a transient upstream problem and is worth retrying after a short wait. Before 19 August 2026 both said soilgrids-unavailable, so retry loops could spin forever on a field in the middle of an ocean.

// CONUS, first call (cold) — SoilGrids not yet computed. Call again to hydrate:
{ "companion": null, "companion_state": "pending" }

// CONUS, hydrated — every expected reading is present:
{ "companion": { /* SoilGrids values */ }, "companion_state": null }

// CONUS, but only some readings came back. Not cached — call again to fill it:
{
  "companion": { /* the readings that did arrive */ },
  "companion_state": "partial",
  "companion_missing_metrics": ["soc@0-15", "soc@15-30", "soc@0-30", "phh2o@0-15", "..."]
}

// CONUS, but ISRIC has nothing at this point. TERMINAL — retrying won't help:
{ "companion": null, "companion_state": "no_coverage" }

// Outside CONUS — SoilGrids is primary; the companion concept doesn't apply.
// Completeness is reported on the primary instead:
{ "companion": null, "primary_state": null }          // present and complete

// Outside CONUS, only some readings came back. Not cached — call again:
{
  "primary_state": "partial",
  "primary_missing_metrics": ["soc@0-15", "soc@15-30", "soc@0-30", "phh2o@0-15", "..."]
}

// Outside CONUS, ISRIC has nothing here. TERMINAL — retrying won't help:
{ "primary_state": "no_coverage" }

drought

US Drought Monitor — the latest weekly release. The vintage field carries the release date. The value_label reads like "D2 — Severe Drought". CONUS only.

Not public domain — carries a required verbatim credit. USDM permission terms require the exact NDMC/USDA/NOAA/NASA credit line returned in this layer's license.attribution field; copy it in full, don't shorten it to "US Drought Monitor."

land_cover

ESA WorldCover 2021 at 10m. Dominant class + proportions of others. The confidence.pct_in_class field tells you how much of your polygon was in the dominant class.

License: CC-BY-4.0 — attribution to ESA WorldCover is required; see this layer's license.attribution field for the citation to use.

weather

NASA POWER daily at a representative point inside your field (the same point used for derived.centroid), summarized over your requested window (default: trailing 12 months). NASA POWER's own grid is about half a degree wide, so which exact point you sample rarely changes the result. Summary metrics: growing degree days (GDD) total, precipitation total, average high and low temperature. The units block declares base and conversion for each.

forest_loss

Hansen Global Forest Change v1.12 (UMD / Google / USGS / NASA), 30 m, global, annual 2001–2024. License: CC-BY-4.0. Returns forest_loss_pct (share of the field with tree-cover loss since 2001), forest_loss_most_recent_year, and a forest_loss_detail block with per-year loss in hectares and pixels plus a total loss area.

Hansen measures tree-cover loss — harvest, fire, disease, and other disturbance — not deforestation specifically. The layer is useful for flagging loss events and tracking change over time; read the provenance envelope before drawing conclusions about cause.

protected_area

USGS Protected Areas Database of the United States (PAD-US) 3.0, 2022. License: CC0 public domain. Returns a 4-state overlap check against all US protected lands — federal, state, local, private, tribal, and marine — with true polygon intersection (not centroid proximity). US and territories only.

The response carries a state field with one of four values:

• no_overlapConfirmed all-clear — the field does not intersect any protected area per PAD-US 3.0.
• overlapOne or more protected areas intersect the field. overlap_ac, overlap_pct, and an areas array with per-unit name, manager type, GAP status, and acreage are included.
• out_of_coverageField is outside US / territory coverage — PAD-US does not apply.
• unavailableThe upstream PAD-US service could not be reached at query time. Try again; a no_overlap is only ever returned when the service confirmed it — never on a failed call.

A warning field appears when the PAD-US query exceeded its result-transfer limit — the overlap check may be incomplete for that field; verify against the upstream source.

irrigation

NASA LP DAAC LGRIP30 L3 V002 (Landsat-Derived Global Rainfed and Irrigated-Cropland Product), 30 m, CONUS, 2020 single-year snapshot. License: CC0 (NASA ESDIS open data policy — no copyright restriction; attribution to NASA/USGS/LP DAAC and Teluguntla et al. (2018, 2024) encouraged). Returns the dominant irrigation classification for the field and a percentage breakdown of irrigated vs. rainfed vs. non-cropland pixels.

The response carries a state field with one of five values:

• irrigatedDominant class is irrigated cropland (LGRIP30 class 2). Includes irrigated_pct, rainfed_pct, and non_cropland_pct breakdowns.
• rainfedDominant class is rainfed cropland (LGRIP30 class 3). Same breakdown fields.
• non_croplandNo irrigated or rainfed cropland detected — field classified as non-cropland.
• out_of_coverageField is outside CONUS / LGRIP30 coverage — irrigation data is not available here.
• unavailableCOG fetch or compute failed at query time. Try again; a result is only ever returned when the data was successfully sampled — never on a failed call.

Do not use this signal on its own. That is not a hedge, it is a measured result from our own work: LGRIP30's single-epoch irrigated class, applied alone, overcounts USDA county irrigated acreage by a median of +102%, and by up to +1,123% in humid counties, where any false positive lands on a small true denominator. A single-epoch classifier cannot separate land that is irrigated from land that merely looked irrigated in one wet window. Read irrigation as "an irrigation signal in the 2019–2021 Landsat record," never as "irrigated," and corroborate it with a multi-year persistence source before you count anything. The full method and the county-level check are in the irrigated-fields write-up.

Note: LGRIP30 is a single 2020 snapshot derived from Landsat-8. Irrigation status can change year to year. Informational only. Cite: Teluguntla et al. (2018) Remote Sensing 10(12):1920, DOI: 10.3390/rs10121920; dataset: Teluguntla et al. (2024) NASA LP DAAC LGRIP30 L3 V002.

land_cover Global · ESA WorldCover · 2021

Returns the areal share of each ESA WorldCover 2021 land-cover class within the AOI — the same 10m dataset as the per-field land_cover layer on enrich. Global coverage; runs inside and outside CONUS. License: CC-BY-4.0 — credit ESA WorldCover.

For very large AOIs the response carries a too_large state and no areal values — shrink the draw if you hit this.

irrigation CONUS only · LGRIP30 · 2020

Returns an areal breakdown of the AOI into three classes — Irrigated, Rainfed, and Non-cropland — each as a percentage, an acreage estimate, and a hectare estimate. Source: NASA LP DAAC LGRIP30 L3 V002 (Landsat-Derived Global Rainfed and Irrigated-Cropland Product), 30 m, nominal 2020 epoch. License: CC0 (NASA ESDIS open data policy; attribution to NASA/USGS/LP DAAC and Teluguntla et al. (2018, 2024) encouraged).

When the AOI centroid is outside CONUS, the response carries irrigation.state: "unavailable_off_conus" — no acreage fields are populated. LGRIP30 coverage is CONUS-only; this is not an error.

Note: LGRIP30 is a single 2020 snapshot. Irrigation status can change year to year. Values are informational only.

The same over-count caveat applies here as on enrich, and it bites harder on a whole area. Used alone, this class overcounts USDA county irrigated acreage by a median of +102%, and by up to +1,123% in humid counties. Do not present irrigation.irrigated_ac as an irrigated-acreage figure. See the enrich irrigation layer for the full caveat and the write-up behind it.

crop_type Global · ESA WorldCereal · 2021

Returns per-product areal share for four crop-type classes: Active cropland, Maize, Winter cereals, and Spring cereals — each as a percentage, an acreage estimate, and a hectare estimate. Source: ESA WorldCereal 2021 global map, 10 m, CC-BY-4.0. Attribution is required under CC-BY-4.0 — credit ESA WorldCereal and include a link to the license in any product that surfaces this data.

Important: these are independent binary predictions — each class is a separate yes/no model, not a mutually-exclusive classifier. The four percentages will not typically sum to 100% and are not expected to. Read each class on its own merits.

For very large AOIs, the response carries crop_type.state: "too_large" and no areal values — WorldCereal is a heavier read than the CDL histogram and has a lower practical size ceiling. Split or shrink the draw if you hit this.

forest_loss Coming soon

Accepted in include, but whole-area aggregation isn't built yet — the response returns an honest { state: "coming_soon" } rather than a fake value. Per-field forest-loss stats (Hansen Global Forest Change) are live today on enrich.

MRV field enrollment#

You have farmer-supplied polygons and need to qualify fields for a carbon program. POST the collection, pull crop_history and soil, and filter by crop rotation and SSURGO organic matter. The per-year CDL history and the SSURGO–SoilGrids soil comparison are both in the response without a second call.

Gap-filling during verification#

Your primary data source has gaps — a field with no farmer-reported crop history for a given year, or missing soil measurements. The CDL and SoilGrids values in the envelope are labeled with source, vintage, and confidence, so you can use them as fill-ins and document exactly what you filled with.

Batch enrollment at scale#

v1 is sync, 25 fields per call. For a large enrollment run, loop your collection in batches of 25 and parallelize up to your rate-limit ceiling. The request_id on each response is your audit handle if something goes wrong mid-batch.

Disclaimer (paste-ready):

Informational only — not legal advice and not a warranty. License and provenance fields are UFFDA's best-effort plain-language reading of upstream metadata. Verify license terms against the upstream source before relying on them for compliance, contract, or legal claims.

Attribution:

Each layer's license.attribution field carries the suggested attribution string for that upstream source, ready to drop into a credits block. For the endpoint itself:

Data enrichment via UFFDA API (uffda.ag). Underlying datasets: USDA NASS CDL (public domain), USDA SSURGO (public domain), ISRIC SoilGrids 2.0 (CC-BY-4.0), US Drought Monitor (custom terms — verbatim NDMC/USDA/NOAA/NASA credit required; see license.attribution), ESA WorldCover 2021, NASA POWER, Hansen Global Forest Change v1.12 (CC-BY-4.0, UMD / Google / USGS / NASA), NASA LP DAAC LGRIP30 L3 V002 (CC0, Teluguntla et al. 2018, 2024), ESA WorldCereal 2021 (CC-BY-4.0, attribution required).