UFFDA Developer API

crop_history

USDA NASS Cropland Data Layer (CDL). Annual crop classification at 30m resolution, 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 (e.g., "Corn", "Soybeans") plus a class-accuracy figure (~92% for US corn/soy from CDL metadata; lower for minor crops). Fields outside CONUS get a null value and a note in properties.errors.

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 as primary for CONUS fields (survey-grade, area-weighted over map units intersecting your polygon); SoilGrids 2.0 as companion (global model estimate, 16-point grid sample, native Q0.05/Q0.95 uncertainty band). Outside CONUS, SoilGrids is primary.

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, nitrogen, bulk density. SoilGrids returns per-depth slices (0–15, 15–30, 0–30 cm); SSURGO uses a single 0–30 cm key for all metrics. A depth_note field on CONUS soil blocks flags that per-depth slices are available only from the SoilGrids companion.

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. Check stats.soilgrids directly to know whether the companion is present — do not rely on the fromCache flag for this (it reflects the SSURGO portion only). 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 or ready, without inspecting the companion object itself.

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

// CONUS, hydrated — companion is fully populated:
{ "companion": { /* SoilGrids values */ }, "companion_state": null }

// Outside CONUS — SoilGrids is primary; companion concept doesn't apply:
{ /* no companion_state key */ }

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 the polygon centroid, summarized over your requested window (default: trailing 12 months). Summary metrics: 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.

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.

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).