The wait is finally over! The Commons released a public beta API for the Water Reporter platform. This is a significant step forward in data democratization for the community science water quality movement. In short, the API is a pipeline, allowing water quality data to quickly flow from a streamside sampling event to dynamic applications and data science workflows. With the API, watershed organizations can now create powerful applications for their constituents, seamlessly pulling data for annual reports, analysis, and much more.
If you want to learn more about APIs and technical standards, we recommend reading our previous posts, Why API? and Integrating APIs. These post will help you get acquainted with the Water Reporter API and see some examples of it in action. First, let’s chat briefly about who can take advantage of the API.
Who is the API for?
The Water Reporter API supports two main user types. Primarily, it’s built for watershed organizations looking to amplify their monitoring data beyond the base visualization offerings in Water Reporter. Anyone with experience working in programming languages such as HTML, CSS, Python, R, or Javascript, will be well prepared to interact with the Water Reporter API. Whether you’re building a custom application from your water quality data, or using it for analysis, the API can support your project. We also built the API for us, The Commons development team. The API speeds up internal data analysis workflows and helps our team collaborate effectively when building dynamic applications.
The API opened doors to more efficient development approaches and allowed us to quickly deploy customized visualizations without changing the core product offerings of Water Reporter. Furthermore, as Water Reporter grows we can no longer support the custom needs of everyone in its network. With the API, the imagination of watershed organizations and developers is no longer constrained by the capacities of The Commons to meet their specifications. This approach increases the potential scale, reach, and power of our platforms and those who use them.
What can the API do?
The API creates ample opportunity for Water Reporter users to build applications to fit their big ideas without being hampered by spreadsheet clutter and weekly data downloads. We are excited to share two distinct but equally impactful applications to give you an idea of what the API can do.
James River Watch 2.0
The first application using the API was the James River Watch 2.0 built for the James River Association (JRA). Although Water Reporter’s standard map feature serves dozens of groups, JRA had innovative ideas for a water quality map that couldn’t be met by the base offering. Chiefly, they wanted to integrate NOAA’s Advanced Hydrologic Prediction Service, a platform for stream and gage height data, with their Water Reporter managed data to deliver targeted information to boaters and other recreators on the James. We were able to integrate NOAA and Water Reporter data into a custom application by using the Water Reporter API and NOAA’s programmatically accessible tabular data. Click the link below to check out the current and predicted data for the James River at Westham station.
https://water.weather.gov/ahps2/hydrograph.php?gage=rmdv2&wfo=akq
As for the Water Reporter API, the JRA application uses it for getting station locations, samples, and threshold information, helping to convey station status to the user. Recreationists can quickly answer the question, is it safe to boat or swim? This development approach met JRA’s needs and also allowed us to vet the API’s framework based on a real-world application. By running in parallel tracks, we were able to make crucial changes to the API, shortening development time and improving the end product.
The Water Reporter Station Card
Now released to all Water Reporter subscription holders, the Station Card is a mobile-friendly, map-based application that quickly conveys water quality information to users. Built on the R Shiny framework, the design philosophy was for a lightweight application that required limited clicks for users to drill down to their station and parameter of choice. Using the API, the Station Card relies on a combination of dataset, station and parameter identifiers to construct a series of requests to display the right data at the right time. Thanks to the API and its design, the Station Card will work with any group’s continuous monitoring data in Water Reporter.
The Station Card can also generate its own QR code (as demonstrated in Why API?) to allow for quick sharing and the ability to place physical codes near stations for public use and awareness. Scanning the station’s QR code will bring the latest information on the monitoring site right to the user’s smartphone so they can assess current conditions and even explore historical trends. Further, these station cards possess their own discrete URLs, allowing them to be easily shared to social media platforms like Twitter and Facebook for relaying water quality conditions to your followers.
https://station-card.waterreporter.org.dataset=1343&station=22427¶meter=3073
If you’re on Water Reporter’s Pro plan, you can try the Station Card out now with your own data source. Developers can head to our GitHub repository to fork the code as a base to create and deploy their own customized Station Card. In the coming weeks, we’ll be diving deeper into this application’s code in our webinar planned for March 15th, you can sign up for the webinar here.
The James River Watch and the Station Card are just the beginning of an application ecosystem built on the Water Reporter API. We envision a community of developers creating novel visualizations and improving data workflows with structured water quality data backed by Water Reporter’s easy-to-use data manager. By creating a structured pipeline, data is now accessible for developers to further community science efforts, allowing information to quickly reach constituents and policy makers to inform the public and better the environment.
How does it work?
The best way to get started with the API is to take a look at our documentation. Here, you can see example requests, parameter options, and expected responses. Before diving in, make sure to get an API access_token from the Visualizations section in any of your Water Reporter data sources. It’s a best practice to keep this key secure and secret, treat it like a password.
Now, there are five major request topics, corresponding to the Water Reporter data model — datasets, readings, parameters, stations, and watersheds. Let’s start with datasets as it’s a great entry point for most workflows. The dataset request supports direct requests for a particular dataset_id, or a variety of spatial queries if you don’t know your dataset_id. Protip: to find a dataset_id in Water Reporter, navigate to your dataset, and examine the URL slug. You’ll see something like this:
www.waterreporter.org/community/dashboard/group/131/data-sources/1343/
The 1343 at the end is the dataset identifier. This trick also works for stations and parameter identifiers. From there you can copy and paste your dataset_id into your request parameters. Alternatively, you can send the dataset request a longitude,latitude coordinate pair (the order is important!), or a bounding box to find public datasets that match your spatial query. Important: To access any data in a data source, it needs to be made public first!
Once you have your dataset request put together, you can see the number of stations, samples, parameters, the group name, and other metadata about the dataset. Below is an example of a dataset request and response. We will walk through some other basic requests, but please check out the documentation to see all the available requests and parameters.
Dataset Request
https://api.waterreporter.org/datasets/1343?access_token={YourToken}
Dataset Response
Stations
Another fundamental request group in the API is the station requests. The base station request requires a dataset_id or org_id to retrieve a list of stations with location and metadata including watershed, collected parameters, last sampled date, and much more. In addition to querying based on ID, we also added a feature for identifying stations spatially, just as you would for datasets above. After you have found your station identifiers, you can now easily request readings. Once you have parsed out a list of station identifiers, you can now start retrieving reading data.
Readings
We spent a lot of time workshopping the readings request. We wanted developers and data scientists to have access to all the reading information in Water Reporter like thresholds and labels. This allows developers to build applications without the need to perform resource-heavy tasks like interpreting threshold results. The reading request requires a dataset_id, station_id, and parameter_id. You can also define a start_dateand end_date or min_value and max_value cutoffs, plus other parameters to further tailor your results. Once sent, the typical request and response will look something like this:
Readings Request
https://api.waterreporter.org/readings?station_id=22427¶meter_id=3073&label=1&access_token={YourToken}
Readings Response
Notice that when available, each reading object will contain a color, description, and label from a matching threshold range condition. (Range conditions are configured through the Water Reporter data manager and indicate a sample’s status.) From here, it’s up to you how you display the data. Use it in an interactive chart, train an AI model to predict parameters, the sky's the limit.
Parameters, Watersheds, and Nearest Station
We added a few other requests to help round out the core group, parameters, a single station request, and watersheds. The parameter request is aimed at providing metadata about a parameter. The request requires a station_id and parameter_id. If available, the response will include a chart schema with rules for data display. Responses also contain the parameter’s min, max, and mean values at a particular station. This is a lightweight way to get sample summary information without using the readings request. We also added an additional station request that can take a station_idand return a single station’s meta information. You can also provide a longitude,latitude pair to find the nearest station. If you add the nearest neighbor parameter nn, it will include the four stations nearest to the geographic point specified by the longitude and latitude coordinates. Here is what that request looks like:
https://api.waterreporter.org/stations/nearest?&lng=-76.6083&lat=39.2891&nn=true&access_token={YourToken}
The last request, watersheds, is purely spatial. You send this request a longitude,latitude pair and it will return the 6-, 8-, 10-, and 12-digit hydrologic unit codes for the location. You can use this request in conjunction with the dataset or station request to retrieve data dependent on a watershed from any location.
Caveats
As the current API version is a read-only beta release, please be aware that we’re still working on it. Aspects of this release are unstable and may change without notice as we measure usage, performance, and other feedback. Breaking changes may include modified URL structures and the removal or re-naming of JSON object properties. We recommend that you experiment first and proceed with caution before incorporating API data into production applications. As an early adopter you may receive periodic email updates as we make adjustments and introduce new functionality.
How can we help?
Our team is happy to support our users with general questions regarding API structure, calls, and API documentation. While we want to support our user base with the best possible experience we are allocating time to the development of custom applications outside of scoped and contracted fee-for-service projects. Here are some examples of how we support users taking advantage of the Water Reporter API and what we will not provide coverage for.
We will:
- Answer questions on general API functionality, request formulation, and interpretation of results.
- Share how our existing code packages for Station Cards and vignette examples are run and generally structured.
- Receive feedback for making improvements to the API for future releases.
We will not:
- Build custom applications for projects that are not fully scoped and contracted.
- Debug your application code.
- Create custom endpoints for specific users, organizations, or data requests.
With Water Reporter’s Public API available, the system is better positioned to serve the many diverse needs of our users. The API is one massive step forward that helps our community leverage structured data, adopt FAIR data principles. We now have a key piece of technical infrastructure that enables developers to tap into the volunteer monitoring data routinely collected by our network of over 150 watershed organizations across the country. We can’t wait to see what you build!
If you would like to learn more about the API, please join our webinar March 15th. We will be giving a walkthrough and can answer any questions you might have about getting started with the API. Stay tuned for our future piece about the Station Card and additional examples of the API in action.
