The U.S. Geological Survey publishes many datasets in a RDB format. RDB is basically a tab delimited file of data with structured comments embedded in them which, when parsed, provide valuable metadata. Here is an example of a simple RDB file.
# ------------------------------------------- # Documentation lines. These describe and # identify the rdb file contents. # ------------------------------------------- NAME COUNT TYP AMT OTHER RIGHT 6s 5n 3s 5n 8s 8s Bill 44 A 133 Another This John 44 23 One Is Gary 77 77 Here On Mar 77 B 244 And The Greg 77 D 1111 So Right
As you can see, comment lines begin with a # followed by a space. Comments are followed by a header line where the columns of data are named. The header line is followed by a field type/length information, typically indicating the maximum size in characters that the field will contain followed by "s" or "n" indicating the field contains either a string or a number. With this basic information it is fairly straightforward for a programmer to write a program to read the data then use it for another purpose.
Unit values are time-series measurements. The USGS has many automated gages deployed in the field that regularly measure water and in some cases weather data. Each measurement is a unit value, i.e. a regular and periodic measurement associated with a time and location. USGS unit values are popular because recent streamflow conditions measuring important information like water levels in lake, streams and rivers are of great national interest. Unit values are more often referred to as "instantaneous values". Thousands of RDB files are hosted by the USGS Water Data for the Nation (NWISWeb) site. These files are of great interest and are frequently downloaded by the public.
The PHP RDB Unit Values Class is a PHP class library designed to make it easier to consume unit value RDB files provided by the USGS Water Data for the Nation (NWISWeb) site. On its most basic level it transforms the data and metadata in these files into more useful, 21st century formats. Specifically it can read a unit values RDB file and provide its output in either Extensible Markup Language (XML) or in Javascript Object Notation (JSON). The class provides filtering and sorting options to make it easier to grab data of interest. For example, you may be only interested in the most recent streamflow measurement. The class supports this.
Essentially the PHP RDB class acts as a proxy.
To get your feet wet, try these two examples. I will explain how they work in a bit.
As you can infer, the class requires PHP. PHP is a popular scripting language typically found on web servers. If you have a publicly accessible web server, it likely already has PHP on it. Most people who use the class will want to re-serve the USGS water data on their own web site, perhaps mixing it with data or graphics of their own. However, PHP can also be installed on most desktop computers. If you are developing an application, you may prefer to install PHP on your desktop computer and "move it to production" on a real web server when ready to deploy.
PHP is an easy language to learn and fortunately you do not need to be a PHP expert to write programs with the class. If you are comfortable with Java, C, C++ or many other block structured languages, PHP will seem easy. Unfortunately to use the class you probably will have to write a little PHP. This is because the PHP class is just a class, not an object. A class is like a blueprint to a car, rather than the actual car itself. So you will need a PHP program that creates a PHP RDB Unit Values object. It's pretty simple, but of course you will probably need to read some input and write some output with your program too. Here is a short program that demonstrates a simple use of the class. (This is the actual server side script for the second example above.)
<?php
include 'rdb.php'; // This indicates where to find the class to the program. // Get the site number from the client $my_site = htmlspecialchars($_GET['site']); // Construct the URL $my_url = 'http://waterdata.usgs.gov/nwis/uv?cb_00060=on&format=rdb&period=1&site_no=' . $my_site;
$my_rdb = new rdb($my_url); // Fetch this RDB file and load it into an object $my_rdb->show_columns = array(2,3); // Only interested in columns 3 and 4 of the output. Arrays start with 0 in PHP $my_rdb->show_order = array(SORT_NUMBER, SORT_NUMBER); // Sort column 3 as a number, then sort by column 4 as a number // Finally, output as JSON to the client $my_rdb->outputJSON(TRUE, TRUE, TRUE); // Output the data as XML
?>