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://www.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
3 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:
- d: simulated day (first d=1)
- Year: (YYYY)
- DOY: day of the year (1 = 1 First of January, 365 = 31th of December)
- Precipitation mm
- PET: potential evapotranspiration mm
- PE: potential evaporation mm
- E: actual evaporation mm
- PT: potential transpiration mm
- AT: actual transpiration mm
- Run off: mm
- AW: available water mm
- Deficit: water to reach 100 % of AW mm
- water content (m3 m-3) of soil layer 1.
- water content (m3 m-3) of soil layer 2.
- water content (m3 m-3) of soil layer 3.
- water content (m3 m-3) of soil layer 4.
- water content (m3 m-3) of soil layer 5.
- water content (m3 m-3) of soil layer 6.
- water content (m3 m-3) of soil layer 7.
- water content (m3 m-3) of soil layer 8.
- water content (m3 m-3) of soil layer 9.
- water content (m3 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:
- Year (YYYY)
- DOY
- Precipitation mm
- Maximum daily air temperature ºC
- Minimum daily air temperature ºC
- Daily solar global radiation MJ day-1
- Maximum air relative humidity %
- Minimum air relative humidity %
- 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:
- site name (string)
- latitude in decimal degrees (GGG.DD), negative for south hemisphere.
- longitude in decimal degrees (GGG.DD), negative for west.
- 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.
- layer number 1 to 10 (FIX)
- layer thickness m(FIX)
- bulk density MG m-3
- FC: field capacity (m3 m-3 a 33 J Kg-1).
- PWP: permanent wilting point (m3 m-3 a 1500 J Kg-1).
- water content at the start of the simulation (d=1) m3 m-3
- clay fraction g g-1
- 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.