The ClimDB and HydroDB database offers several web services in an effort to allow programmatic access to the LTER data contained therein. This document attempts to describe the API's to two of these web services. The two web services described in this document are climdb_agg and climdb_raw.
These web services are built using Perl and Soap. Sample Perl clients and a link to a third party web based client (http://www.soapclient.com/) are supplied. A brief tutorial is also included.
This tutorial will use the get_agg_monthly method of the ClimDB_agg web service for demonstration. get_agg_monthly gives you monthly aggregates for ClimDB and HydroDB data. For example you could get the aggregate values (max,mean,min,or total) for any variable for any site at any station that is participating in the ClimDB and HydroDB program.
The sites, stations, and variables listed above apply to all of the methods described in this document. Variables are all the ClimDB and HydroDB short names;
ATM => DAILY_ATMPRESSURE_MEAN_HPA DEW => DAILY_DEWPOINT_MEAN_C DSCH => DAILY_DISCHARGE_MEAN_LPS GRAD => DAILY_GLOBALRAD_TOTAL_MJM2 PREC => DAILY_PRECIP_TOTAL_MM RH => DAILY_RH_MEAN_PCT RWDI => DAILY_RESWINDDIR_MEAN_DEG RWSP => DAILY_RESWINDSP_MEAN_MSEC SM => DAILY_SOILMOISTURE_MEAN_MPA SMAX => DAILY_SOILTEMP_ABSMAX_C SMEA => DAILY_SOILTEMP_MEAN_C SMIN => DAILY_SOILTEMP_ABSMIN_C SNOW => DAILY_SNOWH20_INSTANT_MM TMAX => DAILY_AIRTEMP_ABSMAX_C TMIN => DAILY_AIRTEMP_ABSMIN_C TMEA => DAILY_AIRTEMP_MEAN_C VAP => DAILY_VAPPRESSURE_MEAN_HPA WDIR => DAILY_WINDDIR_MEAN_DEG WMAX => DAILY_WATERTEMP_ABSMAX_C WMEA => DAILY_WATERTEMP_MEAN_C WMIN => DAILY_WATERTEMP_ABSMIN_C WSP => DAILY_WINDSP_MEAN_MSEC
As new variables are added this list will grow, but keep in mind not all variables are submitted for all sites and stations. If a variable is requested that does not exist for that station or time period no result will be returned, however no error will be indicated.
Please refer to the ClimDB and HydroDB documentation for more information about variables.
As an example, assume you wished to know the average monthly values of maximum air temperature (TMAX) at the primary meteorological station (PRIMET) at the H.J. Andrews LTER site (AND) for the years of 1997 and 1999. NOTE: All values are soap types of string.
A typical soap request would look something like:
<SOAP-ENV:Body>
<namesp1:get_agg_monthly xmlns:namesp1="urn:climdb_agg">
<site_code xsi:type="xsd:string">and</site_code>
<station xsi:type="xsd:string">primet</station>
<variable xsi:type="xsd:string">tmax</variable>
<aggregate_type xsi:type="xsd:string">mean</aggregate_type>
<begin xsi:type="xsd:string">1997</begin>
<end xsi:type="xsd:string">1999</end>
</namesp1:get_agg_monthly>
</SOAP-ENV:Body>
You should expect a response something like:
<SOAP-ENV:Body>
<namesp1:get_agg_monthlyResponse xmlns:namesp1="urn:climdb_agg">
<get_agg_monthly>
<row>
<site_code xsi:type="xsd:string">AND</site_code>
<station xsi:type="xsd:string">PRIMET</station>
<variable xsi:type="xsd:string">TMAX</variable>
<aggregate_type xsi:type="xsd:string">MEAN</aggregate_type>
<year xsi:type="xsd:string">1997</year>
<month xsi:type="xsd:string">1</month>
<value xsi:type="xsd:string">6.7129</value>
</row>
<row>
<site_code xsi:type="xsd:string">AND</site_code>
<station xsi:type="xsd:string">PRIMET</station>
<variable ...
Using a simple Perl client (climdb_agg_client.pl) to access and deserialize this services response.
#!/usr/bin/perl # climdb_agg_client.pl
use SOAP::Lite;
$method = shift;
$soap = SOAP::Lite
->uri("urn:climdb_agg")
->proxy("http://climhy.lternet.edu/wambam/services/climdb_agg_handler.pl";)
->$method(@ARGV);
use Data::Dumper;
print Dumper($soap->valueof('//row'));
Example usage;
perl climdb_agg_client.pl get_agg_monthly AND PRIMET TMAX MEAN 1997 1999
Would yield a result of
$VAR1 = {
'aggregate_type' => 'MEAN',
'station' => 'PRIMET',
'variable' => 'TMAX',
'value' => '6.7129',
'month' => '1',
'site_code' => 'AND',
'year' => '1997'
};
$VAR2 = {
'aggregate_type' => 'MEAN',
'station' => 'PRIMET',
'variable' => 'TMAX',
'value' => '9.8',
'month' => '2',
'site_code' => 'AND',
'year' => '1997'
};
$VAR3 = {
'aggregate_type' => 'MEAN',
'station' => 'PRIMET',
'variable' => 'TMAX'
...
This web service allows remote access to the ClimDB_agg table in the ClimDB and HydroDB database. ClimDB_agg is aggregated data (means, totals, etc.) for various time frames. Three methods are presently offered; get_agg_monthly, get_agg_yearly, and agg_over_all.
The (WSDL) for ClimDB_agg is available. The actual service can be found at http://climhy.lternet.edu/wambam/services/climdb_agg_handler.pl. You may test this service at http://www.soapclient.com/soapclient.
This method gives you monthly aggregates for ClimDB and HydroDB data. The request would consist of site_code, station, variable, aggregate_type, begin, and end. Begin and end are both of the form YYYY-MM-DD. All other variables are as described in the tutorial
The response would consist of site_code, station, variable, aggregate_type, year, month, and value. Month is a value between 1 and 12 where 1 is January, 12 is December.
This method gives you yearly aggregates for ClimDB and HydroDB data. The request would consist of site_code, station, variable, aggregate_type, begin, and end. Begin and end are both years (YYYY). All other variables are as described in the tutorial
The response would consist of site_code, station, variable, aggregate_type, year, and value.
This method gives you monthly values aggregated over all available years for ClimDB and HydroDB data. The request would consist of site_code, station, variable, aggregate_type. All other variables are as described in the tutorial
The response would consist of site_code, station, variable, aggregate_type, month, and value.
This web service allows remote access to the ClimDB_raw table in the ClimDB and HydroDB database. ClimDB_raw is the raw data that was harvested for the various stations. Three methods are presently offered; get_day, last_harvest, and get_variable.
The (WSDL) for ClimDB_raw is available. The actual service can be found at http://climhy.lternet.edu/wambam/services/climdb_raw_handler.pl. You may test this service at http://www.soapclient.com/soapclient.
This method returns all the data for a given research site id on a given day. Date is a soap string following the YYYY-MM-DD format. An example request would be; res_site_id = 47 date = 2000-01-01. An example response would consist of a sequence of variable name, value, and flag. i.e. (TMAX,12,G,TMIN,10,G,TMEA,....)
Given a site, a station, and a ClimDB long name (DAILY_AIRTEMP_MAX_C) , or short name (TMAX). This method will return the day after the last harvest of that variable. An example request would be site = AND, station = PRIMET, variable = TMAX. An example response would be 2004-02-13 (if the last harvest was on the 12).
This method returns the value for a variable between a given date range, i.e. given site = AND, station = PRIMET, variable = TMAX, date = 2000-01-01, date1 = 2000-01-03. The response would consist the variable name, its value, and flag, and the date for the three values on the 1st through the third of January 2000.