WEB SERVICES web services API documentation
A Web Service is a technology that allows applications to communicate remotely via the Internet, regardless of the platforms and languages on which they are based. Smart IS offers 4 elaborate web data services. These services can be integrated into software like R or WEB applications. To access the resources, authentication is required and allows you to identify with a Smartis server.
General operation
When an HTTP client requests a protected resource from the server, the server responds differently depending on the request:
- the request does not contain an identifying HTTP header, in which case the server responds with HTTP code 401 (Unauthorized: not allowed) and sends the information headers on the requested identification.
- the request contains the HTTP identification headers, in this case, after checking the name and the password, if the identification fails, the server responds with the code 401 as in the previous case, otherwise it answers by normal way (code 200 OK).
Step 1 - Secure access to web services via 'Basic authorization' in the request header.
Authorization: Basic login:password
The 'password' must be encrypted with the sha2 512 algorithm. SHA-2 (Secure Hash Algorithm)
Authorization: Basic login:b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86
Step 2 - Base 64 encryption 'login:b109f3bbbc244eb82441917ed06d618b9008dd09b3befd1b5e07394c706a8bb980b1d7785e5976ec049b46df5f1326af5a2ea6d103fd07c95385ffab0cacbc86'
Authorization: Basic bG9naW46YjEwOWYzYmJiYzI0NGViODI0NDE5MTdlZDA2ZDYxOGI5MDA4ZGQwOWIzYmVmZDFiNWUwNzM5NGM3MDZhOGJiOTgwYjFkNzc4NWU1OTc2ZWMwNDliNDZkZjVmMTMyNmFmNWEyZWE2ZDEwM2ZkMDdjOTUzODVmZmFiMGNhY2JjODY=
# WSSMARTIS PACKAGE - EXAMPLE OF USE # Use the R package wssmartis available for download above to test the script below # STEP 1 [FIRST TIME], install the wssmartis package by selecting the download file above. install.packages(file.choose(),repos=NULL) # Installing the : httr, openssl. install.packages('httr') install.packages('openssl') # STEP 2 Load the wssmartis library : library(wssmartis) # STEP 3: Initialise your login and password : # For CIRAD agents, enter your email address login (last name only) lgin<-'user' # Your password must be hashed with the SHA-512 algorithm used by SMARTIS. # If you don't want your password to appear in clear text in your script you can retrieve the result of encrypt_pwd_smartis('your_password') from another script and 'source' it at the beginning of the script: pwd<-encrypt_pwd_smartis('password') # creation of an R object representing your identity credential<-get_credential(lgin,pwd) # STEP 4: CALL FOR WEB SERVICES # Surround the call to the web service functions with a condition verifying that the authentication was successful: if (class(credential)== 'request'){ # Access to geolocated data: latitude = "-21.27657804234913" longitude = "55.39031982421876" geo_data<-ws_geo_meteo(credential,'2022-01-01','2022-01-10',latitude,longitude) # FREQUENCY ANALYSIS OVER 10 YEARS # Daily frequency analysis calculated over 10 full years: # The calculation is as follows: for each day of all years, the median value for rainfall, the average temperature, # PET, the radiation is returned. freq_data<-ws_meteo_frequency(credential,latitude,longitude,altitude,'2020-01-01','2020-12-31') print(freq_data) rr tm etp glot jour 1 4.5 26.8 5.4 25.93 1 2 1.1 25.7 3.2 13.09 2 3 10.6 24.4 2.0 6.39 3 4 2.3 24.2 1.5 4.76 4 . . 366 23.8 18.9 1.6 3.26 366 # Data at the foot of the station in daily format: # Below are the possible values for the variable 'parameters', it is possible to combine these parameters # by separating them with a "|", example : # rr : Rainfall in mm # glot : Global radiation in J/cm2 # tn : Minimum temperature in °C # tx : Maximum temperature in °C # tm : Average temperature in °C # etp : Potential evapotranspiration in mm/d # adv : Advective part of the PET in mm/d # rad : Radiative part of the PET in mm/d # vt : Wind quantity in km/d # un : Minimum relative humidity in % # ux : Maximum relative humidity in % # um : Average relative humidity in % # dirmoy : Prevailing wind direction in relation to the North in ° # fxy : Maximum instantaneous speed in m/s # Example to get all the parameters: parametres <- "rr|glot|vt|tm|tn|tx|etp|dirmoy|fxy" # Example to have 2 parameters: parametres <- "rr|glot" id_station <- "97416465" # WEB SERVICE call : data_q_pied_station <- ws_station_meteo(credential,id_station,'2022-01-01','2022-01-10',parametres,'Q') print(data_q_pied_station) "Numero de la station" "Nom de la station" Jour rr glot 1 97416465 "Ligne Paradis" 01-01-2022 0.0 2382 2 97416465 "Ligne Paradis" 02-01-2022 0.0 2300 3 97416465 "Ligne Paradis" 03-01-2022 0.0 2557 4 97416465 "Ligne Paradis" 04-01-2022 0.0 2828 5 97416465 "Ligne Paradis" 05-01-2022 0.0 2727 6 97416465 "Ligne Paradis" 06-01-2022 12.5 1139 7 97416465 "Ligne Paradis" 07-01-2022 0.0 1502 8 97416465 "Ligne Paradis" 08-01-2022 18.0 1720 9 97416465 "Ligne Paradis" 09-01-2022 0.0 2200 10 97416465 "Ligne Paradis" 10-01-2022 7.0 1142 # Data at the foot of the station in hourly format: data_h_pied_station <- ws_station_meteo(credential,id_station,'2022-01-01','2022-01-10',parametres,'H') # Data in CNA format (Météo-France format): cna<-ws_mf_meteo(credential,id_station,start_date,end_date,header) # Data for the climate change study: SS126 scenario brio_ssp126<-ws_brio_data(credential,latitude,longitude,"2050-01-01","2050-01-03","ssp126") # Data for the climate change study: SS245 scenario brio_ssp245<-ws_brio_data(credential,latitude,longitude,"2050-01-01","2050-01-03","ssp245") # Data for the climate change study: SS585 scenario brio_ssp585<-ws_brio_data(credential,latitude,longitude,"2050-01-01","2050-01-03","ssp585") # Description of the SSP126 scenario print(paste("Info scenario :",choix_scenario('ssp126'))) # Description of the SSP245 scenario print(paste("Info scenario :",choix_scenario('ssp245'))) # Description of the SSP585 scenario print(paste("Info scenario :",choix_scenario('ssp585'))) # Recovery of the useful soil reserve (Raunet map) : ru <- as.matrix(ws_ru(credential,'-21.34886257728332','55.524215698242195'))[1] # Extraction of the altitude of a position from the DTM at 5 m spatial resolution coordinates in WGS84 or WGS84-UTM40S) alti <- as.matrix(ws_alti_dd(credential,'-21.34886257728332','55.524215698242195'))[1] alti <- as.matrix(ws_alti_m(credential,'7681258.2627135','329735.358086943'))[1] # FUNCTION OF OPERATING THE MOSICAS MODEL BY WEB SERVICE: # Coding of the variety name according to the database code : variete<-choix_variete('R585') # Calling the mosicas growth model : result_simulation<-ws_mosicas(credential,'-21.34886257728332','55.524215698242195','2018-07-01','2019-06-30',50,0.5,ru,1,10,variete,1,25,7,400,1,80) # Calling the mosicas growth model on a 3x3 km grid, the coordinate is used to determine the cell. # Weather data is available from 2015 to 2100: result_simulation_g<-ws_mosicas_grid(credential,'-21.34886257728332','55.524215698242195','2028-07-01','2029-06-30',50,0.5,ru,1,10,variete,1, 25,7,400,1,80,code_scenario('ssp126')) }else{ print("Login or password error ") }
Description: Geolocated daily weather data for a date range
URL: https://smartis.re/api/WSMeteo
Method: GET
URL settings:
Mandatory: long= [°Decimal] (GPS coordinates: longitude)
Mandatory: lat=[°Decimal] (GPS coordinates: latitude)
Mandatory: startdate= [date (YYYY-MM-DD)] Start of the date range
Mandatory: enddate= [date (YYYY-MM-DD)] End of the date range
Optional: format = [String] Data format ('csv','raw')
HTTP response codes: Success (200 OK), Bad Request (400), Unauthorized (401)
Query example: https://smartis.re/api/WSMeteo?long=55.307965278625495&lat=-21.140868798573788&startdate=2018-01-01&enddate=2018-09-27&format=raw
Response example:[]
{ "header": [ "Position", // Reminder of the requested coordinates + reference of the altitude determined on the DTM at 5m. "Date", "rr", // Rain in mm/d "glot", // Global radiation in J/cm2 "tn", // Minimum temperature observed over 24H in °C/d "tm",// Mean temperature observed over 24H in °C/d "tx",// Maximum temperature observed over 24H in °C/d "etp"// Potential evapotranspiration calculed in mm/d ], "rows": [{ "position": "(55.3079652786255,-21.1408687985738,734)", "dat": "2018-01-01", "rr": "10.1", "glot": "1214", "tn": "19.0", "tm": "21.3", "tx": "25.0", "etp": "2.71" }, { "position": "(55.3079652786255,-21.1408687985738,734)", "dat": "2018-01-02", "rr": "4.4", "glot": "1400", "tn": "19.5", "tm": "22.3", "tx": "25.4", "etp": "2.91" }.... }
Description: Geolocated frequency analysis for a date range
URL: https://smartis.re/api/WSMeteoFrequencyAnalysis
Method: GET
Header settings:
URL settings:
Mandatory: long= [°Decimal] (GPS coordinates: longitude)
Mandatory: lat=[°Decimal] (GPS coordinates: latitude)
Mandatory: startdate= [date (YYYY-MM-DD)] Start of the date range
Mandatory: enddate= [date (YYYY-MM-DD)] End of the date range
Optional: format = [String] Data format ('csv','raw')
HTTP response codes: Success (200 OK), Bad Request (400), Unauthorized (401)
Response example:[]
[{ "rr": "2.5", "tm": "27.1", "etp": "6.4", "glot": "28.46", "jour": "1" }, { "rr": "0.1", "tm": "26.9", "etp": "3.9", "glot": "17.40", "jour": "2" }...]
URL: https://smartis.re/api/WSMosicas
Method: GET
Header settings: URL settings:
Mandatory: long= [°Decimal] (GPS coordinates: longitude)
Mandatory: lat=[°Decimal] (GPS coordinates: latitude)
Mandatory: startdate= [date (YYYY-MM-DD)] Start of the date range
Mandatory: enddate= [date (YYYY-MM-DD)] End of the date range
Mandatory: remplissage= [integer] Filling (%)
Mandatory: p0= [integer] P0
Mandatory: ru= [integer] Useful reserve (mm)
Mandatory: profrac= [integer] Root depth (m)
Mandatory: ressurf= [integer] Surface tank (mm)
Mandatory: variete= [integer] Variety []
id = 0 => nom = Inconnue
id = 1 => nom = B 5992
id = 2 => nom = B 69379
id = 3 => nom = B 69566
id = 4 => nom = B 8008
id = 5 => nom = B 80689
id = 6 => nom = B 82139
id = 7 => nom = B 47528
id = 8 => nom = B 51129
id = 9 => nom = CO 6415
id = 10 => nom = R 570
id = 11 => nom = R 579
id = 12 => nom = R580
id = 13 => nom = R581
id = 14 => nom = R582
id = 15 => nom = R583
id = 18 => nom = NCO 376
id = 19 => nom = Mex 68 / 200
id = 20 => nom = R577
id = 21 => nom = R92 804
id = 0 => nom = Repousse
id = 1 => nom = Vierge
Mandatory: freqdose= [integer] Irrigation frequency (j)
Mandatory: freq= [integer] Value defined to 1
Optional: format = [String] Data format ('csv','raw')
HTTP response codes: Success (200 OK), Bad Request (400), Unauthorized (401)
Response example:[]
[{ "codtrait": 1, "id_bassin": 1, "datesimul": "2017-01-01", "nomplante": "R570", "dmbaer": 0, "dmstm": 0, "dmsug": 0, "etm": 1.56, "etp": "1.56", "etr": 1.56, "irdose": 0, "jat": 0, "nage": 1, "pari": 0, "rr": "4.9", "rg": 8, "sdj": 3.55, "sug_stm": 0, "tmo": 15.55, "tn": "12.6", "tx": "18.5", "yldcan": 0, "lai": 0, "ei": 0, "kcp": 0, "stmo": 15.55, "stmot": 0, "swdf1": 1, "swdf2": 1, "swdef": 0.001, "mst": 0, "swdfpart1": 1, "trp": 0, "runoff": 0, "srunoff": 0, "runofft": 0, "srunofft": 0, "par": 4, "spar": 4, "spari": 0, "sparit": 0, "drain": 0, "sdrain": 0, "sdraint": 0, "sddbla": 3.55, "sddblat": 0, "setp": 1.56, "setm": 1.56, "setr": 1.56, "setpt": 0, "setmt": 0, "setrt": 0, "dmrac": 0, "tmp": 0, "strpt": 0, "strp": 0, "stmp": 0, "stmpt": 0, "stock": 53.34, "stockfr": 0, "stockm": 5.84, "htvd": 0, "spr": 4.9, "stockevap": 10, "swdefm": 0.0005, "swdf1m": 0.5, "swdf2m": 0.5, "swdeft": 0, "swdf1t": 0, "swdf2t": 0, "tableclimat": "mosiweb.mos_meteo_parcelle", "id_session": "abedc5820a49a21b92e20ac65f553d23feb07331" },...]
Description: Useful reserve
URL: https://smartis.re/api/WSRU
Method: GET
Header settings:
URL settings:
Mandatory: long= [°Decimal] (GPS coordinates: longitude)
Mandatory: lat=[°Decimal] (GPS coordinates: latitude)
Optional: format = [String] Data format ('csv','raw')
HTTP response codes: Success (200 OK), Bad Request (400), Unauthorized (401)
Query example: https://smartis.re/api/WSRU?lat=-21.219748964663875&long=55.32440185546876&format=raw
Response example:[]
[{"ru":70}]
Description: Elevation - DTM
URL: https://smartis.re/api/WSALTI
Method: GET
Header settings:
URL settings:
Mandatory: long= [°Decimal] (GPS coordinates: longitude)
Mandatory: lat=[°Decimal] (GPS coordinates: latitude)
Optional: format = [String] Data format ('csv','raw')
Optional: unit = [String] WEBSERVICES.unit
HTTP response codes: Success (200 OK), Bad Request (400), Unauthorized (401)
Query example: https://smartis.re/api/WSALTI?lat=-21.219748964663875&long=55.32440185546876&unit=dd&format=raw
Response example:[]
[{"altitude":441}]