Cover Crop Nitrogen Calculator (CC-NCALC) API
Base URL:
https://api.covercrop-ncalc.org/
(also available at https://developapi.covercrop-ncalc.org/ for testing)
Endpoint
The endpoint returns nitrogen mineralization estimates based on weather, soil, and crop traits.
| Parameter |
Type |
Units |
Required |
Description |
Model |
| lat | number | degrees | ✅ | Latitude | both |
| lon | number | degrees | ✅ | Longitude | both |
| start | string | YYYY-MM-DD | ✅ | Start (planting) date | both |
| end | string | YYYY-MM-DD | ❌ | Termination date. Defaults to start + 90 days | both |
| n | number | % | ✅ | N concentration in cover crop | both |
| biomass | number | kg/ha | ✅ | Dry biomass at termination | both |
| lwc | number | g water/
g dry biomass | ❌ | Leaf water content (default: 4) | surface |
| carb | number | % | ❌ | Carbohydrate content (default: 24.7 + 10.5 * n) | both |
| cell | number | % | ❌ | Holocellulose (default: 69 - 10.2 * n) | both |
| lign | number | % | ❌ | Lignin (default: 100 - (carb + cell)) | both |
| om | number | % | ❌ | Organic matter (from SSURGO if omitted) | both |
| bd | number | g/cm³ | ❌ | Bulk density (from SSURGO if omitted) | both |
| in | number | ppm | ❌ | Inorganic N in soil (default: 10) | both |
| pmn | number | mg N/kg | ❌ | Potentially mineralizable N (default: 7) | both |
Output Format
Default: JSON
To get CSV, add &output=csv to your request.
Notes
- Any or all of the inputs may be arrays. This allows you to run multiple models together.
- If multiple inputs are arrays, they must have the same length.
- You can include custom parameters in your query (e.g.,
site=Field_A) — they will be echoed back in the output.
- For future dates, soil data is based on 5-year daily averages.
Streaming Support
Use the query string stream=true to enable streaming output for large batch queries (only available on POST requests).
This can help overcome Cloudflare's ~20s timeout due to lack of output activity. However, it will not bypass Cloudflare’s total timeout limit of 100 seconds.
To avoid timeouts, you can:
- Break your data into smaller batches
- Add client-side retry logic for timeouts
Example GET Request
Example POST Requests
Single Site
{
"start": "2023-10-01",
"end": "2024-04-15",
"lat": 35.9,
"lon": -83.95,
"summary": true,
"stream": true,
"n": [2.6],
"biomass": [3000],
"carb": [50],
"cell": [45],
"lign": [5],
"site": ["TN_101"]
}
Multiple Sites
{
"start": "2023-10-01",
"end": "2024-04-15",
"lat": 35.9,
"lon": -83.95,
"summary": true,
"stream": true,
"site": ["TN_101", "TN_102"],
"n": [2.6, 3.1],
"biomass": [3000, 1800],
"carb": [50, 60],
"cell": [45, 35.5],
"lign": [5, 4.5]
}
Surface Model Output Variables
Weather Inputs
| Property |
Description |
Units |
Formula |
| Rain | Hourly precipitation | mm | input |
| Temp | Air temperature | °C | input |
| RH | Relative humidity | % | input |
| Date | Timestamp for timestep | datetime | formatted |
Litter Water Balance
| Property |
Description |
Units |
Formula |
| RainToGetCurrentWC |
Rain needed to reach current litter water content |
mm |
Empirical exponential equation depending on crop type |
| WCFromRain |
Water content expected from rainfall |
g water / g litter |
Exponential function of (Rain + RainToGetCurrentWC) |
| FromRain |
Water gained from rainfall |
g/g |
max(0, min(WCFromRain - LitterWaterContent, 0.3)) |
| FromDew |
Water gained from dew |
g/g |
If dew is present and litter is dry |
| FromAir |
Water absorbed from humid air |
g/g |
k1 * Litter_MPa_Gradient |
| Evaporation |
Water lost from evaporation |
g/g |
max(0, WaterLossFromEvap) |
Water Potential Calculations
| Property |
Description |
Units |
Formula |
| Air_MPa |
Water potential of air |
MPa |
(8.314 * (Temp + 273.15) * ln(RH / 100)) / (18 * 10^-6) / 1000000 |
| %_lignin |
Lignin percentage in litter |
% |
min(13, (Lign / FOM) * 100) |
| a |
Empirical parameter |
— |
-0.5981 * %_lignin + 8.1823 |
| b |
Empirical parameter |
— |
-0.1181 * %_lignin - 0.3783 |
| LitterMPa |
Water potential of litter |
MPa |
max(-200, -a * LitterWaterContent^b) |
| Litter_MPa_Gradient |
Potential gradient from air to litter |
MPa |
Air_MPa - LitterMPa |
Moisture Transfer
| Property |
Description |
Formula |
| k1 |
Humidity transfer coefficient |
Depends on RH change and gradient |
| FromAir |
Moisture uptake from air |
k1 * gradient, capped in code |
Decomposition Rate Constants
| Property |
Description |
Formula |
| CarbK |
Carbohydrate decay constant |
0.018 * exp(-12 * (%_lignin / 100)) |
| CellK |
Cellulose decay constant |
k3 * exp(-12 * (%_lignin / 100)) |
| DeCarb |
Carbohydrate decomposition rate |
CarbK * RMTFAC * CNRF * ContactFactor |
| DeCell |
Cellulose decomposition rate |
CellK * RMTFAC * CNRF * ContactFactor |
| DeLign |
Lignin decomposition rate |
LignK * RMTFAC * CNRF * ContactFactor |
Environmental Rate Modifiers
| Property |
Description |
Formula |
| RMTFAC |
Temperature/moisture rate modifier |
(0.384 + 0.018 * Temp) * exp(LitterMPa * (0.142 + 0.628 * Temp^-1)) |
| ContactFactor |
Residue-soil contact effect |
Critical_FOM / FOM, capped at 1 |
Nitrogen Pools
| Property |
Description |
Formula |
| FON |
Fresh organic N |
CarbN + CellN + LigninN |
| CNR |
Carbon:nitrogen ratio |
(0.426 * FOM) / (FON + INkg) |
| CNRF |
C:N response factor |
min(1, exp((-0.693 * (CNR - 13)) / 13)) |
Nitrogen Release
| Property |
Description |
Formula |
| GrNom1 |
N release from carbohydrate |
CarbN * DeCarb |
| GRNom2 |
N release from cellulose |
CellN * DeCell |
| GRNom3 |
N release from lignin |
LigninN * DeLign |
| GRNom |
Total gross N release |
Sum of the three components |
Carbon Decomposition
| Property |
Description |
Formula |
| GRCom1 |
Carbohydrate decomposition |
Carb * DeCarb |
| GRCom2 |
Cellulose decomposition |
Cell * DeCell |
| GRCom3 |
Lignin decomposition |
Lign * DeLign |
| GRCom |
Total decomposition |
Sum of the three components |
Humus Formation
| Property |
Description |
Formula |
| FOMNhum |
N humified |
GRNom * FractionHumified |
| Resistant |
Humus formed |
(FractionHumified * GRNom) / 0.04 |
Mineralization
| Property |
Description |
Formula |
| HumMin |
Humus mineralization potential |
(Dminr * RMTFAC) / 0.04 |
| RhMin |
Humus N mineralization |
Dminr * RMTFAC |
| NetMin |
Net mineralization |
RhMin + (1 - FractionHumified) * GRNom |
Nitrogen Immobilization
| Property |
Description |
Formula |
| RNAC |
N immobilized |
max(0, min(INkg, GRCom * 0.0213 - GRNom)) |
| MinFromFOMRate |
N mineralized from FOM |
GRNom * (1 - FractionHumified) - RNAC |
| MinFromHumRate |
N mineralized from humus |
RhMin |
Miscellaneous Outputs
| Property |
Description |
Formula |
| Noname_1 |
Humified N added to humus |
FOMNhum |
| Noname_2 |
N immobilized |
RNAC |
| overall_%N |
Total percent N in residue |
(FON / FOM) * 100 |