eSWua Web-Service API documentation (V. 1.1.3)

INDEX

Introduction

The eSWua RESTful Web service is based on the PHP-CRUD-API project (https://github.com/mevdschee/php-crud-api).

The requests to the web service return the desired data in the JSON interchange format.

DATA POLICY: All the data available through the different services are distributed under the Creative Commons Attribution 4.0 International (CC BY 4.0).The eSWua datasets will be provided soon with the DOIs, in the meantime we kindly ask you to acknowledge the "eSWua system (www.eswua.ingv.it) owned by the Istituto Nazionale di Geofisica e Vulcanologia (INGV) and operated by the Upper Atmosphere Physics and Radiopropagation group.".

DATA DOWNLOAD LIMIT: the downloads are limited to a certain number of record at once; the maximum timespan for a single query depends on the specific instruments and on the number of the fields/parameters queried (approx. 1 day for raw ionograms, TEC maps and full parameters GNSS scintillation data, several days for requests with less parameters). When a query requires more than 1 minutes the service will stop the execution and the requests will fail; in this case, consider to reduce the temporal range/number of parameters or to code your own script to run consecutive queries to cover the whole timespan.

A description of the istruments adopted by the INGV ionospheric network is available here. A list of the station/istruments of the network is available here

Web service endpoint: http://ws-eswua.rm.ingv.it/

GNSS receivers data

The following tables of the eSWua Scintillation database are accessible through the web service:

| wsstation
| wsdmc0p
| wsdmc0s
| wsdmc1s
| wsdmc2s
| wskil0n
| wslam0s
| wslam0p
| wsnic0p
| wslyb0s
| wslyb0p
| wsmzs0p
| wsbtn0s
| wsnya0p
| wsnya1p
| wsnya1s
| wsnya0s
| wsnya1s
| wssan0p
| wshan0p
| wssao0p
| wsthu0p

The table wsstation contains the list of all the INGV GNSS receivers for scintillation and TEC monitor and it has the following fields:

| id
| code
| filecode
| name
| lat
| lon
| h
| area
| description
| fk_instrument
| modified
| instrument

The following tables contains the data for the different GNSS scintillation receivers:

Ionosondes data

The following tables of the eSWua Ionosondes database are accessible through the web service:

| station
| rm041_auto
| rm041_rev
| rm041_rdf
| gm037_auto
| gm037_rev
| gm037_rdf
| bbj3r_auto
| bbj3r_rdf
| tuj2O_auto
| tuj2O_rdf
| ro041_auto

The table station contains the list of all the INGV Ionosondes and it has the following fields:

| id
| code
| filecode
| name
| lat
| lon
| h
| area
| description
| fk_instrument
| modified
| instrument

The tables "station_code"_auto contain the autoscaled value and the reconstructed traces, the tables "station_code"_rdf contain the raw ionograms, the tables "station_code"_rev contain the manually validated parameter.
The following tables contain the data for the different Ionosondes:

TEC data

The following tables of the eSWua TEC database are accessible through the web service:

| station
| nc_med | nc_eu
| nc_gl
| ltf_gl

The nc_med table contains the nowcasted TEC data for the mediterranean area, the nc_eu table contains the nowcasted TEC data for the european area, the nc_gl table contains the nowcasted global world TEC data while the ltf_gl table contains the 24-hour forecasted global world TEC data.

Fields/parameters of the nc_med, nc_eu, nc_gl tables:

FIELD ----> DESCRIPTION
| dt
| refresh_rate
| tec_mean
| tec_std
| jfile ----> JSON field with the TEC map

Fields/parameters of the ltf_gl tables:

FIELD ----> DESCRIPTION
| dt
| refresh_rate
| tec_mean
| tec_std
| f_horizon
| r12_eff
| rgec_mean
| rgec_std
| jfile ----> JSON field with the TEC map

Web service basic requests

Starting index to access data:

http://ws-eswua.rm.ingv.it/scintillation.php/records/ ----> GNSS data

http://ws-eswua.rm.ingv.it/ais.php/records/ ----> Ionosondes data

http://ws-eswua.rm.ingv.it/tecdb.php/records/ ----> TEC data

The following instruction contains examples referred to the scintillation data; the same rules apply to the other databases by changing the web service endpoint and the requested fields.

  1. DATA DOWNLOAD LIMIT: the downloads are limited to a certain number of record at once; the maximum timespan for a single query depends on the specific instruments and on the number of the fields/parameters queried. When a query requires more than 1 minutes the service will stop the execution and the requests will fail; in this case, consider to reduce the temporal range or to code your own script to run consecutive queries to cover the whole timespan.

  2. The field dt contains the time in which the measurements are recorded and is in the following format: YY-MM-DD hh-mm-ss

  3. The blank space in the dt field between DD and hh must to be substituted with a %20 in a temporal filtered request

    Example: if the chosen dt is: 2019-10-16 02:45:00 the string must be included as 2019-10-16%2002:45:00. (note that some code editor software automatically generate the substitution)

  4. If you want to apply multiple filters and conditions as an AND operator you need to use the & concatenator

    Example: http://ws-eswua.rm.ingv.it/scintillation.php/records/wsstation?filter=area,eq,ANTARCTIC&filter=code,sw,dmc
    returns the stations located in the ANTARCTIC wich names starts with dmc

  5. If you want to apply multiple filters and conditions as an OR operator you need to enumerate the different filters

    Example: http://ws-eswua.rm.ingv.it/scintillation.php/records/wsstation?filter1=area,eq,ANTARCTIC&filter2=area,eq,ARCTIC
    returns the stations located in the ANTARCTIC and the ARCTIC area

Matlab and Python examples

MATLAB Example

%% Matlab code for retrieve all the fields/parameters from the last temporal record recorded in the database

clc
close all
clear all

%retrieve the scintillation stations/instruments list
stations='http://ws-eswua.rm.ingv.it/scintillation.php/records/wsstation';
station_list=cell2mat(struct2cell(webread(stations))); %%Matlab structure with the stations/instruments list

%% retrieve the complete set of parameters in the last available time instant

station='lyb0p'; %change the station code for retrieve the parameters from other stations

%identification of the last available record
time_limit=sprintf('http://ws-eswua.rm.ingv.it/scintillation.php/records/ws%s?include=dt&order=dt,desc&size=1',station);
time=webread(time_limit); %last available temporal instant
%retireve the parameters
parameter_link=sprintf('http://ws-eswua.rm.ingv.it/scintillation.php/records/ws%s?filter=dt,eq,%s&order=dt',station,time.records.dt);
parameter_list=webread(parameter_link);
parameter=cell2mat(struct2cell(parameter_list)); %Matlab structure with all the parameters for the chosen instrument

Python Example

### Python code for retrieve all the fields/parameters from the last temporal record recorded in the database

import json
import urllib.request

#retrieve the scintillation stations/instruments list
url='http://ws-eswua.rm.ingv.it/scintillation.php/records/wsstation'
webURL=urllib.request.urlopen(url)
station_list=json.loads(webURL.read())  # station_list is a dictionary with the stations/instruments list

#Retrieve the complete set of parameters in the last available time instant ####

station='lyb0p'  #change the station code for retrieve the parameters from other stations

#identification of the last available record
url =  'http://ws-eswua.rm.ingv.it/scintillation.php/records/ws{}?include=dt&order=dt,desc&size=1'.format(station)
webURL=urllib.request.urlopen(url)
data=json.loads(webURL.read())
time=data["records"][0]["dt"] #last available record

#retireve the parameters
time=time.replace(" ","%20") #blank spaces needs substitution with "%20"
url='http://ws-eswua.rm.ingv.it/scintillation.php/records/ws{}?filter=dt,eq,{}&order=time'.format(station,time)
webURL=urllib.request.urlopen(url)
parameter=json.loads(webURL.read()) # parameter is a dictionary with the stations/instruments list
print(parameter) #print of the parameters

List of returned errors

The following errors may be reported:

Error / HTTPresponse code / Message:
1000 / 404 Not found / Route not found
1001 / 404 Not found / Table not found
1002 / 422 Unprocessable entity / Argument count mismatch
1003 / 404 Not found / Record not found
1004 / 403 Forbidden / Origin is forbidden
1005 / 404 Not found / Column not found
1006 / 409 Conflict / Table already exists
1007 / 409 Conflict / Column already exists
1008 / 422 Unprocessable entity / Cannot read HTTP message
1009 / 409 Conflict / Duplicate key exception
1010 / 409 Conflict / Data integrity violation
1011 / 401 Unauthorized / Authentication required
1012 / 403 Forbidden / Authentication failed
1013 / 422 Unprocessable entity / Input validation failed
1014 / 403 Forbidden / Operation forbidden
1015 / 405 Method not allowed / Operation not supported
1016 / 403 Forbidden / Temporary or permanently blocked
1017 / 403 Forbidden / Bad or missing XSRF token
1018 / 403 Forbidden / Only AJAX requests allowed
1019 / 403 Forbidden / Pagination Forbidden
9999 / 500 Internal server error / Unknown error

Contacts

"mailto:eswua@ingv.it