|
|
|
Madrigal web services | Doc home | Madrigal home |
The following section gives a tutorial on the various Madrigal web services in the context of the Madrigal data model. This section is intended to help someone writing their own API to interface with Madrigal. If you simply want to use the existing Matlab or python API's, you can skip ahead to the next sections.
The web services are organized in the same way as the Madrigal data model, from Instrument at the highest level, down to the level of data values. See the Remote data access programming reference manual for complete descriptions of all the Madrigal web services.
Madrigal web services are built using the following cgi scripts:
The top layer of the Madrigal data model is the instrument. All data in Madrigal is associated with one and only one instrument. Since Madrigal is ground-based focused, an instrument has a particular location associated with it. The following information is available for each instrument:
To access Instrument metadata, call url:
<any Madrigal server>/getInstrumentsService.py
For example:
http://www.haystack.mit.edu/cgi-bin/madrigal/getInstrumentsService.py
will return comma-delimited lines with the six fields above, one for each instrument.
In the madrigal database system, the data are organized by experiment. An experiment consists of data from a single instrument covering a limited period of time, and, as a rule, is meant to address a particular scientific goal. The following information is available for each instrument:
To access Experiment metadata for a given instrument and time range, call url:
<any Madrigal server>/getExperimentsService.py?code=<instrument code>&startyear=<year>&startmonth=<month> &startday=<day>&starthour=<hour>&startmin=<min>&startsec=<sec>&endyear=<year>&endmonth=<month>&endday=<day> &endhour=<hour>&endmin=<min>&endsec=<sec>&local=<1 or 0>
Example: To get all data from instrument Millstone Hill ISR (code=30) during 1998 for all Madrigal servers, url is:
http://www.haystack.mit.edu/cgi-bin/madrigal/getExperimentsService.py?code=30&startyear=1998 &startmonth=1&startday=1&starthour=0&startmin=0&startsec=0&endyear=1999&endmonth=1&endday=1 &endhour=0&endmin=0&endsec=0&local=0
which will return comma-delimited lines with the 20 fields above, one for each experiment.
The data from a given experiment is stored in one or more experiment files. The format of these files is the Cedar database format, but this is not important since this data is exposed remotely in an ascii format. Note that once we are at the level of experiment files, we need to request the file from the right Madrigal server. The name of correct Madrigal server is given by the experiment.url field, with everything after the "madtoc" indicator replaced by the correct cgi script name (see example below). The following information is available for each experiment file:
To access Experiment file metadata for a given experiment, call url:
<the correct Madrigal server>/getExperimentFilesService.py?id=<experiment id>
where experiment id was returned by getExperimentsService.py, and the correct Madrigal server is experiment.url, truncated before /madtoc/.
Example: to get Experiment File from experiment id = 20001996,experiment url = http://www.eiscat.se/madrigal/cgi-bin/madtoc/1998/mlh/20jan98:
http://www.eiscat.se/madrigal/cgi-bin/getExperimentFilesService.py?id=20001996
which will return comma-delimited lines with the 6 fields above, one for each experiment file. (Note: this experiment id may change in the future).
Any given file is made up a series of records holding parameters. The next cgi scripts returns information about the parameters contained in a given file. The following information is available about the parameters in any experiment file:
Note that Madrigal will automatically derive a large number of parameters such as Kp and Magnetic field strength that aren't in the file itself; from the user's point of view these derived parameters appear to be in the file. This is the meaning of column 5: isMeasured. 1 means the data comes from the file itself, 0 means it was derived. To access the parameter information for a given file, call url:
<the correct Madrigal server>/getParametersService.py?filename=<full filename>
where full filename was returned by getExperimentFilesService.py in column 1, and the correct Madrigal server is again required.
Example: to get the parameters for file mil980120g.001 from the eiscat server:
http://www.eiscat.se/madrigal/cgi-bin/getParametersService.py?filename=/usr/local/madroot/experiments/1998/mlh/20jan98/mil980120g.001
which will return backslash-delimited lines with the 7 fields above, one for each parameter. Note that backslash is used as a delimiter since commas appear in the parameter descriptions.
To access the parameters for a given file, call url:
<the correct Madrigal server>/isprintService.py?file=<full filename> &parms=<plus-separated parameter mnemonics>
where the filename is the same as in getParametersService.py and parameter mnemonics were returned by getParametersService.py.
Example: To get parameters year, month, day, hour, min, sec, gdlat, glon, gdalt, and ti (temperature ions) from the file /usr/local/madroot/experiments/1998/mlh/20jan98/mil980120g.001, we call url:
http://www.eiscat.se/madrigal/cgi-bin/isprintService.py?file=/usr/local/madroot/experiments/1998/mlh/20jan98/mil980120g.001 &parms=year+month+day+hour+min+sec+gdlat+glon+gdalt+ti
This will return 11 columns for the 11 requested parameters in the same order as they were requested, with one line for each measurement.
Madrigal can derive data, as well as display data from existing experiment files. For example, Madrigal can derive MSIS neutral atmosphere parameters for any time and location. To access this derivation engine, call the madCalculatorService.py script. This script allows you to derive one or more parameters for a range of locations at a single time. If you need data at more than one time, simply call this script repeatedly. If you need data that is independent of position (such as Kp) for more than one time, use the madTimeCalculator.py service. Note that this service does not provide measured data from Madrigal data files; use isprintService.py for that.
It has the following input arguments:
year - int (required)
month - int (required)
day - int (required)
hour - int (required)
min - int (required)
sec - int (required)
startLat - Starting geodetic latitude, -90 to 90 (required)
endLat - Ending geodetic latitude, -90 to 90 (required)
stepLat - Latitude step (0.1 to 90) (required)
startLong - Starting geodetic longitude, -180 to 180 (required)
endLong - Ending geodetic longitude, -180 to 180 (required)
stepLong - Longitude step (0.1 to 180) (required)
startAlt - Starting geodetic altitude, >= 0 (required)
endAlt - Ending geodetic altitude, > 0 (required)
stepAlt - Altitude step (>= 0.1) (required)
parms - comma delimited string of Madrigal parameters desired (required)
The script returns comma-delimited data, one line for each combination of lat, long, and alt, with the following fields:
Example: To get the three components on the magnetic field (BN, BE, BD) at midnight 1/1/2000 at latitude = 20, longitude = 40, and altitudes of 100 to 1000 km in steps of 100 km, use:
http://madrigal.haystack.mit.edu/cgi-bin/madrigal/madCalculatorService.py?year=2000&month=1&day=1& hour=0&min=0&sec=0&startLat=20&endLat=20&stepLat=1&startLong=40&endLong=40&stepLong=1& startAlt=100&endAlt=1000&stepAlt=100&parms=bn,be,bd
This will return the following six columns: latitude, longitude, altitude, BN, BE, BD:
20.00 40.00 100.00 3.33234e-05 1.23289e-06 1.69326e-05 20.00 40.00 200.00 3.16261e-05 1.07499e-06 1.60124e-05 20.00 40.00 300.00 3.00451e-05 9.33461e-07 1.51637e-05 20.00 40.00 400.00 2.85703e-05 8.06412e-07 1.43793e-05 20.00 40.00 500.00 2.71927e-05 6.92227e-07 1.36528e-05 20.00 40.00 600.00 2.59044e-05 5.89497e-07 1.29786e-05 20.00 40.00 700.00 2.46981e-05 4.96988e-07 1.23518e-05 20.00 40.00 800.00 2.35672e-05 4.13624e-07 1.17679e-05 20.00 40.00 900.00 2.25059e-05 3.38453e-07 1.12232e-05 20.00 40.00 1000.00 2.15087e-05 2.70640e-07 1.07142e-05
The madTimeCalculatorService.py service is similar to the madCalculatorService.py service, but it calculates values for a series of times. However, it is limited to parameters that are independent of position, such as Kp.
Input cgi arguments:
Returns comma-delimited data, one line for time, with the following fields:
Example: To get Kp and F10.7 for each 3 hour interval on Jan. 1, 2000, use:
http://grail.haystack.mit.edu/cgi-bin/madrigal/madTimeCalculatorService.py? startyear=2000&startmonth=1&startday=1&starthour=0 &startmin=0&startsec=0&endyear=2000&endmonth=1& endday=1&endhour=23&endmin=59&endsec=59&stephours=1&parms=kp,f10.7
This will return the following eight columns: year, month, day, hour, min, sec, kp, f10.7:
2000 1 1 0 0 0 5.30 1.29900e-20 2000 1 1 3 0 0 4.70 1.29900e-20 2000 1 1 6 0 0 4.00 1.29900e-20 2000 1 1 9 0 0 3.30 1.29900e-20 2000 1 1 12 0 0 4.30 1.29900e-20 2000 1 1 15 0 0 3.00 1.29900e-20 2000 1 1 18 0 0 4.30 1.29900e-20 2000 1 1 21 0 0 3.70 1.29900e-20
The radarToGeodeticService.py script converts a radar position (azimuth, elevation, and range) to a geodetic location. Use geodeticToRadarService.py to go in the other direction.
Input cgi arguments:
Returns comma-delimited data, one line for point in lists:
Example: To get the geodetic point at azimuth=100, elevation=45,55, and 65, and range=1000 km from the Millstone Hill IS Radar at latitude=42.619, longitude=288.51, and altitude=0.146, use:
http://madrigal.haystack.mit.edu/cgi-bin/madrigal/radarToGeodeticService.py? slatgd=42.619&slon=288.51&saltgd=0.146&az=100,100,100&el=45,55,65&range=1000,1000,1000
which will return the geodetic latitude, longitude, and altitude of those three radar positions:
41.361338,-64.012651,742.038442 41.645771,-65.488196,841.794521 41.932738,-67.098375,918.473216
The geodeticToRadarService.py script converts a a geodetic location to radar position (azimuth, elevation, and range) . Use radarToGeodeticService.py to go the other way.
Input cgi arguments:
Returns comma-delimited data, one line for point in lists:
Example: To get the radar location at gdlat=42, glon=290, and gdalt=1000, 2000, and 3000 km from the Millstone Hill IS Radar at latitude=42.619, longitude=288.51, and altitude=0.146, use:
http://madrigal.haystack.mit.edu/cgi-bin/madrigal/geodeticToRadarService.py? slatgd=42.619&slon=288.51&saltgd=0.146&gdlat=42,42,42&glon=290,290,290&gdalt=1000,2000,3000
which will return the azimuth, elevation, and range of those three geodetic positions:
117.704418,80.825093,1011.252383 116.906481,84.802395,2006.351074 116.270492,86.139493,3004.705956
The traceMagneticFieldService.py service allows you to trace magnetic field lines using either the IGRF model or the Tysganenko models.
Input cgi arguments:
The following parameters depend on inputType:
Length of all three lists must be the same
Returns comma-delimited data, one line for point in in lists:
Example: To get the position of the magnetic field line when it crosses 1000 km in the northern hemisphere at midnight 1/1/2004, using the Tysganenko model, with starting points given in GSM and output in geodetic, use:
http://www.haystack.mit.edu/cgi-bin/madrigal/traceMagneticFieldService.py? model=0&stopAlt=1000.000000&year=2004&month=1&day=1&hour=0&min=0&sec=0& in1=0.269000,0.300000,0.300000,0.300000,0.300000& in2=0.583000,0.600000,0.600000,0.600000,0.600000& in3=-0.959870,-10.000000,-1.000000,-10.000000,-1.000000&inputType=1&outputType=0&qualifier=1
which in this case returns a comma-separated list of geodetic altitude, latitude, and longitude:
missing,missing,missing 1000.000000,74.695086,102.027236 1000.000000,19.026779,129.445239 1000.000000,74.695086,102.027236 1000.000000,19.026779,129.445239
Finally, one other tcl cgi script should be included as part of the web services API: getMetadata. This cgi script allows direct downloading of any of the 10 metadata files . In general, all information needed from Madrigal should be available in an easier-to-use form from the python cgi scripts above. However, there is some information in the metadata that is not available through those scripts, and if that information is ever needed, a user can call getMetadata to download the metadata file itself as follows:
cgiUrl /getMetadata?fileType= value
where value is
|
|
|
Madrigal web services | Doc home | Madrigal home |