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

Empowering the Agricultural Supply Chain

Fieldprint API – /v5/FieldData/PrefillFieldHistory

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. Accesss to the Fieldprint API requires an authorized API Key provided by Field to Market.

Overview

The PrefillFieldHistory endpoint generates baseline crop interval data for a field based on its geographic location. It uses the USDA Crop Data Layer (CDL) to determine the crop rotation history from 2008 to the most recent year available, and combines this with a set of crop-specific default values for field activities (planting, harvest, tillage, nutrient applications, etc.) within each interval.

The baseline data provides the minimum data inputs required to calculate annual soil carbon stock changes. Complete data is required for intervals where a Fieldprint Analysis is being requested.

Endpoint Details

Endpoint POST https://api.fieldtomarket.org/v5/FieldData/PrefillFieldHistory
Authentication API Key (provided by Field to Market)
Content-Type application/json
Response Format JSON

Typical Workflow

A common use case for this endpoint is backfilling historical crop intervals when a QDMP wants to generate a Fieldprint Analysis but does not have the full crop rotation history back to 2008. Here is the typical sequence:

  1. A QDMP wants to generate a Fieldprint Analysis for a 2025 Corn (grain) interval.
  2. The QDMP does not have crop rotation history back to 2008 and lacks the baseline data required for the soil carbon indicator.
  3. The QDMP builds the 2025 Corn (grain) interval request with data sufficient to generate a Fieldprint Analysis, then backfills 2008–2024 using data from this endpoint.
  4. The complete request (QDMP’s 2025 interval + prefilled history) is submitted to /v5/Calculator to generate the Fieldprint Analysis.
Important — Data Accuracy: The field history returned may not be accurate and should be reviewed and confirmed by QDMPs. USDA CDL does not always return an accurate crop history. Default data supplied by Field to Market may not represent actual field conditions, and dates for operations may cause validation issues. For example, a harvest date for 2024 may conflict with the date of the first activity in the QDMP’s 2025 interval.

Request Body

The request body is a JSON object containing the field geometry and optional parameters that control which default activities are included in the generated intervals.

Input Fields

Field Type Required Description
field.geometry GeoJSON Polygon Yes The field boundary as a GeoJSON Polygon with coordinates in decimal degrees (longitude, latitude). Must follow the standard GeoJSON format with coordinates as [longitude, latitude] pairs.
options.is_irrigated boolean No When true, adds irrigation operations to all generated crop intervals.
options.cover_crop boolean No When true, adds cover crop planting and termination operations to all generated crop intervals.
options.tillage_class_id string No Applies the specified tillage intensity to all intervals. If omitted, the system computes a default. Valid values are listed below.

Tillage Class Options

ID Description
"1" No-Till (85% Residue)
"2" Strip-Till (70% Residue)
"4" Reduced Till (30% Residue)
"6" Conventional Till (<10% Residue)

Input Validation Errors

Error Code Field Description
GEOMETRY field.geometry Invalid geometry, e.g., empty FeatureCollection.
STRUCTURE field.geometry Malformed GeoJSON (e.g., missing delimiters, invalid coordinates).
CHOICE options.tillage_class_id The provided value is not a valid tillage class ID. See valid options above.

Example Request

{
  "options": {
    "is_irrigated": true,
    "cover_crop": true,
    "tillage_class_id": "6"
  },
  "field": {
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-95.53909487338437, 42.92811105124366],
          [-95.53909487338437, 42.92643775409019],
          [-95.53795761676207, 42.92643775409019],
          [-95.53795761676207, 42.92811105124366],
          [-95.53909487338437, 42.92811105124366]
        ]
      ]
    }
  }
}

Response Body

The response contains the resolved field information, an array of crop intervals (one per year from 2008 to the most recent CDL year), and metadata about default values used.

Top-Level Response Fields

Field Type Description
field object Resolved field information including geometry, computed size, state, and county.
crop_intervals array Array of crop interval objects, one per harvest year, ordered from most recent to oldest (2024 down to 2008).
metadata object Contains warnings about fallback computations and defaultedInputs showing the default values used. See Metadata section below.
debugHistory array The raw USDA CDL crop history data for the field, showing detected crop types and acreage by year. Useful for verifying the CDL data accuracy.

Field Object

Field Type Description
field.geometry GeoJSON Polygon The field boundary, echoed back with coordinates rounded to 8 decimal places.
field.size.value float Computed field area.
field.size.unit string Unit of area measurement (e.g., "acre").
field.state string Two-letter US state abbreviation resolved from the field geometry.
field.county string County name resolved from the field geometry.

Crop Interval Object

Each element in the crop_intervals array represents one harvest year and contains the crop identification, tillage classification, field activities, and any additional data required by the Calculator.

Field Type Description
harvest_year integer The harvest year for this interval (e.g., 2024).
crop_id string Crop identifier from /v5/ReferenceData/Crops. E.g., "10401" = Corn (grain), "11101" = Soybeans.
tillage_class_id string The tillage classification applied to this interval. Uses the requested value or a computed fallback.
activities array Array of activity objects representing field operations for this interval. See Activity Types below.
additional_data object Supplementary data such as soil_test and rice_water_regime defaults.

Activity Types

Each activity in the activities array has a type, date, and inputs object. The structure of inputs varies by activity type. Below are the activity types returned by this endpoint:

Activity Type Description Key Input Fields
planting_cash Cash crop planting operation planting_operation_id, seeding_rate (value + unit), diesel_use, seed_treatment, inoculant_applied
planting_cover Cover crop planting (only if cover_crop: true) cover_crop_id, planting_operation_id, diesel_use, termination_date, termination_operation_id
irrigation Irrigation event (only if is_irrigated: true) water_sources array: water_source_id, irrigation_volume (value + unit), application_method_id
harvest Crop harvest operation harvest_operation_id, yield (value + unit), diesel_use, transport_fuel_id
tillage Tillage operation (may appear multiple times) tillage_operation_id, diesel_use
nutrient_commercial Commercial fertilizer application fertilizer_operation_id, diesel_use, fertilizers array (see below)

Fertilizer Detail (nutrient_commercial activities)

Each entry in the fertilizers array within a nutrient_commercial activity contains:

Field Type Description
product_type_id integer Fertilizer product type identifier from /v5/ReferenceData/Fertilizers.
nitrogen object Nitrogen application rate (value + unit, e.g., "lb / acre").
phosphorus object Phosphorus application rate.
potassium object Potassium application rate.
sulfur object Sulfur application rate.
slow_release boolean Whether the fertilizer is a slow-release formulation.
inhibitor boolean Whether a nitrification inhibitor is applied.

Metadata

The metadata object provides transparency about where the API used fallback computations or default values in the response.

Field Type Description
metadata.warnings object Key-value pairs where the key identifies the interval and field (e.g., "crop_intervals.0.tillage_class_id") and the value is the warning message. Typically: "Not specified, so used fallback computation."
metadata.defaultedInputs object Key-value pairs showing the actual default values used. E.g., "crop_intervals.0.yield": {"value": 44.0, "unit": "bushel / acre"}.
Note: The warnings and defaultedInputs fields use dot-notation keys like crop_intervals.0.yield, where the number is the zero-based index into the crop_intervals array. Common defaulted fields include tillage_class_id, total_n (total nitrogen), and yield.

Debug History (debugHistory)

The debugHistory array contains the raw USDA Crop Data Layer results for each year, showing which crops were detected and their acreage within the field boundary. This is useful for understanding why the API selected a particular crop for each interval, and for identifying potential CDL misclassifications.

Field Type Description
year string The calendar year.
crops array Array of detected crops for that year, each with crop (name), crop_ids (array of matching IDs), and acres (acreage detected).

Example Response (Truncated)

The full response contains one crop interval per year from 2008 to the most recent CDL year. Below shows the response structure with the first two intervals (2024 and 2023) and selected metadata. The remaining intervals (2022–2008) follow the same structure.

{
  "field": {
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-95.53909487, 42.92811105],
          [-95.53909487, 42.92643775],
          [-95.53795762, 42.92643775],
          [-95.53795762, 42.92811105],
          [-95.53909487, 42.92811105]
        ]
      ]
    },
    "size": { "value": 4.2667242, "unit": "acre" },
    "state": "IA",
    "county": "O'Brien County"
  },
  "crop_intervals": [
    {
      "harvest_year": 2024,
      "crop_id": "11101",
      "tillage_class_id": "4",
      "activities": [
        {
          "type": "planting_cash",
          "date": "2024-05-25",
          "inputs": {
            "planting_operation_id": "22917",
            "seeding_rate": { "value": 167.0, "unit": "lb / acre" },
            "diesel_use": { "value": 0.64, "unit": "gal_diesel / acre" },
            "seed_treatment": true,
            "inoculant_applied": false
          }
        },
        {
          "type": "planting_cover",
          "date": "2023-11-15",
          "inputs": {
            "cover_crop_id": "30770",
            "planting_operation_id": "22952",
            "diesel_use": { "value": 0.1283, "unit": "gal_diesel / acre" },
            "termination_date": "2024-05-20",
            "termination_operation_id": "23045"
          }
        },
        {
          "type": "irrigation",
          "date": "2024-10-13",
          "inputs": {
            "water_sources": [
              {
                "water_source_id": "1",
                "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.0, "unit": "bushel / acre" },
            "diesel_use": { "value": 1.53, "unit": "gal_diesel / acre" },
            "transport_fuel_id": "1"
          }
        },
        {
          "type": "tillage",
          "date": "2024-05-10",
          "inputs": {
            "tillage_operation_id": "22975",
            "diesel_use": { "value": 0.48, "unit": "gal_diesel / acre" }
          }
        },
        {
          "type": "tillage",
          "date": "2024-05-18",
          "inputs": {
            "tillage_operation_id": "22988",
            "diesel_use": { "value": 0.62, "unit": "gal_diesel / acre" }
          }
        },
        {
          "type": "nutrient_commercial",
          "date": "2024-05-09",
          "inputs": {
            "fertilizer_operation_id": "22693",
            "diesel_use": { "value": 0.16, "unit": "gal_diesel / acre" },
            "fertilizers": [
              {
                "product_type_id": 21,
                "nitrogen": { "value": 21.0, "unit": "lb / acre" },
                "phosphorus": { "value": 119.0, "unit": "lb / acre" },
                "potassium": { "value": 94.0, "unit": "lb / acre" },
                "sulfur": { "value": 15.0, "unit": "lb / acre" },
                "slow_release": false,
                "inhibitor": false
              }
            ]
          }
        }
      ],
      "additional_data": {
        "soil_test": { "p_soil_test_level_id": "5" },
        "rice_water_regime": { "water_regime_id": "1" }
      }
    },
    {
      "harvest_year": 2023,
      "crop_id": "10401",
      "tillage_class_id": "4",
      "activities": [
        // ... same structure as above, with crop-specific defaults ...
      ],
      "additional_data": { /* ... */ }
    }
    // ... intervals for 2022 down to 2008 follow the same structure ...
  ],
  "metadata": {
    "warnings": {
      "crop_intervals.0.tillage_class_id": "Not specified, so used fallback computation.",
      "crop_intervals.0.total_n": "Not specified, so used fallback computation.",
      "crop_intervals.0.yield": "Not specified, so used fallback computation."
      // ... similar entries for each crop interval ...
    },
    "defaultedInputs": {
      "crop_intervals.0.tillage_class_id": "4",
      "crop_intervals.0.total_n": { "value": 21.0, "unit": "lb / acre" },
      "crop_intervals.0.yield": { "value": 44.0, "unit": "bushel / acre" }
      // ... similar entries for each crop interval ...
    }
  },
  "debugHistory": [
    {
      "year": "2024",
      "crops": [
        {
          "crop": "Soybeans",
          "crop_ids": ["11101"],
          "acres": 4.0
        }
      ]
    },
    {
      "year": "2023",
      "crops": [
        {
          "crop": "Corn",
          "crop_ids": ["10401"],
          "acres": 5.8
        },
        {
          "crop": "Soybeans",
          "crop_ids": ["11101"],
          "acres": 0.4
        }
      ]
    }
    // ... entries for 2022 down to 2008 ...
  ]
}

Usage Notes

Typical Workflow: Use PrefillFieldHistory to generate historical crop intervals, then merge them with your QDMP’s current-year interval data before submitting the complete request to /v5/Calculator. The prefilled intervals provide the minimum baseline needed for the soil carbon stock change calculation.
Review Default Dates: Default operation dates are estimates based on typical timing for each crop. When combining prefilled history with QDMP-provided intervals, check that dates near the boundary between years do not overlap or conflict. A common issue is the prefilled harvest date in the most recent historical interval conflicting with the first activity date in the QDMP’s interval.
CDL Crop Selection: When the USDA CDL detects multiple crops in a field for a given year (as shown in debugHistory), the API selects the dominant crop (highest acreage) for that interval. Years where CDL shows split acreage may indicate field boundary misalignment or mixed land use.
Tillage Class Fallback: If tillage_class_id is not specified in the options, the system computes a default based on crop type and regional data. The metadata.warnings and metadata.defaultedInputs fields document where this fallback was applied.

Related Endpoints

Endpoint Description
/v5/Calculator Submit complete field data (including prefilled history) to generate a Fieldprint Analysis.
/v5/FieldData/PrefillCropIntervals Generate default activity data for specific crop intervals without the full historical lookup.
/v5/FieldData/SSURGO Retrieve SSURGO soil data for a field boundary.
/v5/ReferenceData/Crops List of valid crop IDs and names.
/v5/ReferenceData/TillageClasses List of valid tillage classification IDs.

Was This Article Helpful?

0
Related Articles