Irrigation Need

Agriculture Math & Calculations Credits / request: 1

Calculates irrigation need in mm and m³ using FAO-56 ETc = ET0 × Kc.

GET https://api.apikodu.com/api/v1/agriculture/irrigation

Documentation

Overview

FAO-56 ETc and volume. 1 da = 1 donum = 1000 m². Decision support, not a prescription.

Authentication

Every request requires the x-api-key header. Credits used and remaining quota are returned in response headers (x-api-credits-used, x-api-remaining-credits, x-rate-limit-*).

Request

GET https://api.apikodu.com/api/v1/agriculture/irrigation?area=50&areaUnit=da&crop=maize&stage=mid&et0Mm=5.2

Query string.

Parameters

Name	Type	Required	Default	Options	Description
`area`	number	* Required	—	—	Area > 0.
`areaUnit`	string	Optional	`da`	`da` `dekar` `donum` `ha` `are` `m2`	Area unit.
`crop`	string	Optional	—	`wheat` `barley` `maize` `sunflower` `cotton` `potato` `tomato` `rapeseed` `oats` `rye` `sugarbeet` `grape` `apple` `chickpea` `lentil`	Crop code. Required if kc is empty.
`stage`	string	Optional	`mid`	`initial` `mid` `late`	FAO Kc stage.
`kc`	number	Optional	—	—	0–2. From table if empty.
`et0Mm`	number	Optional	—	—	Empty uses DB/Hargreaves via lat/lon.
`fromDate`	string	Optional	—	—	Weather window start.
`toDate`	string	Optional	—	—	Weather window end.
`latitude`	number	Optional	—	—	Cell when et0Mm is empty.
`longitude`	number	Optional	—	—	Longitude.
`includeDaily`	boolean	Optional	`true`	`true` `false`	Daily breakdown.

Response

Name	Type	Description
`etcMm`	number	Crop evapotranspiration mm. ETc = ET0 × Kc (FAO-56).
`et0Mm`	number	Reference evapotranspiration mm. From the request or Hargreaves/DB.
`kc`	number	Crop coefficient used. From the request or FAO table (stage).
`stage`	string	FAO Kc stage: initial, mid, late.
`volumeM3`	number	Irrigation volume m³ = etcMm/1000 * areaM2.
`areaM2`	number	Area in square meters. 1 da = 1000 m².
`areaDecares`	number	Area in decares (da).
`crop`	string	Normalized crop code. Null if omitted.
`fromDate`	string	Window start YYYY-MM-DD.
`toDate`	string	Window end YYYY-MM-DD.
`daysTotal`	integer	Calendar days in the window (fromDate..toDate).
`daysWithData`	integer	Days that have temperature data.
`missingCount`	integer	Days without data. missingDates.Length.
`missingDates`	array	YYYY-MM-DD list of missing days.
`gridLatitude`	number	0.1° cell latitude. Null when dailyTemps was used.
`gridLongitude`	number	0.1° cell longitude. Null when dailyTemps was used.
`daily`	array	Daily ETc when includeDaily=true and a date window is set. Otherwise empty.
`daily[].date`	string	Day YYYY-MM-DD.
`daily[].et0Mm`	number	ET0 mm for that day.
`daily[].etcMm`	number	ETc mm for that day.
`method`	string	Calculation method. fao56-etc for this API.
`source`	string	user: dailyTemps or et0Mm. db: tarim_hava cell.
`disclaimer`	string	Decision-support disclaimer. Not agronomic advice or a prescription.

Errors

HTTP	code	Description
`400`	`-252`	area missing/≤0 or areaUnit is not da, dekar, donum, ha, are, m2.
`400`	`-250`	both crop and kc missing, or crop is unknown.
`400`	`-249`	stage is not initial/mid/late, kc outside 0–2, Kc not in table, or et0Mm negative.
`400`	`-254`	fromDate/toDate missing, not YYYY-MM-DD, or the window exceeds 366 days.
`400`	`-255`	latitude/longitude are required without dailyTemps. Latitude -90..90, longitude -180..180.
`429`	`-316`	Daily new location (cell) limit (50) reached. Previously requested locations keep working; new locations next day (UTC). Retry-After header gives seconds until end of day.
`503`	`-256`	Cell created; Worker is filling the last 730 days. Retry in a few minutes.
`400`	`-251`	No weather for this location/date (and no dailyTemps).
`401`	`-100`	x-api-key is missing, empty, malformed, inactive, banned, expired, IP-restricted, or not allowed for this API.
`429`	`-221`	Per-minute request limit exceeded. Response headers: x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset.
`429`	—	Package credit quota cannot cover this request. Body may be { error, limit, currentUsage, requestCost } (no code field).
`500`	`-1`	Unexpected server error. message is a generic error text without technical details.

Notes

Success body is { data: { ... } }. Error body is { code, message }. code is an ApiResponseCode enum value (negative integer).

Sample response

{
  "data": {
    "etcMm": 6.24,
    "et0Mm": 5.2,
    "kc": 1.20,
    "stage": "mid",
    "volumeM3": 312.0,
    "areaM2": 50000.0,
    "areaDecares": 50.0,
    "crop": "maize",
    "method": "fao56-etc",
    "source": "user",
    "disclaimer": "Decision support only. Not agronomic advice."
  }
}

Code samples

  
      const response = await fetch('https://api.apikodu.com/api/v1/agriculture/irrigation', {
        method: 'GET',
        headers: {
          'x-api-key': 'YOUR_API_KEY'
        }
      });

      const data = await response.json();
      console.log(data);

  
      import requests

      headers = {
          'x-api-key': 'YOUR_API_KEY'
      }

      response = requests.get('https://api.apikodu.com/api/v1/agriculture/irrigation', headers=headers)
      print(response.json())

  
      using var client = new HttpClient();
      client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

      var response = await client.GetStringAsync("https://api.apikodu.com/api/v1/agriculture/irrigation");
      Console.WriteLine(response);

  
      $response = file_get_contents('https://api.apikodu.com/api/v1/agriculture/irrigation', false, stream_context_create([
          'http' => [
              'header' => "x-api-key: YOUR_API_KEY"
          ]
      ]));

      print_r(json_decode($response, true));

  
      curl -X GET 'https://api.apikodu.com/api/v1/agriculture/irrigation' \
        -H 'x-api-key: YOUR_API_KEY'

Start building in minutes

Create a free account, get your API key and send your first request in minutes.

Get started free