Agriculture Data by NuaSense Get a free keyFree key

Root-zone water balance and irrigation need for your own field, daily

1 row per station per day: root-zone depletion against the water the soil holds, with the day's evapotranspiration and rain, the numbers behind the irrigation advisory.

Catalogue entry: Root-zone water balance. One point per station per daily cycle, combining the soil's available water capacity, derived evapotranspiration and forecast rain.

Questions this data answers

  • Does the field need irrigation today, and how many millimetres would bring the root zone back to field capacity?
  • How much of the readily available water has the crop used since the last irrigation?
  • Does tomorrow's forecast rain cover the deficit, so the pump can stay off?
  • What is the total available water over the root depth here, compared with a neighbouring field?
  • Why does the balance read saturated when the field looks dry?
On this page
  1. Questions this data answers
  2. The balance
  3. When the advisory fires
  4. The Naivasha case
  5. Reading the table
  6. Sample data
  7. Fields
  8. Filters
  9. The same call, three ways
  10. Related datasets

The balance

The root zone holds a fixed amount of water between field capacity and wilting point; the plant can draw part of it freely and the rest only under stress. Total available water and readily available water, both in millimetres over the root depth, come from the water-retention profile in the soil baseline. Depletion tracks how much of that store has been used: the previous day’s depletion, plus the day’s crop water use, minus rain and irrigation. Crop water use itself is reference evapotranspiration from the derived variables multiplied by a coefficient for the crop’s current stage. The rain field nets off forecast rain for the day ahead before any of this is reported. The deficit ratio, finally, is simply depletion over total available water, reading 0 at field capacity and 1 at wilting point.

When the advisory fires

The irrigation advisory reads this row directly. The moment depletion crosses readily available water with no rain in the forecast, it recommends a depth that would bring the root zone back to field capacity, and writes that advisory to the advisory history regardless of whether it was sent.

The Naivasha case

The chart shows 40 days of depletion sitting at 0 with a status of saturated throughout. The probes themselves read 78 to 85 in volume-percent terms against a field capacity in the 30s, simply because the node’s own scale was never calibrated to the baseline. The balance is arithmetically correct here and agronomically silent at the same time, and the row says exactly that with a calibration flag attached. Calibrating the probe is the 1 step that turns this series from noise into something the irrigation advisory can fire on.

Reading the table

Total available water of 54 mm and readily available water of 19 mm both come from the baseline’s water-retention profile over the root depth. The crop coefficient follows the crop stage straight off the sensor settings. The season runs start=-120d; today’s status through the connector is simply the irrigation tool, which returns the latest row along with its recommendation.

Sample data

40 days of root-zone balance, the potato station at Naivasha, 2,490 m

Depletion at 0 across the window: the probe reads 78 to 85 vol-% against a field capacity in the thirties, so the balance reports saturated and the irrigation advisory does not fire. The probe scale needs calibrating against the baseline before this series carries information; the platform marks the output as a sensor proxy until then.
DayDepletion mmTAW mmRAW mmCrop coefficientProbe vol-%Status
10-12054.319———
10-13054.319———
10-14054.319———
10-15054.319———
10-16054.319———
10-17054.319———
10-18054.319———
10-19054.319———

Total available water 54 mm and readily available water 19 mm come from the soil baseline's water-retention profile over the root depth. The crop coefficient follows the crop stage from sensor settings.

Dataset idfarm.water_balance
Cadencedaily
EndpointGET /farm/water-balance
Key scopefarm:read
Declared fields6
History2026-06 to today
Coverageyour own stations
StatusServed over the API

Narrowed to your own gateways and to devices approved for API exposure.

Fields

FieldUnitNote
depletion_mmmmroot-zone depletion
taw_mmmmtotal available water
raw_mmmmreadily available water
et0_mmmm
rain_mmmm
deficit_ratio0-1

Filters

gateway_id

The same call, three ways

curl -G https://api.nuasense.com/api/nuasense/v1/farm/water-balance \
  -H "Authorization: Bearer nua_live_…" \
  -d start=-30d -d start=-60d

Through the MCP connector the same read is the platform_dataset tool with dataset=farm.water_balance. Through a scheduled export it is one job with the same filters, delivered as a file. Every dataset takes the same arguments: start and end, every with agg, fields, limit up to 5,000, order, and the tags it declares.