Skip to content Skip to main navigation Skip to footer
Fieldprint Platform Help

Empowering the Agricultural Supply Chain

Fieldprint API – /v5/Calculator

Access to the Fieldprint Platform and API requires Field to Market membership and an active Data Management Licensing Agreement. Learn more about membership and our data partner program to get started. Access to the Fieldprint API requires an authorized API key issued by Field to Market.

The Calculator endpoint is the primary endpoint of the Fieldprint Platform API. It accepts a field boundary, soil characteristics, and one or more years of crop management data (crop intervals with activities), runs the full suite of Fieldprint sustainability models, and returns results for up to eight environmental metrics: Land Use, Soil Conservation, Soil Carbon, Energy Use, Greenhouse Gas Emissions, Irrigation Water Use, Water Quality, and Biodiversity. Because farming operations vary widely — by crop, region, management practices, and year — the request body is highly flexible. A typical integration submits a multi-year crop rotation history (commonly going back to 2008) with detailed management activities for each year, and receives metric results for the most recent crop year.

Access to the Fieldprint Platform and API requires Field to Market membership and an active Data Management Licensing Agreement. Learn more about membership and our data partner program to get started. Access to the Fieldprint API requires an authorized API key issued by Field to Market.

Contents

Endpoint Details

Endpoint POST https://api.fieldtomarket.org/v5/Calculator
Authentication API Key (provided by Field to Market)
Content-Type application/json
Response Format JSON
Typical Response Time 10–30 seconds (depends on number of crop intervals and model complexity)

Request Body

The request body is a JSON object with three top-level objects: options, field, and crop_intervals.

{
  "options": { ... },
  "field": { ... },
  "crop_intervals": [ ... ]
}

Options Object

The options object controls calculation behavior, report generation, and benchmark configuration. All fields are optional.

Field Type Required Description
validate_only boolean No Top-level flag. When true, the API runs input validation only — no metrics are computed, no models are run, and no report is generated. Returns {"result": "OK"} if the payload passes, or specific error details identifying the first validation failure encountered (e.g., field path, error type, and message). Useful for quickly checking payload structure and values before submitting a full calculation. Note: This is a root-level parameter, not nested under options.
options.report.generate boolean No Set to true to generate a detailed PDF/HTML report alongside the JSON response.
options.report.generated_for string No Email or identifier of the person the report is generated for. Appears in report metadata.
options.report.grower string No Grower or farm name for report labeling.
options.skip_models boolean No If true, skips running the environmental models (WEPP, WEPS, and SWAT+) but still computes all other metrics. Indicators that depend on these models — Soil Conservation and Soil Carbon — will return zero values, while Energy Use, GHG Emissions, Land Use, Irrigation Water Use, Water Quality, and Biodiversity will return real results. The response metadata will show "Skipped" for the bypassed model versions. Useful for testing payloads and debugging without the overhead of full model runs.
options.qdmp_request_id string No Your internal tracking ID for this calculation request. Returned in response metadata.
options.project_name string No Fieldprint Project name to associate with the calculation.
options.benchmark_crop_id integer No Crop ID to use for benchmark comparisons. Defaults to the crop in the most recent crop interval. See /v5/ReferenceData/Crops for valid IDs.
options.benchmark_is_irrigated boolean No Whether to use irrigated benchmarks. Defaults to the irrigation status of the most recent crop interval.
options.assessment_report integer No IPCC Assessment Report version for GHG calculations. Choices: 1 (AR4), 2 (AR5 with climate-carbon feedback), 3 (AR5 without feedback), 4 (AR6). Default: AR6.

Field Object

The field object defines the physical characteristics of the field being analyzed.

Field Type Required Description
field.geometry GeoJSON Polygon Yes Field boundary as a GeoJSON Polygon with coordinates in decimal degrees (longitude, latitude). Must be within the US soils database coverage area.
field.state string No US state abbreviation (e.g., "IL"). Derived from geometry if not provided.
field.location string No Human-readable location (e.g., "Marion County, IL").
field.field_name string No Name of the field. Appears in report metadata.
field.plantable_acres object No Plantable area: { "value": 35.48, "unit": "acre" }. Derived from geometry if not provided.

field.soil_inputs

Soil characteristics for the field. If not provided, the API derives these from the field geometry using the USDA SSURGO soils database.

Field Type Description
soil_inputs.slope object Field slope: { "value": 1, "unit": "%" }
soil_inputs.slope_length object Slope length: { "value": 200, "unit": "foot" }
soil_inputs.texture_id string Soil texture ID. 21 options: 1 Clay, 2 Clay loam, 3 Loam, 4 Loamy sand, 5 Sand, 6 Sandy clay, 7 Sandy clay loam, 8 Sandy loam, 9 Silt, 10 Silt loam, 11 Silty clay, 12 Silty clay loam, 13–21 (additional fine/coarse variants).
soil_inputs.clay object Clay content: { "value": 14.9, "unit": "%" }

field.field_detail_inputs

Additional field-level details that influence specific metric calculations.

Field Type Description
landuse_change.has_landuse_change boolean Whether the field has undergone land use change (e.g., converted from grassland). Affects the Soil Carbon metric.
soils.has_wind_barriers boolean Whether wind barriers (shelterbelts, etc.) are present. Affects the Soil Conservation metric.
tile_drainage.tile_density_id string Tile drainage density. Affects Water Quality metric calculations.
additional_data.rice_water_regime object Rice-specific water management. water_management_id: 1 Continuously Flooded, 2 Single Aeration, 3 Multiple Aeration. water_regime_id: 1 Nonflooded preseason, 2 Flooded preseason > 30 days.
additional_data.nutrient_management object Contains n_carry_over (lb/acre), p_multi_crop_application_id (0–4 years), and nutrient_rate_practice_ids.

Crop Intervals Array

The crop_intervals array contains one object per crop year. Each object describes the crop grown, the harvest year, and the management activities performed. The Calculator typically requires a multi-year crop history — commonly from 2008 to the present — to produce accurate Soil Carbon and Soil Conservation results.

Field Type Required Description
harvest_year string Yes The harvest year for this crop interval (e.g., "2025").
crop_id string Yes Crop identifier from /v5/ReferenceData/Crops. Common values: 10401 (Corn, grain), 11101 (Soybeans).
activities array Yes Array of management activity objects, each with a type, date, and inputs. See Activity Types Reference below.
additional_data object No Interval-level additional data including habitat, soil test, nutrient management, and pest management details. See Additional Data.

Activity Types Reference

Each activity in the activities array has a type string, a date (YYYY-MM-DD), and an inputs object with type-specific fields. The API supports 10 activity types:

Activity Type Description Key Input Fields
planting_cash Cash crop planting planting_operation_id, seeding_rate (lb/acre), seed_treatment (bool), inoculant_applied (bool), diesel_use (gal_diesel/acre)
planting_cover Cover crop planting cover_crop_id, planting_operation_id, termination_date, termination_operation_id, growth_id, is_legume (bool), days_established_id, is_single_species_mix (bool)
harvest Harvest operations harvest_operation_id, yield (bushel/acre or lb/acre), crop_dried (bool), drying_system_id, moisture_removed (%), transport_distance (miles), transport_fuel_id, drying_location_id
tillage Soil tillage/disturbance tillage_operation_id, diesel_use (gal_diesel/acre)
nutrient_commercial Commercial fertilizer application fertilizer_operation_id, fertilizers[] array with: nitrogen, phosphorus, potassium, sulfur (each in lb/acre), product_type_id, inhibitor (bool), slow_release (bool)
nutrient_manure Manure application Manure type, application rate, application method, and nutrient content fields.
nutrient_other Other nutrient applications Nutrient product type and application rate fields.
irrigation Irrigation operations water_sources[] array with: water_source_id, irrigation_volume (acre_inch/acre), application_method_id, has_irrigation_energy (bool)
crop_protectant_spraying Pesticide/herbicide application Product type, application rate, and timing fields.
residue_management Crop residue management Residue type, management method, and timing fields.
Note: Operation and product IDs (e.g., tillage_operation_id, cover_crop_id, product_type_id) are sourced from the Reference Data endpoints. See API Reference Index for the full list of reference data endpoints.

Crop Interval Additional Data

Each crop interval can include an additional_data object with interval-level details that affect specific metric calculations:

Section Key Fields Description
habitat wildlife_habitat_ids Array of wildlife habitat practice IDs. Affects the Biodiversity metric.
soil_test p_soil_test_level_id, p_drawdown_strategy_ids Phosphorus soil test results and drawdown strategies. Affects the Water Quality metric.
nutrient_management management_plan, nutrient_setbacks, precision_application, p_multi_crop_application_id Nutrient management practices. Affects Water Quality and GHG metrics.
pest_management integrated_pest_management_id IPM practice level. Affects the Biodiversity metric.
rice_water_regime water_regime_id Water regime for rice crops. Affects the GHG metric.

Response Body

The response is a JSON object containing metadata and a cropyears array. Results are returned for the most recent crop year (or all years if multiple are configured for output).

Metadata

Field Type Description
metadata.runTimeSec integer Total calculation time in seconds.
metadata.boundaryAcres object Computed field size from the geometry.
metadata.state string US state abbreviation derived from geometry.
metadata.version.api string API version (e.g., "5.0.2").
metadata.version.csip object Versions of underlying CSIP model components: soils, wepp, weps, swatPlus, and climate station data.
metadata.soilInfo object Resolved soil information: mapUnit, name, coKey, slope, slopeLength, texture, textureId, clay, hsGroup, kFactor, omContent.
metadata.noTillYears float Number of consecutive no-till years detected in the crop history.
metadata.unknownInputs array Input fields that were provided but not recognized by the API. Useful for debugging.
metadata.ignoredInputs array Input fields that were recognized but ignored for this calculation (e.g., diesel_use values that are overridden by operation-based defaults).
metadata.qdmp_request_id string Echo of your tracking ID from the request.

Metric Results (cropyears)

Each object in the cropyears array represents one crop year’s results. The top-level fields identify the crop and management context:

Field Type Description
crop string Crop name (e.g., "Corn (grain)").
year integer Harvest year.
isIrrigated boolean Whether irrigation was applied this crop year.
stir float Soil Tillage Intensity Rating (STIR) value computed from tillage operations.
tillageClass string Tillage classification (e.g., "Conventional Till <15% Residue").

Following these identification fields are up to 8 metric result objects:

Metric Details

Each metric follows a common structure: a fieldprintResult (the raw metric value with units), a scaledFieldprintResult (normalized 0–100 scale), and benchmarks comparing the field to state and national averages. Some metrics include additional breakdowns.

1. Land Use

FieldUnitDescription
fieldprintResultacre / bushelLand use efficiency — acres required per unit of production. Lower is better.
yieldAdjustedbushel / acreAdjusted yield used in the calculation.
totalProductionbushelTotal production for the field.
scaledFieldprintResult0–100Scaled score relative to benchmarks.
benchmarks—State and national benchmark comparisons.

2. Soil Conservation

FieldUnitDescription
fieldprintResultton / acre / yearTotal soil erosion (water + wind). Lower is better.
fieldprintWaterton / acre / yearWater erosion component (WEPP model).
fieldprintWindton / acre / yearWind erosion component (WEPS model).
soilCarbonIndexfloatSoil Carbon Index value from the conservation model.
scaledFieldprintResult0–100Scaled score relative to benchmarks.

3. Soil Carbon

FieldUnitDescription
fieldprintResultlbs_co2e / acre / yearSoil carbon flux. Negative values indicate net sequestration (carbon gain).
fieldprintResultMetrickg_co2e / hectare / yearMetric units equivalent.
fluxHistoryarrayYear-by-year soil carbon flux history (lbs CO2e / acre / year) for the full crop history.
intervalFluxDaysarrayNumber of flux days and total days in year for each interval contributing to the result.
benchmarks—National benchmark (carbon neutrality = 0 as the 50th percentile).

4. Energy Use

FieldUnitDescription
fieldprintResultbtu / bushelTotal energy consumption per unit of production. Lower is better.
fieldprintResultMetricMJ / kgMetric units equivalent.
upstreamobjectUpstream energy: electricityProd (irrigation, crop drying), fuelProd (field ops, transport), inputsTransport, fertilizers, protectants, seed.
onFarmMechanicalobjectOn-farm mechanical energy from field operations and irrigation pumping.
scaledFieldprintResult0–100Scaled score relative to benchmarks.

5. Greenhouse Gas Emissions

FieldUnitDescription
fieldprintResultlbs_co2e / bushelTotal GHG emissions per unit of production. Lower is better.
totalGreenhouselbs_co2eTotal GHG emissions for the field.
contextobjectCalculation context: assessmentReport (e.g., AR6), timeHorizon (e.g., 100 years), egridRegion, dryingTransportLocation.
upstreamobjectUpstream emissions from fertilizer production, seed, protectants, fuel production, and electricity generation.
onFarmMechanicalobjectEmissions from on-farm mechanical operations.
onFarmSourcesSinksobjectSoil-based emissions and sinks: N₂O from soil, CO₂ from lime/urea, rice CH₄, residue burning, soil carbon change.
postHarvestobjectPost-harvest emissions from drying and transport.
scaledFieldprintResult0–100Scaled score relative to benchmarks.

6. Irrigation Water Use

FieldUnitDescription
fieldprintResultac_in / bushelIrrigation water per unit of production. Lower is better. Returns null if the crop year is not irrigated.
totalWateracre_inch / acreTotal irrigation water applied.
yieldDifferencebushel / acreEstimated yield difference attributable to irrigation.
scaledFieldprintResult0–100Scaled score relative to benchmarks.
Note: The Irrigation Water Use metric returns null for non-irrigated crop years.

7. Water Quality

FieldUnitDescription
fieldprintResult.valueintegerWater Quality index value (STEP model).
fieldprintResult.indexstringIndex identifier (e.g., "STEP").
lossPathwayobjectDetailed nutrient loss pathway analysis with four components: surfaceN, subsurfaceN, surfaceP, subsurfaceP. Each includes wqsrCategory, fieldSensitivityScore, riskMitigationScore, and individual credit breakdowns.
scaledFieldprintResult0–100Scaled score relative to benchmarks.

8. Biodiversity

FieldUnitDescription
fieldprintResult.valuefloatHabitat Potential Index (HPI) score.
fieldprintResult.indexstringIndex identifier ("HPI").
hpiCategorystringCategory classification (e.g., "Moderate").
cultivatedLandScorefloatLandscape-level cultivated land score.
fieldScorefloatField-level biodiversity score.
scaledFieldprintResult0–100Scaled score relative to benchmarks.

Example Request

The following example submits a corn/soybean rotation in Marion County, Illinois (35.48 acres). Two representative crop intervals are shown — the most recent corn year (2025) and the preceding soybean year (2024). A typical production request would include the full rotation history back to 2008.

POST https://api.fieldtomarket.org/v5/Calculator
Content-Type: application/json
Authorization: Bearer {your_api_key}

{
  "options": {
    "report": {
      "generated_for": "demo06@fieldtomarket.org",
      "grower": "Demo 06 Farm"
    }
  },
  "field": {
    "location": "Marion County, IL",
    "state": "IL",
    "field_name": "Demo 06 Field A5",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[ [-89.01864, 38.80656], [-89.01862, 38.80468], /* ... additional vertices ... */ [-89.01864, 38.80656] ]]
    },
    "plantable_acres": { "value": 35.48, "unit": "acre" },
    "soil_inputs": {
      "slope": { "value": 1, "unit": "%" },
      "slope_length": { "value": 200, "unit": "foot" },
      "texture_id": "10",
      "clay": { "value": 14.9, "unit": "%" }
    },
    "field_detail_inputs": {
      "landuse_change": { "has_landuse_change": false },
      "tile_drainage": { "tile_density_id": "1" }
    }
  },
  "crop_intervals": [
    // --- 2025 Corn (grain) ---
    {
      "harvest_year": "2025",
      "crop_id": "10401",
      "activities": [
        {
          "type": "planting_cover",
          "date": "2024-11-15",
          "inputs": {
            "cover_crop_id": "30770",
            "termination_date": "2025-05-01",
            "growth_id": "2",
            "is_legume": false,
            "planting_operation_id": "22952",
            "termination_operation_id": "23045",
            "days_established_id": "3"
          }
        },
        {
          "type": "tillage",
          "date": "2025-04-21",
          "inputs": { "tillage_operation_id": "22975" }
        },
        {
          "type": "tillage",
          "date": "2025-04-29",
          "inputs": { "tillage_operation_id": "22988" }
        },
        {
          "type": "planting_cash",
          "date": "2025-05-06",
          "inputs": {
            "seeding_rate": { "value": 30, "unit": "lb / acre" },
            "seed_treatment": true,
            "inoculant_applied": false,
            "planting_operation_id": "22917"
          }
        },
        {
          "type": "nutrient_commercial",
          "date": "2025-05-09",
          "inputs": {
            "fertilizer_operation_id": "22693",
            "fertilizers": [{
              "nitrogen": { "value": 140, "unit": "lb / acre" },
              "phosphorus": { "value": 133, "unit": "lb / acre" },
              "potassium": { "value": 84, "unit": "lb / acre" },
              "sulfur": { "value": 16, "unit": "lb / acre" },
              "product_type_id": 21,
              "inhibitor": false,
              "slow_release": false
            }]
          }
        },
        {
          "type": "harvest",
          "date": "2025-10-09",
          "inputs": {
            "harvest_operation_id": "22819",
            "yield": { "value": 146, "unit": "bushel / acre" },
            "crop_dried": true,
            "drying_system_id": "2",
            "moisture_removed": { "value": 2, "unit": "%" },
            "drying_location_id": "1",
            "transport_distance": { "value": 10, "unit": "miles" },
            "transport_fuel_id": "1"
          }
        }
      ],
      "additional_data": {
        "habitat": { "wildlife_habitat_ids": [] },
        "soil_test": {
          "p_soil_test_level_id": "1",
          "p_drawdown_strategy_ids": ["216"]
        },
        "nutrient_management": {
          "management_plan": false,
          "nutrient_setbacks": false,
          "precision_application": false,
          "p_multi_crop_application_id": "1"
        },
        "pest_management": { "integrated_pest_management_id": "6" }
      }
    },
    // --- 2024 Soybeans ---
    {
      "harvest_year": "2024",
      "crop_id": "11101",
      "activities": [
        {
          "type": "planting_cover",
          "date": "2023-11-15",
          "inputs": {
            "cover_crop_id": "30770",
            "termination_date": "2024-05-20",
            "planting_operation_id": "22952",
            "termination_operation_id": "23045"
          }
        },
        {
          "type": "nutrient_commercial",
          "date": "2024-05-09",
          "inputs": {
            "fertilizer_operation_id": "22693",
            "fertilizers": [{
              "nitrogen": { "value": 21, "unit": "lb / acre" },
              "phosphorus": { "value": 119, "unit": "lb / acre" },
              "potassium": { "value": 94, "unit": "lb / acre" },
              "sulfur": { "value": 15, "unit": "lb / acre" },
              "product_type_id": 21
            }]
          }
        },
        {
          "type": "tillage",
          "date": "2024-05-10",
          "inputs": { "tillage_operation_id": "22975" }
        },
        {
          "type": "tillage",
          "date": "2024-05-18",
          "inputs": { "tillage_operation_id": "22988" }
        },
        {
          "type": "planting_cash",
          "date": "2024-05-25",
          "inputs": {
            "seeding_rate": { "value": 167, "unit": "lb / acre" },
            "planting_operation_id": "22917"
          }
        },
        {
          "type": "irrigation",
          "date": "2024-10-13",
          "inputs": {
            "water_sources": [{
              "irrigation_volume": { "value": 8.8, "unit": "acre_inch / acre" },
              "application_method_id": "2"
            }]
          }
        },
        {
          "type": "harvest",
          "date": "2024-10-18",
          "inputs": {
            "harvest_operation_id": "22819",
            "yield": { "value": 44, "unit": "bushel / acre" }
          }
        }
      ],
      "additional_data": {
        "soil_test": { "p_soil_test_level_id": "5" }
      }
    }
    // ... additional crop intervals back to 2008 (corn/soybean rotation continues)
  ]
}
Note: This example shows 2 of the 18 crop intervals in a typical corn/soybean rotation. Production requests should include the complete rotation history (commonly 2008–present) for accurate Soil Carbon and Soil Conservation results. Use the /v5/FieldData/PrefillFieldHistory endpoint to generate a complete history from USDA Cropland Data Layer data, then overlay known management details.

Example Response

The response below shows results for the 2025 corn year. The metric values, benchmarks, and sub-component breakdowns are condensed for readability — the actual response includes deeply nested energy and GHG component breakdowns.

{
  "metadata": {
    "runTimeSec": 15,
    "boundaryAcres": { "value": 35.48, "unit": "acre" },
    "state": "IL",
    "version": {
      "api": "5.0.2",
      "csip": {
        "soils": "2.0",
        "wepp": "2.0",
        "weps": "5.0",
        "swatPlus": "61.0.2.60-odav@0.18.10(default)-2.8.60(default)"
      }
    },
    "soilInfo": {
      "mapUnit": "Hoyleton silt loam, 0 to 2 percent slopes",
      "texture": "Silt loam",
      "textureId": "10",
      "slope": { "value": 1.0, "unit": "%" },
      "clay": { "value": 14.9, "unit": "%" }
    },
    "noTillYears": 0,
    "generated_for": "demo06@fieldtomarket.org",
    "grower": "Demo 06 Farm",
    "field": "Demo 06 Field A5",
    "location": "Marion County, IL",
    "unknownInputs": [ /* fields provided but not recognized */ ],
    "ignoredInputs": [ /* fields recognized but not used in this calculation */ ]
  },
  "cropyears": [
    {
      "crop": "Corn (grain)",
      "year": 2025,
      "isIrrigated": false,
      "stir": 101.04,
      "tillageClass": "Conventional Till <15% Residue",

      "landUse": {
        "fieldprintResult": { "value": 0.00684932, "unit": "acre / bushel" },
        "yieldAdjusted": { "value": 146.0, "unit": "bushel / acre" },
        "totalProduction": { "value": 5180.08, "unit": "bushel" },
        "scaledFieldprintResult": 81.22,
        "benchmarks": {
          "scaleBasis": "State",
          "state": { "scaledFieldprintResult": 70.33 },
          "national": { "scaledFieldprintResult": 87.58 }
        }
      },

      "soilConservation": {
        "fieldprintResult": { "value": 2.57362833, "unit": "ton / acre / year" },
        "fieldprintWater": { "value": 2.50270009, "unit": "ton / acre / year" },
        "fieldprintWind": { "value": 0.07092824, "unit": "ton / acre / year" },
        "soilCarbonIndex": 0.074,
        "scaledFieldprintResult": 69.80,
        "benchmarks": {
          "state": { "scaledFieldprintResult": 62.0 },
          "national": { "scaledFieldprintResult": 86.12 }
        }
      },

      "soilCarbon": {
        "fieldprintResult": { "value": -2372.38, "unit": "lbs_co2e / acre / year" },
        "fieldprintResultMetric": { "value": -2659.09, "unit": "kg_co2e / hectare / year" },
        "scaledFieldprintResult": 0,
        "fluxHistory": [
          { "year": 2008, "flux": { "value": 3442.64, "unit": "lbs_co2e / acre / year" } },
          /* ... one entry per year from 2008 through 2025 ... */
          { "year": 2025, "flux": { "value": -3196.74, "unit": "lbs_co2e / acre / year" } }
        ],
        "benchmarks": {
          "scaleBasis": "Neutral",
          "national": { "fieldprintResult": { "value": 0.0 }, "scaledFieldprintResult": 50.0 }
        }
      },

      "energyUse": {
        "fieldprintResult": { "value": 69330.44, "unit": "btu / bushel" },
        "fieldprintResultMetric": { "value": 2.88, "unit": "MJ / kg" },
        "scaledFieldprintResult": 89.74,
        "upstream": { /* electricityProd, fuelProd, inputsTransport, fertilizers, protectants, seed */ },
        "onFarmMechanical": { /* mobile operations: fieldOps, irrigationOps */ },
        "benchmarks": { /* state and national comparisons */ }
      },

      "greenhouseGas": {
        "fieldprintResult": { "value": 1.20068466, "unit": "lbs_co2e / bushel" },
        "totalGreenhouse": { "value": 6219.64, "unit": "lbs_co2e" },
        "context": {
          "assessmentReport": "AR6",
          "timeHorizon": "100 years",
          "egridRegion": "SRMW",
          "dryingTransportLocation": "On-Farm"
        },
        "scaledFieldprintResult": 0.66,
        "upstream": { /* fertilizer, seed, protectant, fuel, electricity emissions */ },
        "onFarmMechanical": { /* field operations, irrigation emissions */ },
        "onFarmSourcesSinks": { /* N2O soil, CO2 lime/urea, CH4 rice, residue burning, soil carbon */ },
        "postHarvest": { /* drying and transport emissions */ },
        "benchmarks": {
          "state": { "fieldprintResult": { "value": 12.16 }, "scaledFieldprintResult": 72.0 },
          "national": { "fieldprintResult": { "value": 11.41 }, "scaledFieldprintResult": 66.09 }
        }
      },

      "irrigationWaterUse": null,
      // null because the 2025 corn year is not irrigated

      "waterQuality": {
        "fieldprintResult": { "value": 0, "index": "STEP" },
        "scaledFieldprintResult": 100.0,
        "lossPathway": {
          "surfaceN": { "wqsrCategory": "MODERATELY HIGH", "fieldSensitivityScore": 65, "riskMitigationScore": 8.25 },
          "subsurfaceN": { "wqsrCategory": "MODERATELY HIGH", "fieldSensitivityScore": 50, "riskMitigationScore": 15.0 },
          "surfaceP": { "wqsrCategory": "MODERATELY HIGH", "fieldSensitivityScore": 60 },
          "subsurfaceP": { "wqsrCategory": "MODERATELY LOW", "fieldSensitivityScore": 25 }
        },
        "benchmarks": { /* state and national comparisons */ }
      },

      "biodiversity": {
        "fieldprintResult": { "value": 0.66878307, "index": "HPI" },
        "scaledFieldprintResult": 33.12,
        "hpiCategory": "Moderate",
        "cultivatedLandScore": 354.8,
        "fieldScore": 237.28
      }
    }
  ]
}

Validation & Error Handling

HTTP Status Codes

StatusMeaning
200Calculation completed successfully. Check response for metric results.
400Validation error. The response body contains an array of field-level error details.
403Authentication failed. Verify your API key.
500Server error. The API may return model-specific error details (see below).

Validation Error Codes

A 400 response returns an array of error objects. Each error identifies the field path and the type of validation failure:

Error CodeDescriptionExample
REQUIRED A required field is missing. crop_intervals.0.crop_id — Crop ID is required for every interval.
CHOICE Value is not one of the allowed options. options.assessment_report — Must be 1, 2, 3, or 4.
TYPE Value has the wrong data type. field.plantable_acres.value — Expected a number.
UNITS Unit value is not recognized. crop_intervals.0.activities.0.inputs.yield.unit — Must be a valid yield unit.
GEOMETRY Field geometry is invalid. Geometry must be a valid GeoJSON Polygon or MultiPolygon within the US soils database.
STRUCTURE Request structure is malformed. Expected an array for crop_intervals but received an object.
RANGE Numeric value is outside the acceptable range. crop_intervals.0.activities.0.inputs.yield.value — Yield value exceeds the plausible maximum for this crop.
CONFIG Conflicting or invalid configuration of related inputs. Irrigation activity provided but is_irrigated is set to false on the crop interval.
DEPRECATED Input or value has been deprecated in the current API version. A field or choice ID that was valid in a prior version but is no longer accepted.
AREA Field geometry area does not meet requirements. Geometry area exceeds the maximum allowed field size or is too small to calculate.

500 Server Errors

If an environmental model fails during calculation, the API may return a 500 error with details about which model component failed. Common causes include:

  • Field geometry in a region not covered by the WEPP or WEPS climate station network
  • CSIP model timeout (complex soil or crop history configurations)
  • Invalid soil parameter combinations that pass input validation but fail during model execution
Important: If you receive a 500 error, check your field geometry and soil inputs first. Use "validate_only": true to confirm inputs pass validation, then retry with "options": {"skip_models": true} to isolate whether the error originates from the environmental models.

Usage Notes

Multi-Year History Required: The Calculator models (especially Soil Carbon and Soil Conservation) depend on multi-year crop management history. Submitting only 1–2 years of data will produce results, but they will be less accurate. For the best results, include crop intervals from 2008 to the present. Use the /v5/FieldData/PrefillFieldHistory endpoint to generate a baseline history, then overlay known management details.
Crop Rotation Patterns: The example above shows a corn/soybean rotation — the most common Midwest pattern. The API supports 222+ crop types including wheat, rice, cotton, alfalfa, and specialty crops. Each crop type may require different activity types and input fields. Reference the crop-specific ReferenceData endpoints for valid operation IDs.
Irrigation Water Use: The irrigationWaterUse metric returns null for non-irrigated crop years. Include an irrigation activity with water_sources data to receive this metric. The 2024 soybean year in the example above includes irrigation data.
Benchmark Comparisons: All metrics include state-level and national-level benchmark comparisons. The scaledFieldprintResult value (0–100) positions the field’s performance relative to the benchmark distribution. A score of 50 represents the benchmark median. Higher scores generally indicate better environmental performance, except for metrics like Soil Carbon where negative values (carbon sequestration) are favorable.
Unknown & Ignored Inputs: The response metadata includes unknownInputs and ignoredInputs arrays. Use these to identify fields in your request that the API did not recognize or did not use for this particular calculation. This is helpful for debugging data pipeline issues and ensuring your submitted data is being consumed as expected.
GHG Assessment Report: The default GHG calculation uses IPCC AR6 global warming potentials. You can select an earlier assessment report version (AR4 or AR5) via the options.assessment_report field if your reporting requirements specify a particular IPCC version.
Payload Testing Workflow: When developing your integration, consider a two-step testing approach. First, submit your payload with "validate_only": true (root level) to quickly confirm all inputs pass validation — the API returns {"result": "OK"} on success, or details about the first validation failure encountered. Iterate until validation passes. Then use "options": {"skip_models": true} to get a full response with most metrics computed but without the overhead of WEPP, WEPS, and SWAT+ model runs. This lets you verify your response-parsing logic before running a complete calculation.
Endpoint Description
POST /v5/FieldData/PrefillFieldHistory Generate a complete multi-year crop history (2008–present) from USDA CDL data. Use this to build the baseline crop_intervals array for the Calculator.
POST /v5/FieldData/PrefillCropIntervals Generate complete management activities for specific crop years. Use when you have partial data for individual years.
POST /v5/ScaledBenchmarks Retrieve benchmark distributions without running a full calculation. Useful for building comparison UI.
POST /v5/SaiCalculator Calculate SAI Platform FSA Equivalency from a 22-question survey.
GET /v5/ReferenceData/Crops List all valid crop IDs and names for the crop_id field.
GET /v5/EndPoints Full list of all 52 API endpoints including all Reference Data endpoints for operation IDs.

Reach out to support@fieldtomarket.org with additional questions on implementation.

Was This Article Helpful?

0
Related Articles