With the rollout of Water Reporter’s Beta API, our team has been hard at work identifying approaches to make our platform’s data and information as widespread as possible. Now that we are structuring hundreds of thousands of water quality monitoring results from hundreds of volunteer monitoring programs across the nation, we are building creative ways to embed these data into the daily lives of people looking to venture out to river access sites, and learn more about the current water quality near them.
Why we built Water Reporter Assistant v1.0
It’s no secret that water quality monitoring data are scattered across the web in a number of differing formats with varying degrees of discoverability. Even monitoring programs that do have structured and machine-readable data are often presented in siloed web applications that requires a user to know where to look for this information. Our team set out to take advantage of Water Reporter’s API, our vast network of machine-readable data, and the pervasiveness of virtual assistants to build an application that helps members of the general public gain better access to water quality information. Launched in late March 2022, our team has successfully stood up the first version of Water Reporter Assistant, an Alexa Action designed to help members of the general public use Water Reporter data to answer simple questions such as “What watershed am I in?” as well as check the latest swimming conditions at a monitoring site near them. The Water Reporter Assistant Action helps extend the ubiquity of our platform by bringing water quality monitoring results right into your own home. Getting started is as simple as:
- Enabling the Water Reporter Assistant on your Amazon smart device (such as an Echo or an Echo Show 5) or the Amazon mobile application.
- Asking Alexa to open Water Reporter Assistant.
From there the action will walk you through how to get the latest swimming conditions near you or look up a specific point of interest.
Our goal with this service is to make the ease and behavior of looking up water quality conditions as simple and commonplace as checking the daily weather forecast. We get there by connecting as many of the credible data providers as possible with readily adopted technologies that already have the largest market share. In the case of smart speaker users, this constitutes a much larger captive audience than those that go out in search of a web map or discrete web page for this critical information.
Fun fact: The number of active Amazon Alexa users was 46.5 million in 2020.
Affiliation with Swim Guide
Swim Guide is a platform developed by Swim Drink Fish Canada that provides the latest swimming recreation conditions for over 8,000 beaches throughout the world. Many of their affiliates collect routine samples at designated access points, allowing for a highly up-to-date picture of recreational safety based on contact risk associated with local bacteria monitoring standards. Working in collaboration with Swim Guide, our team pulled the index of Swim Guide monitoring locations and connected the Water Reporter Assistant to the Swim Guide API to return the latest swimming condition status that is available on the Swim Guide web and mobile applications.
How we built the Water Reporter Assistant
The Water Reporter Assistant has been designed and developed in a way that is modular and easy to expand upon. Our team relied on a few key APIs. These included Water Reporter, Swim Guide, and a powerful framework known as Voiceflow. Voiceflow handles the necessary intent training, organization for Alexa’s natural language processing (NLP), and deployment to the Amazon Store. We also relied on the Voiceflow service to build a concise conversation design, trigger API calls to Water Reporter and Swim Guide, and parse these data into a concise response to our users’ questions.
In Voiceflow we are able to diagram out all conversation paths created for the assistant application. This is illustrated by the following diagrams demonstrating each intent, or question, a user can prompt the assistant to fulfill.
Launching the Action
A user initiates a conversation with the Water Reporter Assistant by simply uttering the platform name. For example, on Alexa devices, a user says “Alexa, Open Water Reporter Assistant.” Once instantiated, the assistant greets the user and moves to the main menu flow.
Main Menu
The main menu routes the user conversation to a given intent that is listed. To date, we support the following intents:
- What watershed am I in?
- Tell me about the Internet of Water.
- What is Water Reporter?
- Look up beach conditions for a site on Swim Guide.
- Find water quality conditions near me.
Example Command: Find My Watershed
If a user asks a question that matches the Find My Watershed intent, they will be moved to the Watershed intent handler pictured below. The following steps occur to bring back the user’s watershed.
- User is prompted to tell the assistant their full address. They are also able to use any combination or omission combination of city, state, and ZIP code.
- The assistant packages the response from the user and sends a GET request to the Mapbox Geocoding API service, which returns the user’s latitude and longitude.
- https://api.mapbox.com/geocoding/v5/mapbox.places/{user_location}.json?access_token={mapboxtoken}
- The user’s latitude and longitude are sent via GET request to Water Reporter’s watershed reference endpoint.
- https://api.waterreporter.org/watersheds/intersect?access_token={WR Token}&lng={user_longitude}&lat={user_latitude}
- Assistant reads back the HUC12 name that is georeferenced based off of the user’s geo-coded location. Our base dataset for watershed reference is the HUC12 catchment provided by the NHD+ dataset.
Example Command: Look up Swim Guide beach conditions from a known site
Under this intent, a user can ask for swimming conditions based on Swim Guide. They are required to have some idea of the site name they are interested in discovering. For example “Anacostia River” or “James River.” The more specificity provided to the assistant, the better it will be able to look up and return a more accurate match to the monitoring site of interest. For example: Williamsport Park is an exact location in Swim Guide and if uttered the same way by the user will return the exact site. Steps for looking up swimming conditions are as follows:
- Assistant will ask the user for a beach and capture the utterance as a variable for lookup.
- Assistant will repeat back the location and ask for confirmation. Upon confirmation the assistant looks up and string matches the Swim Guide Site utterance to an index of Swim Guide sites stored here.
- The GET request will return the swim guide site ID and the assistant repeats back the matched Swim Guide site for confirmation by the user.
- Once the Swim Guide site is matched and confirmed to the user utterance, the Swim Guide ID is sent to the Swim Guide API via GET request to return the latest swimming conditions.
https://www.theswimguide.org/api/beach/?format=json&id={sg_id} - Results are analyzed and mapped to the appropriate Swim Guide rating as follows:
3 — Met water quality standards less than 60% of the time
2 — Passed water quality tests 60–95% of the time
1 — Passed water quality tests at least 95% of the time
0 — No data available - Results are read back to the user by the assistant and the user has the option to learn more about the site, look up another site, or exit the intent.
Example Command: Look up Swim Guide Beach Conditions from my Location
Similar to the Find My Watershed Intent, a user can return Swim Guide results for stations closest to them. This is done in a series of steps similar to the Find My Watershed Intent and Look up Swim Guide Beach Conditions from a Known Location.
- User is prompted to tell the assistant their full address. They are also able to use any combination or omission combination of city, state, and ZIP code.
- The assistant packages the response from the user and sends a GET request to the Mapbox Geocoding API service, which returns the user’s latitude and longitude.
https://api.mapbox.com/geocoding/v5/mapbox.places/{user_location}.json?access_token={mapboxtoken} - The user’s latitude and longitude are sent via GET request to Water Reporter’s watershed reference endpoint to return the nearest station. Currently this service is restricted to a dedicated Swim Guide Data Source that indexes all swim guide sites in the Water Reporter API. This is used to get the Swim Guide ID.
https://api.waterreporter.org/stations/nearest?access_token={Water Reporter Token}&lng=-76.609811&lat=39.28499&geo_format=xy&sets=1344 - The Swim Guide ID is sent to the Swim Guide API via GET request to return the latest swimming conditions.
https://www.theswimguide.org/api/beach/?format=json&id={sg_id} - Results are analyzed and mapped to the appropriate Swim Guide rating as follows:
3 — Met water quality standards less than 60% of the time
2 — Passed water quality tests 60–95% of the time
1 — Passed water quality tests at least 95% of the time
0 — No data available - Results are read back to the user by the assistant and the user has the option to learn more about the site, look up another site, or exit the intent.
Informational Intents (What is Internet of Water, Tell Me About Water Reporter, etc.)
Static intents are where a user’s question can be mapped directly to an answer supplied by mostly static information. Contextual questions such as “What is the Internet of Water?” and “Tell me about Water Reporter” are all handled by a simple ask and answer workflow where an intent and sample questions are created and the user is read back precomposed information. The following intents are created as follows:
- User asks a question that matches a static intent.
- Assistant understands intent and responds back with static content.
- User gets routed back to main menu or can end session.
Where are we going from here?
In future releases, our team aims to bring online a number of intents that can help answer watershed health questions. For example, some of our partners, like Blue Water Baltimore and Save the Sound, conduct routine sampling that informs an annual report card grade of the watershed in question. This approach has been developed by the University of Maryland’s Eco-Health Report Card, which establishes explicit grading criteria for a number of parameter indicators that are relevant to a watershed’s geography and historic conditions.
As our team brings on a number of partners that are collecting information based on these protocols, we will be opening up intents that help folks find watershed health information within their region of interest if it exists. Other enhancement ideas that are formulating amongst our team consist of being able to:
- Look up, connect, and donate to watershed organizations in a user’s area.
- Deploy the Water Reporter Assistant to Google Actions.
- Access information on river flow and stage based on USGS’s NWIS monitoring network.
- Save a monitoring site for easy lookup as water quality conditions change.
- Integrate EPA 303d listings for local impairments.
We’re always interested in hearing from you as to what types of intents could be helpful to bring online. If you have ideas, please reach out to us at support@waterreporter.org. We hope you find this service useful and are excited about the possibilities of being able to combine data from many different APIs in order to support the general public in gaining better insight on the health and latest status of their local waterways.
