Summary

By integrating key soil physical and biogeochemical properties — including texture, soil organic carbon, total nitrogen, bulk density, pH, and hydraulic characteristics — nitrogen transformation and loss pathways in cropland systems can be quantified. This use case describes a data collection approach applied in the United States to support the estimation of Nitrogen Use Efficiency (NUE), enabling the identification of areas where nitrogen uptake by crops may be constrained.

Identification of required soil parameters for NUE analysis

Soil Physical Properties

USDA Texture
Bulk Density
Root Zone Depth (proxy for effective soil depth/rooting constraint)
Coarse Fragments
Saturated Hydraulic Conductivity (Ksat)
Available Water Holding Capacity (AWHC)
Water Retention Volumetric

These parameters control soil water balance, oxygen diffusion, and water-filled pore space, which are critical regulators of nitrification, denitrification, and N leaching.

Soil Carbon and Nitrogen Pools

Organic Carbon Content or Soil Organic Carbon Density/Carbon Total
Nitrogen
C:N Ratio

These variables constrain soil organic matter turnover and nitrogen mineralization-immobilization dynamics.

Soil Chemical Context

pH
Cation Exchange Capacity (CEC)
Electrical Conductivity (EC)
Sodium Adsorption Ratio (SAR) and/or Sodium (if salinity/sodicity is relevant)
Calcium Carbonate (CaCO₃) (for calcareous systems and pH buffering effects)

These influence ammonium retention, nutrient availability, microbial activity, and crop N uptake efficiency.

Steps

Step 1: Build WKT payload for area of interest

For this use case, the area of interest is USA with focus on cropland. Since USA is a large area, you may need to define a specific geometry or use spatial filters to narrow down. For demonstration, we'll use a sample geometry covering parts of the United States cropland areas. In practice, you would use a more precise geometry for your specific region.

Example WKT for a sample area in the United States:

POLYGON ((-125.0 25.0, -125.0 50.0, -65.0 50.0, -65.0 25.0, -125.0 25.0))

Step 2: Get a token

All API requests must be made over HTTPS and must include an authentication token. A SoilHive client application is required to generate a token.

curl --request POST \
     --url https://auth.soilhive.ag/oauth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data audience=https://api.soilhive.ag/ \
     --data client_id={client_id} \
     --data client_secret={client_secret}

{
  "access_token": "{token}",
  "scope": "soilhive-api-services",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Step 3: Call the POST operation of the Spatial Filters endpoint to see what is available in your area of interest

curl --request POST \
     --url https://api.soilhive.ag/v1/spatial-filters/queries \
     --header 'accept: application/ld+json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "geometry": "POLYGON ((-125.0 25.0, -125.0 50.0, -65.0 50.0, -65.0 25.0, -125.0 25.0))"
}

{
  "@context": "https://api.soilhive.ag/v1/core.jsonld",
  "id": "https://api.soilhive.ag/v1/spatial-filters",
  "type": "ItemList",
  "description": "List of spatial filters",
  "items": {
    "id": "https://api.soilhive.ag/v1/spatial-filters",
    "type": "ItemList",
    "description": "List of spatial filters",
    "items": [
      {
        "type": "LandCoverFilter",
        "id": "https://api.soilhive.ag/v1/spatial-filters/134",
        "identifier": 134,
        "name": "Cultivated and managed vegetation agriculture (cropland)",
        "description": "Lands covered with temporary crops followed by harvest and a bare soil period (e.g., single and multiple cropping systems). Note that perennial woody crops will be classified as the appropriate forest or shrub land cover type."
      }
    ]
  }
}

Cultivated and managed vegetation agriculture (cropland) is available with ID=134.

Step 4: Call the POST operation of the Soil Properties endpoint to discover which soil properties are available in this area of interest

curl --request POST \
     --header 'accept: application/ld+json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "geometry": "POLYGON ((-125.0 25.0, -125.0 50.0, -65.0 50.0, -65.0 25.0, -125.0 25.0))",
  "spatialFilters": [134]
}'

{
  "@context": "https://api.soilhive.ag/v1/core.jsonld",
  "id": "https://api.soilhive.ag/v1/soil-properties",
  "type": "ItemList",
  "description": "List of soil properties",
  "items": {
    "id": "https://api.soilhive.ag/v1/soil-properties",
    "type": "ItemList",
    "description": "List of soil properties",
    "items": [
      {
        "type": "PhysicalProperty",
        "identifier": 13,
        "name": "Bulk Density",
        "unitText": "10xkg/m3, cg/cm3, kg/dm3, kg/m3",
        "unitCode": "10xkg/m3, cg/cm3, https://qudt.org/vocab/unit/KiloGM-PER-DeciM3, kg/m3"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 9,
        "name": "Cation Exchange Capacity",
        "unitText": "mmolc/kg, cmolc/kg, cmol(+)/kg",
        "unitCode": "mmolc/kg, cmolc/kg, cmol(+)/kg"
      },
      {
        "type": "PhysicalProperty",
        "identifier": 10,
        "name": "Clay",
        "unitText": "g/kg, g/100g, %",
        "unitCode": "https://qudt.org/vocab/unit/GM-PER-KiloGM, g/100g, https://qudt.org/vocab/unit/PERCENT"
      },
      {
        "type": "PhysicalProperty",
        "identifier": 14,
        "name": "Coarse Fragments",
        "unitText": "g/100g, %",
        "unitCode": "g/100g, https://qudt.org/vocab/unit/PERCENT"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 2,
        "name": "Electrical Conductivity",
        "unitText": "dS/m, mS/m",
        "unitCode": "https://qudt.org/vocab/unit/DeciS-PER-M, https://qudt.org/vocab/unit/MilliS-PER-M"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 7,
        "name": "Iron",
        "unitText": "mg/kg, ppm, 100ppm",
        "unitCode": "https://qudt.org/vocab/unit/MilliGM-PER-KiloGM, https://qudt.org/vocab/unit/PPM, 100ppm"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 31,
        "name": "Magnesium",
        "unitText": "mg/kg, ppm",
        "unitCode": "https://qudt.org/vocab/unit/MilliGM-PER-KiloGM, https://qudt.org/vocab/unit/PPM"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 3,
        "name": "Nitrogen",
        "unitText": "cg/kg, g/kg, %, %w",
        "unitCode": "cg/kg, https://qudt.org/vocab/unit/GM-PER-KiloGM, https://qudt.org/vocab/unit/PERCENT, https://qudt.org/vocab/unit/PERCENT"
      },
      {
        "type": "BiologicalProperty",
        "identifier": 15,
        "name": "Organic Carbon Content",
        "unitText": "dg/kg, g/kg, %",
        "unitCode": "dg/kg, https://qudt.org/vocab/unit/GM-PER-KiloGM, https://qudt.org/vocab/unit/PERCENT"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 1,
        "name": "pH",
        "unitText": "pHx10",
        "unitCode": "pHx10"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 4,
        "name": "Phosphorus",
        "unitText": "ppm, mg/kg, g/kg",
        "unitCode": "https://qudt.org/vocab/unit/PPM, https://qudt.org/vocab/unit/MilliGM-PER-KiloGM, https://qudt.org/vocab/unit/GM-PER-KiloGM"
      },
      {
        "type": "PhysicalProperty",
        "identifier": 12,
        "name": "Sand",
        "unitText": "g/kg, g/100g, %",
        "unitCode": "https://qudt.org/vocab/unit/GM-PER-KiloGM, g/100g, https://qudt.org/vocab/unit/PERCENT"
      },
      {
        "type": "ChemicalProperty",
        "identifier": 28,
        "name": "Sodium",
        "unitText": "mg/kg, ppm",
        "unitCode": "https://qudt.org/vocab/unit/MilliGM-PER-KiloGM, https://qudt.org/vocab/unit/PPM"
      },
      {
        "type": "DerivedProperty",
        "identifier": 35,
        "name": "USDA Texture"
      },
      {
        "type": "PhysicalProperty",
        "identifier": 34,
        "name": "Water Content",
        "unitText": "cm3/100cm3",
        "unitCode": "cm3/100cm3"
      }
    ]
  }
}

Relevant properties for nitrogen use efficiency are available: Bulk Density (13), Calcium Carbonate (8), Cation Exchange Capacity (9), Coarse Fragments (14), Electrical Conductivity (2), Magnesium (31), Nitrogen (3), Organic Carbon Content (15), pH (1), Phosphorus (4), Sand (12), Sodium (28), USDA Texture (35), Water Content (34).

Step 5: Call the POST operation of the Data Sources endpoint to discover which data sources are available for the spatial filters, soil properties and area of interest

curl --request POST \
     --url https://api.soilhive.ag/v1/datasets/queries \
     --header 'accept: application/ld+json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "geometry": "POLYGON ((-125.0 25.0, -125.0 50.0, -65.0 50.0, -65.0 25.0, -125.0 25.0))",
  "spatialFilters": [134],
  "soilProperties": [13,9,10,14,2,31,3,15,1,4,12,28,35,34]
}'

{
  "@context": "https://api.soilhive.ag/v1/core.jsonld",
  "id": "https://api.soilhive.ag/v1/datasets",
  "type": "DataCatalog",
  "description": "List of the available datasets in this data catalog",
  "temporalCoverage": "1905/2019",
  "DataSet": [
    {
      "type": "DataSet",
      "id": "https://api.soilhive.ag/v1/datasets/19",
      "identifier": 19,
      "name": "SoilGrids — global gridded soil information",
      "description": "SoilGrids is designed as a globally consistent, data-driven system that predicts soil properties and classes using global covariates and globally fitted models.",
      "url": "https://soilgrids.org/",
      "measurementTechnique": {
        "type": "DefinedTerm",
        "name": "D2.8.III.3 INSPIRE Data Specification on Soil, soil profile category",
        "termCode": "DerivedSoilProfile",
        "url": "http://inspire.ec.europa.eu/featureconcept/DerivedSoilProfile"
      },
      "distribution": {
        "type": "DataDownload",
        "encodingFormat": "TIF",
        "lockedForDownload": false
      },
      "size": {
        "type": "QuantitativeValue",
        "value": "61",
        "unitCode": "files"
      }
    },
    {
      "type": "DataSet",
      "id": "https://api.soilhive.ag/v1/datasets/4",
      "identifier": 4,
      "name": "Harmonized World Soil Database",
      "description": "The Harmonized World Soil Database version 2.0 (HWSD v2.0) is a unique global soil inventory providing information on the morphological, chemical and physical properties of soils at approximately 1 km resolution.",
      "url": "https://gaez.fao.org/pages/hwsd",
      "measurementTechnique": {
        "type": "DefinedTerm",
        "name": "D2.8.III.3 INSPIRE Data Specification on Soil, soil profile category",
        "termCode": "DerivedSoilProfile",
        "url": "http://inspire.ec.europa.eu/featureconcept/DerivedSoilProfile"
      },
      "distribution": {
        "type": "DataDownload",
        "encodingFormat": "TIF",
        "lockedForDownload": true
      }
    }
  ]
}

Available datasets include SoilGrids (ID=19) and Harmonized World Soil Database (ID=4).

Step 6: Call the POST operation of Soil Data By Geometry Queries to request the download

Since the area of interest is larger than 10 hectares, use the "Soil Data by Geometry Queries" endpoint to request download. Specify the location, spatial and property filters, data sources, and time range.

curl --request POST \
     --url https://api.soilhive.ag/v1/soil-data-by-geometry/queries \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {token}' \
     --header 'content-type: application/json' \
     --data '
{
  "geometry": "POLYGON ((-125.0 25.0, -125.0 50.0, -65.0 50.0, -65.0 25.0, -125.0 25.0))",
  "spatialFilters": [134],
  "soilProperties": [13,9,10,14,2,31,3,15,1,4,12,28,35,34],
  "startYear": 2000,
  "endYear": 2020,
  "datasets": [19],
  "gisDataTypes": ["raster"]
}'

{
  "Location": "https://api.soilhive.ag/v1/soil-data-by-geometry/queries/abc123def-4567-8901-2345-6789abcdef01"
}

Step 7: Call the GET operation of the Soil Data By Geometry Queries to check the status of the download job

Check the status of the job using the returned location ID.

curl --request GET \
     --url https://api.soilhive.ag/v1/soil-data-by-geometry/queries/abc123def-4567-8901-2345-6789abcdef01 \
     --header 'accept: application/ld+json' \
     --header 'authorization: Bearer {token}'

{
  "@context": "https://api.soilhive.ag/v1/core.jsonld",
  "id": "https://api.soilhive.ag/v1/soil-data-by-geometry/queries/abc123def-4567-8901-2345-6789abcdef01",
  "type": "Action",
  "actionStatus": "Completed",
  "description": "Completed file, ready for download",
  "startTime": "2024-10-09T12:46:01.385Z",
  "endTime": "2024-10-09T12:46:33.442Z",
  "result": {
    "type": "DataDownload",
    "url": "https://varda-prd-euc1-gsp-data-source.s3.amazonaws.com/download/abc123def-4567-8901-2345-6789abcdef01_1728477961290.zip",
    "expires": "2024-10-16T12:46:33.442Z"
  }
}

Outcome

Download the data from the provided link to obtain soil property rasters for nitrogen use efficiency modeling. Use these datasets to integrate with environmental drivers, crop information, and land management practices for comprehensive NUE analysis.

Additional Layers Required

Environmental Drivers

Daily or monthly temperature and precipitation, with optional radiation, evapotranspiration, and humidity to regulate soil moisture status and temperature-sensitive nitrogen transformations.

Crop Information

Crop species/variety, growing season duration, effective rooting depth, and yield with grain/tissue N concentration to estimate plant N demand and uptake.

Land Management Practices

Fertilizer type, rate, timing, and placement, along with irrigation, tillage, residue management, and cover cropping to capture management-driven shifts in nitrogen availability and loss pathways.