US

The goal is to develop online and simulation-based tools to assist on the decision-making process in agricultural systems. There are several web sites that offer online weather and environmental information in real time. Also, some of them incorporate map-based geographical and environmental information such as weather forecasting and satellite imagery. All that information resources have great potential in supplying decision makers, growers and any player operating on agricultural systems with key information to improve the decision-making process. Though, proved estimation methods and somewhat mechanistic simulation models of agro-ecosystems, integrated with geographical information, might improve drastically the knowledge and understanding of the natural system. Thus, the prediction of its behaviour will be based more on its functioning and therefore better options for its management will be more likely.

Method

Web services, through Application Programming Interfaces (APIs), provide a very powerful form of integrating cropping simulation models with web-based environmental and geographical databases. APIs provide a peer-to-peer inter-process communication by handling events triggered by the exchange of URIs (resource identifiers). Hence, a crop or any environmental model or processing algorithm can remotely be launched or executed by any other application or website that provides map-based data on geographical environmental information on the client side, e.g., Google Maps API.

A Demo:

AGRO-DATA implements at this time a very simple environmental simulation model: a soil water balance with a single soil cover (named at this time: Web API-SWB Basic). This model estimates in a very simple and direct manner the soil water balance yet involving most of the water fluxes and storage process occurring in a soil: infiltration, run-off, drainage, evaporation, transpiration, plant water stress, and water deficit. Plant transpiration is estimated for a single, permanent and reference plant cover with a fix root depth and distribution.

Next

Our idea is to expand this simple model (Web API-SWB Basic) to a broader range of models that can be used either for simple environment-crop relationships (e.g. water balance, crop development) or for more comprehensive agro-ecosystems modelling (e.g. nutrient balances and cycling, carbon dynamics, rotations). The product would be a set of models, included in a sort of toolbox and used with Web APIs, that can be picked according to specific needs.

This demo tests a method of accessing and executing agro-ecosystems models via a Web API. The API allows the on-line delivery of input data, execution of the model and obtaining the results. The data calculated by the model are ready for using in web applications (potential users). The demo is described first (A) from the agronomics and then (B) from the programming details on using the API.

Web API-SWB Basic: web address:

The Web API to run the SWB Basic is located at: http://www2.agro-data.net/client.php

User name: guesttoswb

Password: guesttoenter

A) Web API-SWB Basic: Agronomics

The SWB Basic estimates in a very simple way the soil water balance. Nevertheless, it includes most of the water fluxes and storage process occurring in a soil: infiltration, runoff, drainage, evaporation, transpiration, plant water stress, and water deficit. It calculates the water available for crop transpiration (AW) as the soil water content (m³ m^-3) between field capacity (FC) and permanent wilting point (PWP). Those water contents are the water retained at 33 and 1500 J kg^-1 respectively. Transpiration, the water consumption from the soil by plants, is estimated as the water uptake of a reference and permanent plant cover that explores 1 m depth of soil. This reference plant cover is assumed to have a leaf area index that gives a value of 0.85 for fraction interception of global radiation. Transpiration of this reference cover is included in order to approximate a cultivated soil water balance. By not including this reference transpiration, soil water can be overestimated.

Next, we describe input and output data. They are organized in arrays (n x m) that have no headings and not all columns (m) are used in this sample demo. They will be used in further model expansions.

Daily outputs of SWB Basic are arranged in a d x 22 array:

1. d: simulated day (first d=1)
2. Year: (YYYY)
3. DOY: day of the year (1 = 1 First of January, 365 = 31^th of December)
4. Precipitation mm
5. PET: potential evapotranspiration mm
6. PE: potential evaporation mm
7. E: actual evaporation mm
8. PT: potential transpiration mm
9. AT: actual transpiration mm
10. Run off: mm
11. AW: available water mm
12. Deficit: water to reach 100 % of AW mm
13. water content (m³ m^-3) of soil layer 1.
14. water content (m³ m^-3) of soil layer 2.
15. water content (m³ m^-3) of soil layer 3.
16. water content (m³ m^-3) of soil layer 4.
17. water content (m³ m^-3) of soil layer 5.
18. water content (m³ m^-3) of soil layer 6.
19. water content (m³ m^-3) of soil layer 7.
20. water content (m³ m^-3) of soil layer 8.
21. water content (m³ m^-3) of soil layer 9.
22. water content (m³ m^-3) of soil layer 10.

Input data consists of (3) arrays:

a) (weadata): daily weather data, size: d x 9

b) (locdata): location data, size: 1 x 20

c) (soildata): soil data, size: 10 x 20

• (weadata): THIS SETS THE LENGTH (DAYS) OF THE SIMULATION AND THE START AND END DATES and has the format:
  1. Year (YYYY)
  2. DOY
  3. Precipitation mm
  4. Maximum daily air temperature ºC
  5. Minimum daily air temperature ºC
  6. Daily solar global radiation MJ day^-1
  7. Maximum air relative humidity %
  8. Minimum air relative humidity %
  9. Daily mean wind speed m s^-1
  IMPORTANT: positions 1 and 2 (Year and DOY) of the first and last row set the length, total days and start and end dates of the simulation.
• (locdata): only few positions are used:
  1. site name (string)
  2. latitude in decimal degrees (GGG.DD), negative for south hemisphere.
  3. longitude in decimal degrees (GGG.DD), negative for west.
  4. sea level altitude in m
  positions 5 to 20 are not used in this SWB Basic. However, the 1 x 20 structure is kept for more flexibility when expanding this demo.
• (soildata): input data are for a soil profile with a fix number of layers (10) with fix values of layer thickness. Therefore, the first two columns are fix and MUST BE SUPPLIED AS INDICATED IN THE EXAMPLES.
  1. layer number 1 to 10 (FIX)
  2. layer thickness m(FIX)
  3. bulk density MG m^-3
  4. FC: field capacity (m³ m^-3 a 33 J Kg^-1).
  5. PWP: permanent wilting point (m³ m^-3 a 1500 J Kg^-1).
  6. water content at the start of the simulation (d=1) m³ m^-3
  7. clay fraction g g^-1
  8. silt fraction g g^-1
  positions 9 to 20 are not used in this SWB Basic. However, the 10 x 20 structure is kept for more flexibility when expanding this demo.

Daily output data were chosen among those that have some potential to be used for web applications. From the entire range of output data, the user can pick any number of variables for using in his web application. In addition, intermediate or data not supplied by this demo at this time can be provided by user’s request to the output palette.

Input data examples are provided in the API web page. They are ready for using to simulate soil water balance for 90 days (December, January and February) at three Argentinian locations (General Pico, Rio Cuarto and Junin) during two contrasting years (2010/11 and 2011/12). These examples can be used as reference in how to build input data sets.

B) Web API-SWB Basic: using the API

The SWB Basic hooks up with web applications via a PHP script that implements a server side JSONRPC 2.0 protocol node for remote execution of the SWB Basic. The JSONRPC 2.0 protocol uses JSON for coding input and output data (http://www.json.org/jsones). This format was chosen because is fast and lightweight. As mentioned in the agronomics, the SWB Basic engine requires inputs arranged as one (locdata) and two ((weadata) and (soildata)) dimension arrays. In this application we use JSON to build multi dimension arrays by nesting arrays, e.g., a two dimension array consists on an array which elements are arrays themselves. Arrays in JSON must begin with a left bracket ( [ ) and end with a right bracket ( ] ).

The (weadata) array is built as follows (for a 10-day simulation):

[ [2011,350,0,29.56,12.13,36.89,93.17835,23.320805,1.9226984], [2011,351,0,29.43,12.4,32.17,89.61349,25.528276,1.1191945], [2011,352,0,33.77,12.06,37.16,86.73418,13.160954,0.4543664], [2011,353,0,36.83,13.33,33.74,82.20955,9.842892,1.1681389], [2011,354,0,37.17,15.46,35.16,83.58065,12.790757,0.8336855], [2011,355,0,37.31,19.68,28.47,59.17507,16.245929,4.0558585], [2011,356,0,38.12,19.81,34.19,81.11267,20.51005,4.9205429], [2011,357,0,31.3,16.27,35.52,90.43615,13.394041,2.8811929], [2011,358,0,22.95,10.31,23.39,70.69231,27.022775,2.5548969], [2011,359,0,25.56,5.427,36.51,90.84748,17.301676,2.4977951] ]

The (locdata) arrays is built as:

["Mackenna",-33.9,-64.5,250,0.1,0.1,17,10,0.2,0.2,90,0.1,80,0.5,20,2,4,1,1,1]

The (soildata) array as:

[ [1,0.05,1.4,0.3,0.1,0.3,0.1,0.2,1,0.001,0.0001,6,0.055079559,0.06,40,0.2,0.07,0.9,0.03,0.03], [2,0.05,1.4,0.3,0.1,0.3,0.1,0.2,1,0.002,0.0002,6,0.036719706,0.06,40,0.7,0.07,0.9,0.03,0.03], [3,0.2,1.4,0.3,0.1,0.3,0.1,0.2,0.8,0.002,0.0002,7,0.02753978,0.06,40,0.7,0.07,0.9,0.03,0.03], [4,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.05,0.001,0.0001,7,0.018359853,0,0,0,0.07,0.9,0.03,0.03], [5,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.05,0.0005,0.00005,7,0.009179927,0,0,0,0.07,0.9,0.03,0.03], [6,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0005,0.00005,7,0.001835985,0,0,0,0.07,0.9,0.03,0.03], [7,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0005,0.00005,7,0.00128519,0,0,0,0.07,0.9,0.03,0.03], [8,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0002,0.00002,7,0,0,0,0,0.07,0.9,0.03,0.03], [9,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0001,0.00001,7,0,0,0,0,0.07,0.9,0.03,0.03], [10,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0001,0.00001,7,0,0,0,0,0.07,0.9,0.03,0.03] ]

JSONRPC

The API uses a client-server protocol that transports data through TCP or HTTP protocols. For this application we have chosen HTTP. HTTP Requests sent to the script of the Web API are of the type POST. The body of the HTTP request includes the Object Request and it receives the Response Object.

The Object Request to run the SWB Basic via the Web API (input data) has the following format: (http://www.jsonrpc.org/specification#request_object)

{ "jsonrpc" : "2.0", "method" : "SWB_class.run", "params" : { "weadata" : [ [2011,350,0,29.56,12.13,36.89,93.17835,23.320805,1.9226984], [2011,351,0,29.43,12.4,32.17,89.61349,25.528276,1.1191945], [2011,352,0,33.77,12.06,37.16,86.73418,13.160954,0.4543664], [2011,353,0,36.83,13.33,33.74,82.20955,9.842892,1.1681389], [2011,354,0,37.17,15.46,35.16,83.58065,12.790757,0.8336855], [2011,355,0,37.31,19.68,28.47,59.17507,16.245929,4.0558585], [2011,356,0,38.12,19.81,34.19,81.11267,20.51005,4.9205429], [2011,357,0,31.3,16.27,35.52,90.43615,13.394041,2.8811929], [2011,358,0,22.95,10.31,23.39,70.69231,27.022775,2.5548969], [2011,359,0,25.56,5.427,36.51,90.84748,17.301676,2.4977951] ], "locdata" : ["Mackenna",-33.9,-64.5,250,0.1,0.1,17,10,0.2,0.2,90,0.1,80,0.5,20,2,4,1,1,1], "soildata" : [ [1,0.05,1.4,0.3,0.1,0.3,0.1,0.2,1,0.001,0.0001,6,0.055079559,0.06,40,0.2,0.07,0.9,0.03,0.03], [2,0.05,1.4,0.3,0.1,0.3,0.1,0.2,1,0.002,0.0002,6,0.036719706,0.06,40,0.7,0.07,0.9,0.03,0.03], [3,0.2,1.4,0.3,0.1,0.3,0.1,0.2,0.8,0.002,0.0002,7,0.02753978,0.06,40,0.7,0.07,0.9,0.03,0.03], [4,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.05,0.001,0.0001,7,0.018359853,0,0,0,0.07,0.9,0.03,0.03], [5,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.05,0.0005,0.00005,7,0.009179927,0,0,0,0.07,0.9,0.03,0.03], [6,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0005,0.00005,7,0.001835985,0,0,0,0.07,0.9,0.03,0.03], [7,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0005,0.00005,7,0.00128519,0,0,0,0.07,0.9,0.03,0.03], [8,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0002,0.00002,7,0,0,0,0,0.07,0.9,0.03,0.03], [9,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0001,0.00001,7,0,0,0,0,0.07,0.9,0.03,0.03], [10,0.3,1.4,0.3,0.1,0.3,0.1,0.2,0.01,0.0001,0.00001,7,0,0,0,0,0.07,0.9,0.03,0.03] ] }, "id" : 1 }

Output data are returned inside the Request Object that has the following format: (http://www.jsonrpc.org/specification#response_object) and has the following format:

{ "jsonrpc" : "2.0", "result" : [ [1,2011,350,0,7.0844594431752,1.0626689164763,1.0626689164763,6.0217905266989, 6.0113360292567,0,232.92599505427,7.074004945733,0.27874662167047,0.29017277240435, 0.29121822214856,0.293309121637,0.29581820102313,0.29832728040925,0.3,0.3,0.3,0.3], [2,2011,351,0,6.0006314909041,0.90009472363562,0.90009472363562,5.1005367672685, 5.0916343698487,0,226.93426596078,13.065734039217,0.26074472719776,0.28187190249461, 0.28379358088038,0.28764207283303,0.29226892402162,0.2969047308123,0.3,0.3,0.3,0.3], [3,2011,352,0,7.0205020570298,1.0530753085545,1.0530753085545,5.9674267484753, 5.9569748350257,0,219.9242158172,20.075784182797,0.23968322102667,0.27217991343357, 0.27511843461424,0.28101170058908,0.28811035169402,0.29523585495471,0.3,0.3,0.3,0.3], [4,2011,353,0,7.1863654022318,1.0779548103348,1.0779548103348,6.108410591897, 6.0976558908026,0,212.74860511607,27.251394883935,0.21812412481998,0.26229147121847, 0.26625674778817,0.27422407312142,0.28384372944952,0.29352044995076,0.3,0.3,0.3,0.3], [5,2011,354,0,7.2740652918948,1.0911097937842,1.0911097937842,6.1829554981106, 6.1720042864228,0,205.48549103586,34.514508964142,0.19630192894429,0.25232399051009, 0.25730987769615,0.26735229283478,0.27951281415359,0.291775624758,0.3,0.3,0.3,0.3], [6,2011,355,0,7.679278542283,1.1518917813425,1.1518917813425,6.5273867609406, 6.5157603674594,0,197.81783888706,42.182161112944,0.17326409331744,0.24184804388147, 0.24788953749505,0.26009549509028,0.27492737173033,0.28992488160639,0.3,0.3,0.3,0.3], [7,2011,356,0,9.2259368501974,1.3838905275296,1.3838905275296,7.8420463226678, 7.8280439663753,0,188.60590439315,51.394095606849,0.14558628276685,0.22929775968938, 0.23658914434378,0.2513740698654,0.26940922184518,0.2876962862947,0.3,0.3,0.3,0.3], [8,2011,357,0,7.3509331534337,1.1026399730151,1.1026399730151,6.2482931804187, 6.2369253030634,0,181.26633911707,58.733660882927,0.12353348330655,0.21946005291671, 0.22766932122852,0.24441596066771,0.26496796468413,0.28589206818218,0.3,0.3,0.3,0.3], [9,2011,358,0,4.1888106792652,0.62832160188978,0.62832160188978,3.5604890773754, 3.5536633695073,0,177.08435414568,62.915645854324,0.11096705126875,0.21412194504259, 0.22272490729998,0.24043565608804,0.26236376674653,0.28481698673247,0.3,0.3,0.3,0.3], [10,2011,359,0,6.4422217388943,0.96633326083414,0.96633326083415,5.4758884780602, 5.465658974364,0,170.65236191048,69.347638089522,0.091640386052072,0.20572961689001, 0.21502276905945,0.23432166023708,0.25841061207164,0.28319875419623,0.3,0.3,0.3,0.3] ], "error" : null, "id" : 1 }

For reference see: http://www.jsonrpc.org/specification

The Web API uses the server side JSONRPC protocol implementation for PHP coded by subutux available on GitHub https://github.com/subutux/json-rpc2php. This implementation allows the authentication of the requests by the addition of the "xrpcauthusername" and "xrpcauthpassword" fields at the header of the HTTP request.

Using the sample

When logging into the API-SWB Basic website you will find the examples. These examples are a set of input data and they intent to help the user to understand the building of the request object when interfacing with the SWB Basic via the API. Example input weather, location and soil data are stored in the server in *.csv files and can be selected from three drop-downs menus. Then, clicking the “send” button, the model is remotely run and output data is written in the box “Results(csv)”. For reference, the user can copy data from the boxes to check the format and quality of the data.

In addition, for testing purposes, the user can paste his own data into the input (“csv”) boxes and run the model. Preferably, the user should copy data from csv files formatted with the exact same format as the one shown in the “(csv)” boxes.

The boxes “Parameters JSON-RPC(params)” and “Results JSON-RPC(result)” show the Object Request with the input data and the Response Object with the output data respectively. The data (with the proper format) in these two boxes are written by the application ONLY to show how the input data should be formatted and how the results look like respectively.