Partner Stories

James River Association

James Riverwatch: Aggregating data to help watershed residents inform recreational water quality conditions.
James River Association

Across the James River, communities convene to swim, fish, and take in the beautiful scenery. At every turn and tributary, James River Association staff and volunteers work together to help everyone enjoy the James. But waterways can be dangerous if not properly understood. To protect and inform all community members, JRA strives to share critical information directly with river goers so that everyone can make safe and informed decisions when heading to the River.

The most critical, up-to-the-minute information regarding James River health is the interactive James River Watch. The James River Watch 2.0 map application is the second iteration of James River Association’s efforts to communicate critical water quality information to its constituents across the watershed. This map is packed with features to help anyone who enjoys spending time by the water make safe decisions about swimming and boating. The map provides up-to-date data from two sources and communicates results via simple, easy to interpret features.

“JRA was happy to partner with The Commons on our new water quality testing map. The new visuals and data displays have made it easier for river users to access the information they need to make informed decisions about where and when to access the river safely. We’re especially excited about the integration of NOAA river level forecasts. This lets folks see what current and past river levels are but also what the river might look like in the next few days, allowing them to plan their trips in advance,” explained Erin Reilly, JRA Staff Scientist.

What questions does the map answer?

Swimmers need to know if the water will make them sick. Is it safe to swim? Volunteers and staff at JRA collect water quality information like E. Coli levels, and temperature. They collect and store their data using Water Reporter, which then connects directly with the River Watch Map. Second, for boaters

Boaters want to know if water levels are safe for boating. Can we launch today? The application serves gauge height and stream flow data from NOAA for both current, and predicted conditions. This technology gives boaters the ability to know before they go, both the current and future water conditions.

Communicated through simple indicators, anyone with an interest in heading to the James can benefit from taking a look at the map. No advanced science degrees or training courses are necessary to interpret the results!

Critical Components to Build a River Health Mapping Application

NOAA Data displays not only past trends but forecasts future river heights to help boaters plan their outdoor adventures.

Choose an analytical system that creates clean visualizations. Built on R Shiny (an ecosystem for creating interactive data oriented visualizations), the map contains a host of custom features to help JRA quickly and clearly communicate water quality data. Upon arrival at the map, users can take in a quick snapshot of the river’s health in the moment. Right away, visitors will get a sense of where to safely head for their next water trip thanks to bright red and green points indicating station health.

Strive for simplicity. On the JRA map, everyone can interpret the data visualized on this map and make informed decisions based on current readings or historical data. Visitors can explore individual stations or toggle between different parameters to learn about specific components of the water quality sampling data. Where available, we include contextual thresholds at the station to help waterway users understand what the parameter values mean in context. Additionally, users can toggle between different temperature units, and select from a list of different parameters depending on the station type.

Gauge chart view on the James River Watch

Sourced by the Water Reporter API

Through the James River Watch application we launched the first ever application using Water Reporter’s API, or Application Programming Interface. The API allows for data to be requested from the Water Reporter server almost instantly and displayed, complete with all threshold and indicator information, on the map. For example, you can request all the station locations from a particular data source, or all the dissolved oxygen readings from a particular station. To the end user, there is minimal difference in the app experience from Water Reporter hosted maps; however, it represents a significant step forward in the ability to share collected water quality data instantaneously with swimmers, boaters, and other recreational users with a custom mapping interface that met the desired specifications the JRA staff. As soon as data is collected and certified in Water Reporter, applications like this one can now request that data and visualize.

Why use an API?

There are a few benefits with this over the typical method of hosting the data directly in the application, such as through an online spreadsheet. First, the API circumvents the process of downloading data and importing it into the application whenever new data becomes available. In the case of the James River Watch monitoring program, they collect and store their data in Water Reporter’s data sources. The system allows them to quickly verify and aggregate data in machine readable formats that can easily be exported and mapped to additional data structures, essentially keeping their data accessible, flexible, and in high demand from all interested parties. Because they have multiple uses for their data, launching an application that doesn’t require an additional data upload step saves the team not only time but also reduces opportunities to introduce errors into the data set.

An example response from the Water Reporter API

Second, the application can use less code, as the API returns nicely formatted data, and only when necessary. For example, when using parameter thresholds, the API can return the color of a particular data value based on its parameter and station as defined in Water Reporter. This means that developers don’t have to replicate threshold logic and functionality in each application — a fantastic way to reduce the burden on developers to create existing wheels and future maintenance.

Building Applications with Water Reporter

True to our name and mission, The Commons looks forward to opening Water Reporter’s API publicly in order to help organizations create more exciting applications that share their monitoring data with an array of end users. The environmental sector’s adoption of software that champions integration across systems can bolster attempts to help more stakeholders connect with and understand critical information about our natural resources. As demonstrated with the production of the James River Watch mapping application, software can spur innovation without requiring continual investment in core products.

Our Analyst and Development teams are working closely to complete all of the requisite steps to publicly open the API for use by more developers. For now, only applications made by The Commons can use the API. We are currently developing a public API so developers and analysts can make their own applications or streamline their data workflows with dynamic data.

If you are interested in joining Beta Testing opportunities using the Water Reporter API to build your own data-driven applications, please get in touch at

James River Association
The mission of the James River Association is to be a guardian of the James River. We provide a voice for the river and take action to promote conservation and responsible stewardship of its natural resources.
Watershed Management
Richmond, VA

Create the Code for Change

Let us show you how The Commons can help propel your efforts to new heights.