The ClimDB and HydroDB Web Service API


Description

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.


Tutorial

ClimDB and HydroDB

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.

Soap

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'
		  ...


ClimDB_agg

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.

Methods

get_agg_monthly

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.

get_agg_yearly

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.

agg_over_all

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.


ClimDB_raw

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.

Methods

get_day

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,....)

last_harvest

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).

get_variable

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.