diff --git a/README.md b/README.md
index 8374513..f4fee6b 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,44 @@
 
 ## Overview
 
-This repository contains scripts for the `command_line` integration in HomeAssistant.
+This repository contains scripts to integrate Davis Weatherlink and USGS water data
+into HomeAssistant.
 The scripts access external resources, typically via the Internet, and print various
 values as elements of `data` in a JSON output. The output can be captured by a
 HomeAssistant "sensor" and then included into individual sensors.
 
 Scripts include:
 
+### Command line
 - `davisconditions.py`: weather conditions from a [Davis WeatherLink Live](https://www.davisinstruments.com/pages/weatherlink-live) (local network)
 - `riverconditions.py`: river conditions from the [USGS National Water Information System](https://waterdata.usgs.gov/)
 
-## Installation
+### REST
+- `waterconditions.py`: simple Python web server that gathers data from the [USGS National Water Information System](https://waterdata.usgs.gov/) and makes it available via a JSON-encoded REST interface.
+
+## Using the REST scripts
+
+The scripts can be installed on any machine visible to the HomeAssistant server.
+The only non-standard Python library is `requests`, which is something you should
+make available in your standard installation anyway.
+
+The script needs to be executable (`chmod 755 waterconditions.py`), but has no other
+special requirements.
+
+### Water conditions
+
+`waterconditions.py` queries the [USGS National Water Information System](https://waterdata.usgs.gov/) for
+current conditions of US lakes (including reservoirs) and rivers. URLs are of the form
+`https://_my.server.address_:8999/river-01234567`, where the URL path is either `lake` or
+`river` followed by the 8 digit USGS identifier for the water sensor.
+You can find the 8 digit identifier using the [USGS web page](https://waterdata.usgs.gov/).
+
+The script only sends an actual query for each site at most every `request_interval` (default 599) seconds.
+It returns a cached value if `waterconditions.py` is queried more frequently; this avoids overloading
+the USGS server, and prevents them from throttling your queries. You may change this value in the script
+if you want; I'd recommend no less than 599, but longer may be OK if you need less frequent updates.
+
+## Using the command line scripts
 
 The scripts can be installed into any directory that HomeAssistant can run scripts from.
 Make sure they're executable (*e.g.*, `chmod 755 riverconditions.py`).
@@ -28,8 +55,6 @@ The only non-standard package that's needed is `requests`, though you shouldn't
 install it if you're using HomeAssistant's `python3` executable, since HomeAssistant already
 installs `requests`.
 
-## Usage
-
 ### Running the scripts
 
 Each script takes a single argument that specifies the resource being accessed. `riverconditions.py`