Data sharing and API how-to

Last updated 17.01.2025 by Kat Kavanagh

We have designed this data platform to help groups collect and manage their community's water quality data, and provide basic visualization. However, we know that to tell the full story of the data, you'll need to be able to access data in its raw format. For most people, being able to download the data from each dataset is sufficient. You'll see this link on each dataset.

For more advanced partners and organizations, Water Rangers' API can be used to pull data for visualization and to combine with other data sources. It's also a way to automatically share data in larger datasets (for example, suitable Canadian groups will have their data automatically shared with DataStream and in the UK through CaSTCo).

Please note that we restrict access to the API in order to ensure that our servers are not overloaded. We are a small non-profit organization. If you plan to use our API regularly, please consider contributing to our server costs!

---

Data structure

Water Rangers' platform is built to provide enough structure to provide good quality meta data and high data quality for each dataset, but also the flexibility for each group to define their customized protocol. While we encourage people to use Water Rangers' testkit protocols, groups are free to use the tools to define their own.

---

Organization

An Organization represents the owner of one or many Datasets. Organizations can have multiple Datasets, users, and admin users. Organizations do not have to be formal-- a single person looking to collect data could create their own. We encourage communities to work together as it's more sustainable and trustworthy.

Organization data: Organization name*, short description, long description, primary country, state/province/county, nearest city, email, phone, website, logo, region, datasets, users, and admin users.

---

Dataset

A Dataset is data collected using a specific protocol for a specific purpose and is defined by a region. You should specify things like testing equipment, protocols, frequency, data standards, region of interest, etc. Users can be part of multiple Datasets, but will have to set their primary dataset in order to contribute to that dataset.

Dataset data: Dataset name*, description, start date, intended audience, intended data use (choice), dataset purpose (choice), monitoring frequency (choice), frequency details, standards guidelines, customizable form, region of interest, share with DataStream (see data sharing below), users and admin users.

---

Form parameters

Each dataset has their own customizable form where they can specify what parameter they're testing and with what type of equipment, and if they're testing one, two, or three times. You can rearrange the form to correspond to your protocol testing order. The equipment choices are based on commonly used community science parameters so that we can provide detection ranges. There are opportunities to import existing protocols from Water Rangers and some of our partners. Getting the form right sets your volunteers up for successful monitoring and produces much higher quality data.

Fields like sample ID, testers, weather, ice-on, and preset qualitative protocols are available. These tend to be less customizable. View the How-to page for more details on how to set up your dataset's form.

---

Location

Locations are exclusive to an individual Dataset and display information for a particular Dataset only. You can set up testing Locations in the same spot, matching latitude and longitude, however, Datasets will not be combined into a single location summary. Location summaries show trends over time, as well as lines to show when Readings are above recommended levels based on region.

Location data: latitude*, longitude*, country (reverse geo-coded), state/province/county (reverse geo-coded), time-zone (auto), waterbody name*, location name*, location ID, waterbody type*, land uses, bank vegetation, reference photo, and assigned data collector.

---

Observation

Observations are groupings of Readings on a particular day. Many people take multiple Readings at the same time.

---

Readings or Datapoints

Readings are how we describe individual parameter results including their unit and equipment. We use the term Datapoints on our interface to count Readings.

Readings data: Associated with one location, dataset, organization and user. Each reading is also locked to a parameter's contextual data that was set up by the dataset administrator. This includes method and equipment (which is locked to specific units and ranges). Readings can be either quantitative (e.g. a number value, such as a conductivity reading of 164 uS/cm) or qualitative (e.g. a word descriptor, such as a water colour is green and yellow). Qualitative readings can provide a single choice (radio), select multiple (checkbox), or provide free form (text field). We are working hard to offer flexibility to accomodate complex Readings that are common to community science (e.g. secchi depth can be quantiative as 1.3m or qualitative as 'bottom visible').

---

Notes and photos

Often times notes and photos provide extra context. Right now you can add multiple photos by control clicking within your file browser only.

---

Points of interest

Points of interest are owned by an organization/dataset and display upstream (before) and downstream (after) a specific point that is, well, of interest. This can be a pollution source where you want to collect long-term trends or an intervention like reed planting, intending to show the intervention's effect on water quality. We recommend organizations set up dedicated datasets for tracking points of interest. This feature is under development: if you'd like to add in points of interest, please contact us.

Points of interest data: Latitude, Longitude, Owner organization, Downstream location ID, Upstream location ID, Grid Ref, Point of interest name, Receiving water course, created at, updated at, Point of interest category (shoreline restoration, wetland, outflow, altered shoreline, pollution source, algal bloom, other), description.

---

Downloading data and data usage

Organizations own their data- Water Rangers provide this platform as a place for communities to share it and datasets are open by default.

You can download a dataset without a login by visiting the dataset page and clicking on "Download data" on the left side panel. You will need to fill out a form to help us understand data usage. Once you fill out the form, buttons will appear for downloading the dataset's metadata and data (as two separate buttons). Data is provided in a format (almost the same as that) of DataStream's WQX data standard.

Datasets are made downloadable by Water Rangers under the Open Data Commons Attribution Licence (ODC-By). You are free to share, modify, and use this dataset, provided that proper attribution is given. The proper attribution statement is provided to you when you download data from a dataset. It follows this format:

SOURCE: [Dataset name] dataset by [Organization] is licensed under Open Data Commons Attribution Licence (ODC-By).

As a data user, it is important for you to recognize the efforts and intentions of each dataset.

---

Importing historical data to this platform

If you have historical data you'd like to import, use the templates provided for meta data and data import (coming soon). Importing historical data takes time from technical staff members to map your metadata and ensure data is imported correctly. We charge a small fee to recognize this effort (we apply for grant funding to provide this service, especially for priority groups that are historically underfunded. If your organization needs financial support, please let us know).

---

Request to use our API

• Sign up for an account. You do not need to go through the process of creating or joining an organization.
• Send an email to contact [at] waterrangers [dot] ca with the email you registered with, a little bit about you, plus a description of what data you're looking to pull and how often you plan to use the API connection.
• If your implementation fits, we will send you an API key to your email. This may take a few days, so please give yourself adequate time to make this request.
• Your rate limit will initially be set at 1000.

Using the API

Using APIs requires coding skills. If you are new to this, please consider downloading individual datasets as a .csv from the dataset pages.

Appending .json to your endpoint and then including the API key to the end of your URL. For example, to access datasets, you'd visit:

https://data.waterrangers.com/datasets.json?api_key=[api_key]

Consult the API docs to understand endpoints, parameters and data responses.