DEOS : Web Services and Data Feeds DEOS Technical Note #17 Version 2 Copyright 2006-2008 Center for Climatic Research All material herein is copyright by The Center for Climatic Research Published: October 6 th 2006 Table of Contents Introduction Web Services REST Web Services Web Services Software Interface Retrieving A Network List Retrieving A Station List Retrieving A Data Type List Retrieving Station Data Error Handling Configuration Syndication Feeds; Atom and RSS Atom Feeds RSS Feeds Geographical Encoding Syndication Subscription Files Introduction This document summarizes the available data feeds for the DEOS system. Feeds are divided into syndication feeds of daily and completed monthly data pages, and web service feeds. Web Services The following sections describe the DEOS web service feeds. REST Web Services Web Services Software Interface
The external interface to the web services are described in this section. Retrieving A Network List The following section describes the method implemented to retrieve the list of networks providing web service data. Purpose To provide a list of networks providing data for the DEOS web services. The network names returned by this method are needed in subsequent calls to retrieve station IDs and station data. Options The following are the options understood by this component. Required Parameters The following item is required. key; a valid access key. Example Output The following is an example request and a example output. Example 1. Example Request [URL]ws/REST/V1/getNetworkList?key=abcdef will generate a file similar to that below. Example 2. Example Response <?xml version="1.0" encoding="utf-8"?> <deos:networks xmlns:deos="http://www.deos.udel.edu/ws/ns/" totalnumber="5"> <deos:network number="1" id="7"> <deos:name>deos</deos:name> <deos:description>delaware Environmental Observing System</deos:description> <deos:updatefrequency units="minutes">5</deos:updatefrequency> </deos:network> <deos:network number="2" id="8"> <deos:name>usgs-streamflow</deos:name> <deos:description>us Geological Service Stream-flow Gage</deos:description>
<deos:updatefrequency units="minutes">15</deos:updatefrequency> </deos:network> <deos:network number="3" id="9"> <deos:name>usgs-tidal</deos:name> <deos:description>us Geological Service Tidal Gage</deos:description> <deos:updatefrequency units="minutes">15</deos:updatefrequency> </deos:network> <deos:network number="4" id="11"> <deos:name>ndbc</deos:name> <deos:description>ndbc Buoy Data</deos:description> <deos:updatefrequency units="minutes">60</deos:updatefrequency> </deos:network> <deos:network number="5" id="12"> <deos:name>deldot</deos:name> <deos:description>delaware Department of Transportation Weather Network</deos:description> <deos:updatefrequency units="minutes">10</deos:updatefrequency> </deos:network> </deos:networks> Retrieving A Station List The following section describes the method implemented to retrieve a list of stations from a given network or state, or county within a state. Purpose To provide a list of stations in a given subset providing data for the DEOS web services. The station IDs returned by this method are needed in subsequent calls to retrieve the station data itself. Options The following are the options understood by this component. Required Parameters The following items are required. key; a valid access key. network; the network name as returned from a call to getnetworklist. state; the two-letter state abbreviation. county; the county name in the given state. Either the network, the state or the state and county options must be provided. Example Output The following is an example request and a example output.
Example 3. Example Request [URL]ws/REST/V1/getStationList?key=abcdef&state=PA will generate a file similar to that below. Example 4. Example Response <?xml version="1.0" encoding="utf-8"?> <deos:stations xmlns:deos="http://www.deos.udel.edu/ws/ns/" totalnumber="5"> <deos:station number="1" network="usgs-streamflow"> <deos:id>01481000</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.869727</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.593589</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">0</deos:elevation> <deos:bankfull unittext="meters" unitsymbol="m">0</deos:bankfull> <deos:floodstage unittext="meters" unitsymbol="m">2.7</deos:floodstage> <deos:waterbody>brandywine Creek</deos:waterbody> <deos:county>chester</deos:county> <deos:city>abington</deos:city> <deos:state fullname="pennsylvania">pa</deos:state> <deos:country>usa</deos:country> </deos:station> <deos:station number="2" network="usgs-streamflow"> <deos:id>01479820</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.816671</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.691966</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">0</deos:elevation> <deos:bankfull unittext="meters" unitsymbol="m">1</deos:bankfull> <deos:floodstage unittext="meters" unitsymbol="m">1.1</deos:floodstage> <deos:waterbody>red Clay Creek</deos:waterbody> <deos:county>chester</deos:county> <deos:city>abbottstown</deos:city> <deos:state fullname="pennsylvania">pa</deos:state> <deos:country>usa</deos:country> </deos:station> <deos:station number="3" network="usgs-streamflow"> <deos:id>01478245</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.747515</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.770862</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">0</deos:elevation> <deos:bankfull unittext="meters" unitsymbol="m">0</deos:bankfull> <deos:floodstage unittext="meters" unitsymbol="m">0</deos:floodstage> <deos:waterbody>white Clay Creek</deos:waterbody> <deos:county>chester</deos:county> <deos:city>unknown User</deos:city>
<deos:state fullname="pennsylvania">pa</deos:state> <deos:country>usa</deos:country> </deos:station> <deos:station number="4" network="deos"> <deos:id>dlwg</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.871675</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.682512</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">140.2</deos:elevation> <deos:county>chester</deos:county> <deos:city>kennett Square</deos:city> <deos:state fullname="pennsylvania">pa</deos:state> <deos:country>usa</deos:country> </deos:station> <deos:station number="5" network="deos"> <deos:id>dscr</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.865545</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.846378</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">190.5</deos:elevation> <deos:county>chester</deos:county> <deos:city>west Grove</deos:city> <deos:state fullname="pennsylvania">pa</deos:state> <deos:country>usa</deos:country> </deos:station> </deos:stations> Retrieving A Data Type List The following section describes the method implemented to retrieve the list of data types available. Purpose To provide a list of data types providing data for the DEOS web services. The abbreviations returned by this method are needed in subsequent calls to retrieve station data if the user wishes to reduce the volume of returned data. Options The following are the options understood by this component. Required Parameters The following item is required. key; a valid access key. Optional Parameter
The following items are optional. units; unit schema (default is SI). Example Output The following is an example request and a example output. Example 5. Example Request [URL]ws/REST/V1/getDataTypeList?key=abcdef will generate a file similar to that below. Example 6. Example Response <?xml version="1.0" encoding="utf-8"?> <deos:datatypes xmlns:deos="http://www.deos.udel.edu/ws/ns/" totalnumber="45"> <deos:datatype number="1" id="2"> <deos:name>air Temperature</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>at</deos:abbreviation> <deos:datatype number="2" id="3"> <deos:name>dew Point Temperature</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>dp</deos:abbreviation> <deos:datatype number="3" id="6"> <deos:name>wind Direction</deos:name> <deos:symbol>deg.</deos:symbol> <deos:abbreviation>wd</deos:abbreviation> <deos:datatype number="4" id="12"> <deos:name>heat Index</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>hi</deos:abbreviation> <deos:datatype number="5" id="13"> <deos:name>wind Chill</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>wc</deos:abbreviation> <deos:datatype number="6" id="14"> <deos:name>soil Temperature</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>st</deos:abbreviation> <deos:datatype number="7" id="18">
<deos:name>volumetric Water Content</deos:name> <deos:symbol>%</deos:symbol> <deos:abbreviation>vwc</deos:abbreviation> <deos:datatype number="8" id="22"> <deos:name>visibility</deos:name> <deos:symbol>km</deos:symbol> <deos:abbreviation>vb</deos:abbreviation> <deos:datatype number="9" id="26"> <deos:name>water Temperature</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>wt</deos:abbreviation> <deos:datatype number="10" id="37"> <deos:name>wave Direction (Average)</deos:name> <deos:symbol>deg.</deos:symbol> <deos:abbreviation>wda</deos:abbreviation> <deos:datatype number="11" id="40"> <deos:name>fuel temperature</deos:name> <deos:symbol>deg. C</deos:symbol> <deos:abbreviation>f</deos:abbreviation> <deos:datatype number="12" id="42"> <deos:name>wind Gust Direction</deos:name> <deos:symbol>deg.</deos:symbol> <deos:abbreviation>wgi</deos:abbreviation> <deos:datatype number="13" id="1"> <deos:name>gage Precipitation (60)</deos:name> <deos:abbreviation>rfh</deos:abbreviation> <deos:datatype number="14" id="4"> <deos:name>wind Speed</deos:name> <deos:symbol>m.s-1</deos:symbol> <deos:abbreviation>ws</deos:abbreviation> <deos:datatype number="15" id="7"> <deos:name>barometric Pressure</deos:name> <deos:symbol>mbar</deos:symbol> <deos:abbreviation>bp</deos:abbreviation> <deos:datatype number="16" id="8"> <deos:name>solar Radiation</deos:name> <deos:symbol>w.m-2</deos:symbol> <deos:abbreviation>sr</deos:abbreviation> <deos:datatype number="17" id="9"> <deos:name>wind Gust Speed (5)</deos:name> <deos:symbol>m.s-1</deos:symbol> <deos:abbreviation>wg5</deos:abbreviation> <deos:datatype number="18" id="10"> <deos:name>gage Precipitation (5)</deos:name>
<deos:abbreviation>rf5</deos:abbreviation> <deos:datatype number="19" id="11"> <deos:name>relative humidity</deos:name> <deos:symbol>%</deos:symbol> <deos:abbreviation>rh</deos:abbreviation> <deos:datatype number="20" id="16"> <deos:name>bias-adjusted Gage Precipitation (60)</deos:name> <deos:abbreviation>rha</deos:abbreviation> <deos:datatype number="21" id="17"> <deos:name>bias-adjusted Gage Precipitation (5)</deos:name> <deos:abbreviation>r5a</deos:abbreviation> <deos:datatype number="22" id="19"> <deos:name>snow depth</deos:name> <deos:symbol>cm</deos:symbol> <deos:abbreviation>sd</deos:abbreviation> <deos:datatype number="23" id="20"> <deos:name>radar Precipitation (6)</deos:name> <deos:abbreviation>rr6</deos:abbreviation> <deos:datatype number="24" id="21"> <deos:name>leaf wetness</deos:name> <deos:symbol>%</deos:symbol> <deos:abbreviation>lf</deos:abbreviation> <deos:datatype number="25" id="23"> <deos:name>gage Height</deos:name> <deos:symbol>m</deos:symbol> <deos:abbreviation>gh</deos:abbreviation> <deos:datatype number="26" id="24"> <deos:name>precip (daily)</deos:name> <deos:abbreviation>rfd</deos:abbreviation> <deos:datatype number="27" id="25"> <deos:name>discharge</deos:name> <deos:symbol>m3.s-1</deos:symbol> <deos:abbreviation>dsc</deos:abbreviation> <deos:datatype number="28" id="27"> <deos:name>stream Velocity</deos:name> <deos:symbol>m.s-1</deos:symbol> <deos:abbreviation>sv</deos:abbreviation> <deos:datatype number="29" id="28"> <deos:name>gage Precipitation (15)</deos:name> <deos:abbreviation>rfq</deos:abbreviation>
<deos:datatype number="30" id="29"> <deos:name>ph</deos:name> <deos:symbol> </deos:symbol> <deos:abbreviation>ph</deos:abbreviation> <deos:datatype number="31" id="30"> <deos:name>conductance</deos:name> <deos:symbol>micros.l-1</deos:symbol> <deos:abbreviation>sc</deos:abbreviation> <deos:datatype number="32" id="31"> <deos:name>dissolved Oxygen %saturation</deos:name> <deos:symbol>%</deos:symbol> <deos:abbreviation>po2</deos:abbreviation> <deos:datatype number="33" id="32"> <deos:name>dissolved Oxygen Volume</deos:name> <deos:symbol>mg.l-1</deos:symbol> <deos:abbreviation>do2</deos:abbreviation> <deos:datatype number="34" id="33"> <deos:name>turbidity (BB)</deos:name> <deos:symbol>ntu</deos:symbol> <deos:abbreviation>tbb</deos:abbreviation> <deos:datatype number="35" id="34"> <deos:name>wave Height</deos:name> <deos:symbol>m</deos:symbol> <deos:abbreviation>wh</deos:abbreviation> <deos:datatype number="36" id="35"> <deos:name>wave Period (Dominant)</deos:name> <deos:symbol>s</deos:symbol> <deos:abbreviation>wpd</deos:abbreviation> <deos:datatype number="37" id="36"> <deos:name>wave Period (Average)</deos:name> <deos:symbol>s</deos:symbol> <deos:abbreviation>wpa</deos:abbreviation> <deos:datatype number="38" id="38"> <deos:name>barometric Pressure Trend</deos:name> <deos:symbol>mbar.hr-1</deos:symbol> <deos:abbreviation>bpt</deos:abbreviation> <deos:datatype number="39" id="39"> <deos:name>tide (Deviation)</deos:name> <deos:symbol>m</deos:symbol> <deos:abbreviation>td</deos:abbreviation> <deos:datatype number="40" id="41"> <deos:name>fuel moisture</deos:name> <deos:symbol>%</deos:symbol> <deos:abbreviation>fm</deos:abbreviation> <deos:datatype number="41" id="93"> <deos:name>wind Gust Speed (10)</deos:name>
<deos:symbol>m.s-1</deos:symbol> <deos:abbreviation>wgx</deos:abbreviation> <deos:datatype number="42" id="94"> <deos:name>gage Precipitation (10)</deos:name> <deos:abbreviation>rfx</deos:abbreviation> <deos:datatype number="43" id="95"> <deos:name>turbidity (MC)</deos:name> <deos:symbol>fnu</deos:symbol> <deos:abbreviation>tm</deos:abbreviation> <deos:datatype number="44" id="112"> <deos:name>water Level</deos:name> <deos:symbol>m</deos:symbol> <deos:abbreviation>wl</deos:abbreviation> <deos:datatype number="45" id="113"> <deos:name>mean Daily Water Level</deos:name> <deos:symbol>m</deos:symbol> <deos:abbreviation>wld</deos:abbreviation> </deos:datatypes> Retrieving Station Data The following section describes the method implemented to retrieve the meteorological data of a given station via the web service. Purpose To provide a set of station meteorological and other data for the DEOS web services. Options The following are the options understood by this component. Required Parameters The following items are required. key; a valid access key. station; the station name. network; the network name. Optional Parameters The following items are optional.
datatypes; the list if data type abbreviations to use. The default is to retrieve data for all data types. time; the date and time for the data retrieval. The default is the current date and time. [1] span; the time span (in minutes) for the data retrieval. The default is one hour. Spans over 24 hours are not permitted. If a span of zero is requested, then any time parameter is ignored and the most recent data for all relevant data types are returned. N.B. The date of this data may not be recent, so the user needs to check on the data currency. units; either SI (default) or English tz; the time zone that the data will be generated for. The default is UTC (GMT). [2] Example Output The following is an example request and a example output. Example 7. Example Request [URL]ws/REST/V1/getStationData?key=abcdef&station=DPTR&network=DEOS&tz=EST5ED T&span=5&time=2006/10/25 17:00:00 will generate a file similar to that below. Example 8. Example Response <?xml version="1.0" encoding="utf-8"?> <deos:data xmlns:deos="http://www.deos.udel.edu/ws/ns/"> <deos:station number="1" name="dptr" network="deos"> <deos:stationmetadata> <deos:id>2301</deos:id> <deos:latitude unittext="degrees" unitsymbol="°">39.773871</deos:latitude> <deos:longitude unittext="degrees" unitsymbol="°">- 75.541966</deos:longitude> <deos:elevation unittext="meters" unitsymbol="m">82.3</deos:elevation> <deos:country>usa</deos:country> </deos:stationmetadata> <deos:stationdata total="11"> <deos:dataitem number="1" datatype="2"> <deos:unitdescription>air Temperature</deos:unitDescription> <deos:value unitsymbol="deg. C">10.3</deos:value> <deos:dataitem number="2" datatype="3"> <deos:unitdescription>dew Point Temperature</deos:unitDescription> <deos:value unitsymbol="deg. C">-1</deos:value>
<deos:dataitem number="3" datatype="4"> <deos:unitdescription>wind Speed</deos:unitDescription> <deos:value unitsymbol="m.s-1">5.5</deos:value> <deos:dataitem number="4" datatype="6"> <deos:unitdescription>wind Direction</deos:unitDescription> <deos:value unitsymbol="deg.">297.6</deos:value> <deos:dataitem number="5" datatype="7"> <deos:unitdescription>barometric Pressure</deos:unitDescription> <deos:value unitsymbol="mbar">1016</deos:value> <deos:dataitem number="6" datatype="8"> <deos:unitdescription>solar Radiation</deos:unitDescription> <deos:value unitsymbol="w.m-2">297</deos:value> <deos:dataitem number="7" datatype="9"> <deos:unitdescription>wind Gust Speed (5)</deos:unitDescription> <deos:value unitsymbol="m.s-1">7.8</deos:value> <deos:supplementarytime unixtimestamp="1161795420">2006/10/25 12:57:00 EDT</deos:supplementaryTime> <deos:dataitem number="8" datatype="10"> <deos:unitdescription>gage Precipitation (5)</deos:unitDescription> <deos:value unitsymbol="mm">0</deos:value> <deos:dataitem number="9" datatype="11"> <deos:unitdescription>relative humidity</deos:unitdescription> <deos:value unitsymbol="%">45</deos:value> <deos:dataitem number="10" datatype="15"> <deos:unitdescription>voltage</deos:unitdescription> <deos:value unitsymbol="v">13.52</deos:value> <deos:dataitem number="11" datatype="18"> <deos:unitdescription>volumetric Water Content</deos:unitDescription>
<deos:value unitsymbol="%">34.2</deos:value> </deos:stationdata> </deos:station> </deos:data> Error Handling The following section describes the output in the case of a processing error. Example Output The following is an example request and a error example output. Example 9. Example Request [URL]ws/REST/V1/getNetworkList?key=badkey will generate a file similar to that below. Example 10. Example Error Response <?xml version="1.0" encoding="utf-8"?> <deos:networks xmlns:deos="http://www.deos.udel.edu/ws/ns/" totalnumber="0"> <deos:errors totalnumber="1"> <deos:error number="1"> <deos:code>deos.keyinvalid</deos:code> <deos:message>the provided key is not valid.</deos:message> </deos:error> </deos:errors> </deos:networks> Configuration The following list of parameters are the configurable items for the web services component and can be found in the ofnidb.jnk file in the odd-divas directory. gdebug: this is the setting that allows more output to be generated, assisting fixing problems. grecordmax: this is the maximum number of data items that can be retrieved. Care must be exercised when setting this too large values. Other limits from PHP, both memory and execution time may occur. Syndication Feeds; Atom and RSS
The following sections describe the DEOS syndicated data feeds. Atom Feeds The DEOS Atom feeds are based on Atom Version 1.0. RSS Feeds The DEOS RSS (Real Simple Syndication) feeds are based on RSS Version 2.0. Geographical Encoding Both the Atom and RSS feeds utilize GeoRSS encodings to specify the geographical location of the station providing the data. Syndication Subscription Files It is expected that the web developer of the site hosting the data feeds will provide a summary page of all the feeds to allow subscribers easy access to all the available feeds. This section summarizes where the data feed files originate for the benefit of the web developer. The daily feeds files are accessible as described in the following example: Example 11. Daily Feed Access [DF_BASE_URI]/[feed type]/[network]/[station]/daily.xml The completed monthly data feeds are accessible as described in the following example: Example 12. Monthly Feed Access [DF_BASE_URI]/[feed type]/[network]/[station]/monthly-[unit type].xml The options are as follows: DF_BASE_URI: is set in the DCF and must match the DF_BASE_DIR setting, relative to the web site root. feed type: Either Atom or rss. network: the name of the network. station: the name of the station. unit type: either SI or english.
[1] The date and time string must meet the guidelines presented here. [2] The time zone string must be from the list provided here.