Applications
Explore auxiliary applications, dashboards, and visualizations that draw from the Natural Flows Database
Water is essential for California’s people, economy, and environment. Centuries of water management through dams and diversion have altered the flows in many streams and rivers, which can harm the freshwater ecosystems. The Nature Conservancy and the United States Geological Survey (USGS), and other partners have generated estimates of natural flows (expected streamflow in the absence of human modification) in all the streams and rivers in California from 1950 to the present.
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
After more than a century of dams and diversions, many of California’s streams and rivers have highly altered flow. We used machine learning to estimate natural flows (expected streamflow in the absence of human modification) for all streams and rivers in California to help water managers identify and manage flows to support native freshwater species.
California has higher variability in hydrology between wet and dry years than any state in the US, due to a small number of winter storms providing most of the state’s precipitation (Dettinger, 2011). California also has strong spatial gradients in water availability, with 90% of the state’s water originating from 40% of its land surface (Hanack et al, 2011). Managing this variability has led to some of the most extensive water infrastructure in the world. Although more constant streamflows are desirable to support human uses, such alterations to natural variability across seasons and landscapes can have negative consequences for native species and communities.
Understanding natural flows and patterns of alteration is an important first step in managing California’s rivers and streams for human and ecosystem benefits. To protect freshwater biodiversity, we need to know California’s hydrologic foundation, including the flows that would have been in our streams and rivers in the absence of water use and human land use. We have predicted natural flows statewide and expressed these predictions as monthly flow and functional flow metrics. The methods and statewide results of the monthly flow predictions are published in Freshwater Biology (Zimmerman et al, 2017). Functional flows are aspects of the annual flow variation that directly relate to ecological, geomorphic or biogeochemical processes in riverine systems (e.g., wet-season peak flow, dry-season base flow). The functional flow metric predictions are part of the California Environmental Flows Framework (CEFF), a statewide approach to develop stream segment-scale ecological flow criteria that protect native aquatic species and communities. This approach requires that the natural range of variation of functional flow metrics (FFMs) be estimated at any potential location of interest in California.
We partnered with the U.S. Geological Survey (USGS) to develop a modeling approach that uses machine learning to predict monthly flows statewide. We identified 250 reference stream gages with little or no flow alteration across the state and split them into three regions based on climate and hydrologic conditions: Interior Mountains (including the Sierra Nevada and Klamath mountains), North Coastal Mountains (including the mountains in the north western portion of the state), and Xeric (including the Central Valley, Central and South Coast, and desert portions of the state). Using the observed monthly flows at the reference gages, we developed statistical models for each region that accurately predicted streamflow at these reference gages using fixed physical watershed characteristics (such as geology, soils, and elevation) and monthly climate data (such as precipitation, air temperature, and runoff volume). The models for each region were then used to predict flows at all streams in that region, using the NHDPlus Version 2 (Horizon Systems, 2018) to delineate stream reaches based on a common identifier (COMID). For each stream reach, we report the expected monthly mean, median, maximum, and minimum natural flow values for all months from 1950 to 2015. For each of these metrics, we also provide the average flow value predicted by the model (“estimated”) and the range of uncertainty, expressed as the 10th and 90th percentile of predicted values (“P10” and “P90”). For a full description of the datasets and methods used to generate the natural flow data, see Zimmerman et al, 2017.
Predicted monthly flows for 2016 to the present were generated using the same methods outlined above with the following modifications:
To assess the predictive accuracy of the model, we compared the predicted monthly mean flows to observed flows at 81 reference stream gages with flow data between 2010 and 2021. These reference gages are on streams expected to have natural flows because there are no major land use or hydrological modifications upstream from the gage. We found the models accurately predicted monthly flows, with an average Nash-Sutcliffe model efficiency (NSE) coefficient of 0.96 for the 2010-2015 time period and 0.92 for the 2016-2021 time period (a NSE of 1 indicates a perfect model). To compare the performance of version 2.1 models with the previous version, we evaluated the original model predictions against observations at the same set of reference gages from 2010-2015. The average NSE for the predicted versus observed monthly flow values for the original model during this period was 0.98, indicating a slight loss in model predictive accuracy with version 2.1. Using this method we will update the monthly flow estimates every 1-2 months as new climate data from PRISM become available.
Using a similar modeling approach, functional flow metrics were predicted for every stream segment in the state (Grantham et al. 2022). One key difference between the approaches is that monthly flows were predicted for each month over the time period of 1950-2015, whereas the functional flow metric models generate long-term predictions (across the entire time period of 1950-2015) of functional flows metric values for each stream segment. The expected natural range of functional flows are reported for all years, and for subsets of years classified as “wet”, “moderate” and “dry” water years. For this exercise, a set of 219 reference gages was used to train the models. We modeled metrics associated with five functional flow components including the fall pulse flow, wet-season baseflow, peak flow, spring recession flow, and dry-season base flow (Yarnell et al. 2020). Functional flow metrics that describe each of these functional flow components are described in the tables below. For each FFM, predictions are provided as a range (10th, 50th, and 90th percentile values), which reflects both model uncertainty and interannual variation. In Section A of CEFF, these predicted metrics are used to identify ecological flow criteria to protect native aquatic species and communities. For a full description of the datasets and methods used to predict functional flow metrics, see Appendix D of the CEFF Guidance Document and Grantham et al, 2022.
| Flow Characteristic | Flow Metric Name | Flow Metric Code | Flow Metric Description |
|---|---|---|---|
| Magnitude (cfs) | Fall pulse magnitude | fa_mag |
Peak magnitude of fall pulse event (maximum daily peak flow during event) |
| Start (water year day) | Fall pulse start | fa_tim |
Water year day of fall pulse event peak |
| Duration (days) | Fall pulse duration | fa_dur |
Duration of fall pulse event |
| Flow Characteristic | Flow Metric Name | Flow Metric Code | Flow Metric Description |
|---|---|---|---|
| Magnitude (cfs) | Wet season baseflow and median flow | wet_bfl_mag_10, wet_bfl_mag_50 |
Magnitude of wet-season baseflow and median flow (10th percentile and median of daily flows within that season, including peak flow events) |
| Start (water year day) | Wet-season start | wet_tim |
Start date of wet-season in water year days |
| Duration (days) | Wet-season duration | wet_bfl_dur |
Wet-season baseflow duration (# of days from start of wet-season to start of spring season) |
| Flow Characteristic | Flow Metric Name | Flow Metric Code | Flow Metric Description |
|---|---|---|---|
| Magnitude (cfs) | Peak flow magnitude |
peak_2,
peak_5,
peak_10
|
Peak-flow magnitude (2-year, 5-year, and 10-year recurrence interval) |
| Duration (days) | Peak flow duration |
peak_dur_2,
peak_dur_5,
peak_dur_10
|
Seasonal duration of 2-year, 5-year, and 10-year recurrence interval peak flow (cumulative number of days in which this peak flow magnitude is exceeded) |
| Frequency | Peak flow frequency |
peak_fre_2,
peak_fre_5,
peak_fre_10
|
When a peak flow event happens in a year, the number of times a peak flow amount is exceeded within one season (e.g., fall, wet-season) |
| Flow Characteristic | Flow Metric Name | Flow Metric Code | Flow Metric Description |
|---|---|---|---|
| Magnitude (cfs) | Spring recession magnitude | sp_mag |
Spring recession magnitude (daily flow on start date of spring-flow period, 4 days after last wet-season peak) |
| Start (water year day) | Spring start | sp_tim |
Start date of spring in water year days |
| Duration (days) | Spring duration | sp_dur |
Spring flow recession duration (# of days from start of spring to start of dry-season baseflow period) |
| Rate of change (%) | Spring rate of change | sp_roc |
Spring flow recession rate (median daily rate of change over decreasing periods during the recession) |
| Flow Characteristic | Flow Metric Name | Flow Metric Code | Flow Metric Description |
|---|---|---|---|
| Magnitude (cfs) | Dry season baseflow and high baseflow | ds_mag_50, ds_mag_90 |
Base flow magnitude (50th and 90th percentile of daily flow within dry season) |
| Start (date) | Dry-season start | ds_tim |
Dry-season baseflow start timing (water year day of dry season) |
| Duration (days) | Dry-season duration | ds_dur_ws |
Dry-season baseflow duration (# of days from start of dry season to start of wet season) |
The mapping tool and API provide direct access to the results of this analysis. Within the mapping tool, users can click on any stream segment to see a summary chart of the average estimated natural flows for the full modeling period (1950 to the present). The charts show the average monthly flow for “Wet years” (predicted mean annual flows in the top third of all water years), “Dry years” (predicted mean annual flows in the bottom third of all water years) and “Mod. Years” (predicted mean annual flows in the middle third of all water years). When the user hovers over a line on the chart, the average of the P10 and P90 values are displayed to show the range of estimates (prediction interval) for any given stream. By clicking “Raster Hydrograph”, the user can see a raster hydrograph of all the predicted monthly natural flows by year and month.
A user can see the predicted functional flows by selecting the “Functional Flow Metric” page at the bottom of the pop-up window for any stream segment. For each flow metric, a numeric value of flow, duration, or timing is provided for the mean model estimate (“50th Percentile”) as well as the range of model estimates expressed by the 10th and 90th percentile model results. Users can select different year types (“Wet”, “Dry”, “Moderate”, or “All Years”), as well as different functional flow components (see Table 1). Some functional flow components (e.g., Peak flow) provide different metrics depending on the recurrence interval of interest. For these components, the user can select and compare metrics between different recurrence intervals.
A subset of the streams in California have stream gages that measure actual (observed) flows. These segments are shown in purple in the mapping tool. For these streams, the summary chart shows a fourth line that indicates the average monthly observed flow at the stream gage. Please note that these averages are based on the data available and in most cases will not reflect the same 1950-2015 time period shown for the estimated data. In addition, a chart of flow alteration is available by using the control on the bottom of the pop-up to select the monthly flow alteration chart. This chart shows the percent of the observed monthly flows that are altered by being either inflated (blue bars) or deflated (red bars). An observed monthly flow is considered inflated if it is greater than the 90th percentile (P90) model estimate for that month and year. Similarly, an observed monthly flow is considered deflated if is less than the 10th percentile (P10) model estimate. For example, suppose the modeled flow in January 2015 for a given stream had a P10 estimate of 10 cubic feet per second (CFS) and a P90 estimate of 100 CFS. If the observed monthly average flow in January 2015 was 5 CFS, it would be considered deflated. If the observed monthly average flow in January 2015 was 110 CFS, it would be considered inflated. The chart summarizes the frequency of inflation or deflation for each month to show the type and seasonality of alteration. If all the observed flows for a given month are not altered (i.e., they fall within the range of P10 to P90) then no bars are shown for that month.
A subset of stream gages also have enough data to generate estimates of observed functional flow metrics to compare with the predicted functional flows. Segments that have both observed monthly flows and observed functional flow metrics are shown in dark purple in the mapping tool. We only present these comparisons if there is enough daily stream flow data since 1980 to estimate the functional flow metric for 15 years or more for non-peak flow metrics, and 20 years or more for peak flow metrics or more. We then take the median observed metric over that time frame and compare to the 10th and 90th percentile model estimates for a functional flow metric. If the observed median is outside of this range, the flow is likely altered. If the observed median is inside this range, the flow is likely unaltered. In some cases, the median falls inside the range, but most of the observed years fall outside of the range, making the alteration status more difficult to determine. These cases are noted with an asterisk in the pop-up window, and are classified as “indeterminate". See Appendix J of the CEFF Guidance Document for more details on how to evaluate reference-based functional flow metrics against the same metrics calculated under current (observed or modeled) conditions to determine if functional flows are altered. Users familiar with the R programing language can calculate flow alteration for a given stream gage location using the instructions and code posted here .
A user can also download all data for predicted monthly and functional flow metrics (including monthly mean, minimum, and maximum daily flows for a month) by clicking the button with the plus sign in the bottom right corner of the popup window. The predicted monthly flow data is in a long data format, with each data value for each year and month in a unique row. The functional flow data is also in a long data format with metrics provided by year type (wet, dry, moderate, and all years). A user can also download data for all stream segments in a watershed by clicking the “Select by Watershed” tab. The watershed boundaries are based on the 10- or 12-digit hydrologic unit code (HUC10 or HUC12) level watersheds (Horizon Systems, 2018).
We published a paper illustrating statewide patterns of streamflow alteration based on the comparison between estimated and observed monthly flows. The analysis shows that the primary pattern of flow alteration across California is reduced flow variability. Most streams and rivers have flows that are both higher than expected (inflated) and lower than expected (depleted) depending on the time of year, due to moving water from wetter to drier seasons and from wetter to drier parts of the state. Flows are typically inflated during the dry summer months and depleted during the winter and spring, with losses of both the highest and lowest flows of the year (Zimmerman et al, 2017).
California Environmental Flows Framework Technical Team. 2018. The California Environmental Flows Framework Guidance Document. Retrieved from http://ceff.ucdavis.edu
Dettinger, M. 2011. Climate change, atmospheric rivers and floods in California—A multimodel analysis of storm frequency and magnitude changes. Journal of the American Water Resources Association, 47, 514–523. https://doi.org/10.1111/j.1752-1688.2011.00546.x
Grantham TE, DM Carlisle, J Howard, B Lane, R Lusardi, A Obester, S Sandoval-Solis, B Stanford, ED Stein, KT Taniguchi-Quan, SM Yarnell, JKH Zimmerman. 2022. Modeling Functional Flows in California’s Rivers. Frontiers in Environmental Science. 10. https://www.frontiersin.org/article/10.3389/fenvs.2022.787473
Hanak, E., Lund, J., Dinar, A., Gray, B., Howitt, R., Mount, J., et. al. 2011. Managing California's water: From conflict to reconciliation. San Francisco, CA: Public Policy Institute of California. Retrieved from http://books.google.com/books/about/Managing_California_s_Water.html?hl=&id=90hLp8aGrgIC .
Horizon Systems. 2015. National hydrography dataset plus: Horizon Systems Corporation. Retrieved June 1, 2015, from http://www.horizon-systems.com/nhdplus/ .
Yarnell SM, Petts GE, Schmidt JC, Whipple AA, Beller EE, Dahm CN, Goodwin P, Viers JH. 2015. Functional Flows in Modified Riverscapes: Hydrographs, Habitats and Opportunities. BioScience. 65:10:963–972. https://doi.org/10.1093/biosci/biv102
Yarnell, SM, ED Stein, JA Webb, T Grantham, RA Lusardi, J Zimmerman, RA Peek, BA Lane, J Howard, S Sandoval-Solis. 2020. A functional flows approach to selecting ecologically relevant metrics for environmental flow applications. Freshwater Biology 36 318-324.
Zimmerman JKH, Carlisle DM, May JT, et al. 2017. Patterns and magnitude of flow alteration in California, USA. Freshwater Biology 2018;63:859–873. https://doi.org/10.1111/fwb.13058
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
Select a watershed on the map to add all of the stream segments within it to the download queue.
Select a stream segment on the map and click the ‘+’ button to add stream to download queue.
In addition to the map-based viewer and download tool, the Natural Flows Database is also accessible through a simple but powerful RESTful Application Programming Interface (API). The API is publicly available for data analysis. It can be used with any programming language that supports HTTP requests such as Python, R, JavaScript, and many others as well as from a command line shell, e.g. using curl. In response to GET and POST requests, the API is able to stream CSV formatted data.
Click the following link to download a zip file of the entire functional flow metrics dataset: https://rivers.codefornature.org/data/ffm-final-v1.2.1.zip (103 MB)*
*Functional Flow metric predictions are generated from a statewide model (Grantham et al. 2022) or from observed values at regional reference gauges. Given the diversity of landscapes and stream conditions in California, the accuracy of metric estimates is expected to vary based on the physical setting of individual streams. Users should consider local circumstances when interpreting the data and refer to the California Environmental Flows Framework ceff.ucdavis.edu for additional guidance.
Since authentication, throttling, and rate limits are not yet implemented but may become necessary the current version is marked as beta. While the API is very stable, we don't guarantee its availability. While the API is ready for data download and analysis, please let us know if you plan to build an application. The data schema for version 2 is final. We might add fields but the name and the position of existing endpoints and fields will not change before the next major release. Data values might change due to model improvements. Citation requirements apply for the use of the data.
Please contact falk.schuetzenmeister@tnc.org for further questions.
The API provides two endpoints. The first one
https://flow-api.codefornature.org/v2/stream/
serves modelled natural flow data for every stream segment
(identified by NHDv2 COMID) in the dataset.
The second one
https://flow-api.codefornature.org/v2/ffm/
provides seasonally aggregated functional flow characteristics for
the same segments. Please refer to the science section for more
details.
The API can be tested in a web browser, no specific authentication
or format headers are required for GET requests (for POST see below).
If no comids query parameter is provided, the API returns
CSV file (Content-type: text/csv) with column headers but
without data.
To download data, query for an actual comid, for example
https://flow-api.codefornature.org/v2/stream/?comids=15039097.
This request returns all variables and years for the stream segment
with the COMID 15039097. The term “COMID” refers to the
common identifier within the
National Hyrdrography Dataset (NHDPlusV2)
which is used as reference throughout the project (and in other
hydrological work).
Please note that the request parameter comids is a
plural word. The provided value will be interpreted as a list. E.g.
https://flow-api.codefornature.org/v2/stream/?comids=15039097,2803945
will return data for both COMIDs. If a given COMID does not exist in
the Natural Flows database, the request will not return data for that
particular stream segment (but for other requested COMIDs that do
exist). If none of the requested COMIDs exist the CSV file will
only contain the header line. You will not receive a HTTP
error if non-existent data is requested.
The requests above triggers a CSV download which will be identically formatted and named as if requested from the form in the map-based tool:
comid,statistic,variable,year,month,value
15039097,max,estimated,1950,1,291321.317781431
15039097,max,estimated,1950,2,288226.252365343
15039097,max,estimated,1950,3,142474.19934679
15039097,max,estimated,1950,4,86750.5785288129
15039097,max,estimated,1950,5,40582.2848221952
15039097,max,estimated,1950,6,18109.1250910531
...Progress bars and download time estimates will not work because of the streaming nature of the API. The file will not be fully prepared on our server before the download actually starts. Instead, records will be sent as they become available which increases speed and minimizes memory used by our server.
The entire dataset could be downloaded with the query parameter
comids=0. Please refrain from sending
this request unless you have a use for the entire dataset of roughly 42
Gbyte and a CSV file that cannot be handled in Microsoft Excel.
The Natural Flows API is a read-only API therefore we are not overly
concerned about security. However, we are concerned about resource use.
In the future we might restrict the amount of data that can be
requested per time unit and user (throttling). For future authentication
and metering, please expect to add a token= parameter to your
requests. Once implemented, you will be able to obtain an access token from
this page and the documentation will be updated accordingly.
Please don't rely on this API to build web applications since we cannot guarantee availability, performance, or scalability. Please contact us if you want to build something awesome with this data. Feel free to prototype, the API is CORS enabled.
We would appreciate, if you could cache downloads of more than 5 Mbyte
(all data for about 10 segments) on your machine whenever possible and specify
your requests used in scripts as much as possible in order to keep the load on
the server and the transferred amount of data low. For R users to get easily
started with caching see
https://cran.r-project.org/web/packages/httpcache/vignettes/httpcache.html.
The use of this package instead of httr will speed up your data
analysis significantly.
This section describes the endpoints of the API in detail, which CSV columns are available, and what query parameters can be used to limit the amount of data returned.
Query strings containing query parameters begin with a ? at
the end of the URL. Query parameters have the form keyword=value.
Several parameters are separated by an &. The query string
must not contain any spaces. Please note that some query parameters are plural
words. In these cases, a lists separated by commas without spaces, e.g.
statistics=min,maxreturns all of the requested data. Another
way to provide lists is by repeating the keyword, such as
statistics=min&statistics=max.
In URLs special characters need to be escaped. Most browsers and high
level programming languages will do that automatically or provide utility
functions. However, an URL like
https://flow-api.codefornature.org/v2/stream/?comids=15039097,2803945&statistics=mean,max&begin_year=1980&months=1,3,5
would be sent like this over the Internet:
https://flow-api.codefornature.org/v2/stream/?comids%3D15039097%2C2803945%26statistics%3Dmean%2Cmax%26begin_year%3D1980%26months%3D1%2C3%2C5
Some environments may require that the programmer takes explicitly care of this
(see https://www.w3schools.com/tags/ref_urlencode.asp
for more information on URL encoding).
The response mimetype for both endpoints is text/csv,
Accept headers do not have any effect.
This end point returns modelled natural flow data for every month between 1950 and the present. The CSV header line for this endpoint is:
comid,statistic,variable,year,month,value
Fields:
comid (string): NHDPlusV2 common identifier
statistic (string): statistics, e.g. max, mean, median, min
variable (string): percentile of model runs
year (integer): model year
month (integer): model month
value (number): modelled value
The /stream/ endpoint provides query parameters
identical to the form fields in the map-based tool to subset and
slice data. Following parameters can be used to subset the data.
comids (list of integers): Comids in California where Natural
Flows Data is available (default: None, special values: 0 will request all)
statistics (list of strings): max, mean, median, min
(default: all)
variables (list of strings): estimated, p10, p90, observed
(default: all)
begin_year (integer): one value between 1950 .. 2023 (default: 1950)
end_year (integer): one value between 1950 .. 2023 (default: 2023)
months (list of integers): list of values between 1 .. 12 (default: all)
This endpoint returns the functional flow metrics. Functional Flow metric predictions are currently in draft form and have not yet been peer reviewed. We will update this site with a link to documentation when peer review has been completed. The estimates of natural functional flow metrics are from a statewide model or observed values from regional reference gauges. Given the diversity of landscapes and stream conditions in California, the accuracy of metric estimates is expected to vary based on the physical setting of individual streams. Users should consider local circumstances when interpreting the data and refer to the California Environmental Flows Framework (ceff.ucdavis.edu) for additional guidance. The CSV header line for this endpoint is:
comid,ffm,wyt,p10,p25,p50,p75,p90,unit,source,gage_id,observed_years,observed_year_start,observed_year_end,alteration
Fields:
comid (string): NHDPlusV2 common identifier
ffm (string): functional flows metrics code (see ...)
wyt (string): water year type
p10, p25, p50, p75, p90: modeling values for 10, 25, 50, 75 and 90 percentile
of runs, use p50 for the most likely value
unit: measurement unit for p10, p25, p50, p75, and p90
source: source of p10, p25, p50, p75, and p90
gage_id: only populated if source=observed,
USGS gage id where observed
observed_years: only populated if source=observed, number of years of observations
observed_year_start: only populated if source=observed, first water year of observations
observed_year_end: only populated if source=observed, last water year of observations
alteration: only populated if source=observed, alteration compared to modelled value
Query parameters:
comids (list of integers): Comids in California where Natural
Flows Data is available (default: None, special values: 0 will request all)
ffms (list of strings): ds_dur_ws, ds_mag_50, ds_mag_90, ds_tim,
fa_dur, fa_mag, fa_tim, peak_10, peak_2, peak_5, peak_dur_10,
peak_dur_2, peak_dur_5, peak_fre_10, peak_fre_2, peak_fre_5, sp_dur,
sp_mag, sp_roc, sp_tim, wet_bfl_dur, wet_bfl_mag_10, wet_bfl_mag_50,
wet_tim (default: all)
wyts (list of strings): dry, moderate, wet, all (default: 'dry,moderate,wet,all')
sources (list of strings): model, inferred, observed
Note: Not all ffms or sources are
available for every comid. A single functional flows metric can
have multiple records from several sources. The combination
comid, ffm, source, gage_id is unique.
If sources=observation there are a few cases with
multiple records due to multiple gages on the stream segment.
Example:
https://flow-api.codefornature.org/v2/ffm/?comids=15039097,2803945&ffms=ds_dur_ws,ds_mag_50&wyts=dry
Values for inferred and observed are only available for a few records. Query with
https://flow-api.codefornature.org/v2/ffm/?comids=0&sources=observed,inferred.
Please allow for some time to finish.
RESTful APIs make use of the different verbs provided by the HTTP protocol for specific purposes. GET requests are typically used for requesting data without making changes to the data.
In a GET request all specifics that are needed to query data are provided in the URL as query parameters. This approach is only limited by the maximum length URLs can have. For the Natural Flows API the limit is 4,096 characters but some browsers will limit URLs to 2,048 characters (including protocol and domain name). Since the Natural Flows dataset contains roughly 130,000 stream segments this limit could matter, e.g. if you want to request the data for all stream segments in Southern California. The API provides the ability to POST a long list of COMIDS.
Currently two content types for the request body of POST requests
are supported application/x-www-form-urlencoded
(default) and application/json. The response will be
a CSV file (Content-Type: text/csv), the same format
as the map interface or GET requests.
The content type (application/x-www-form-urlencoded)
is typically generated through HTML forms like:
<form action="https://flow-api.codefornature.org/v2/stream/" method="post">
<!-- Use type=hidden for values preselected by app interactions -->
<input type="hidden" name="comids" value="15039097,2803945">
<!-- Use same name (not id!) for multiple choice -->
<span>Statistics:</span>
<label for="min">Min</label>
<input id="min" type="checkbox" name="statistics" value="min">
<label for="mean">Mean</label>
<input id="mean" type="checkbox" name="statistics" value="mean" checked="true">
<label for="median">Median</label>
<input id="median" type="checkbox" name="statistics" value="median">
<label for="max">Max</label>
<input id="max" type="checkbox" name="statistics" value="max">
<!-- add additional fields here -->
<button type="submit">Download</button>
</form>While application/x-www-form-urlencoded queries can be
generated by most scripting languages, the use of JSON
seems more convenient. In both cases, the same keywords
(and allowed values) as for GET requests apply
(e.g. for /streams/: comids, statistics, variables, begin_year, end_year, months).
If you post a JSON body the
Content-Type header has to be explicitly set to
application/json:
POST request cannot easily be evaluated in the browser. There
are tools like Postman
or the Firefox plugin
Rested
that do allow for convenient evaluation of POST requests.
Using the command line tool curl a POST request could
look like this:
curl \
-H "Content-Type: application/json" \
-d '{"comids":[15039097,2803945],"statistics":["min","max"],"variables":["estimated"],"begin_year":1980,"end_year":1981,"months":[1,2]}' \
-X POST https://flow-api.codefornature.org/v2/stream/In the section above, we described how to submit long lists of COMIDSs to the API. This raises the question how these lists can be generated, e.g. from a geographic region, a river basin, or a feature name. The Natural Flows API does currently not provide a build-in way to query for COMIDs. We avoided to duplicate resources that already exist in one form or another. We will add capabilities to generate COMID lists by interacting with the map-based tool in the future.
The canonical reference for the work with stream segments and COMIDs
is the NHDPlusV2 dataset. This dataset can be downloaded from
http://www.horizon-systems.com/. For the current extent of the
API, you will find the stream lines in:
http://www.horizon-systems.com/NHDPlusData/NHDPlusV21/Data/NHDPlusCA/NHDPlusV21_CA_18_NHDSnapshot_05.7z.
Use GIS or other geoprocessing tools to extract COMIDs of
interest.
Error handling is not yet fully implemented and malformed query
parameters (e.g. wrong data types or invalid special characters)
might occasionally result in an Internal Server Error
(500) when it should actually return a Bad Request
(400) instead. Syntactically correct queries resulting in an empty
set of data will return a CSV file containing just the header line
(no error message). Invalid query parameter keywords and values
will be ignored.
In some context you might get a Moved Permanently (301) status
message for queries that worked perfectly fine in a browser. The
reason is that requests using the HTTP protocol will be redirected
to the secure HTTPS protocol. Another reason could be that you
forgot the trailing slash in the URL since /v2/stream
will be redirected to /v2/stream/. While your browser
will just follow these redirects the http function in your scripting
language might not. Curl will follow redirects only if provided with
the -L flag. Make sure to request with the correct protocol
(https://) and the trailing slash at the end of the URL.
Accept headers are currently ignored.
Content-Type: text/csv will be served no matter what.
The API does not issue Not Acceptable (406)
errors or any other data format than CSV. Make sure that your code
can handle the response.
Please use the code examples to get started in different programming languages. Please consider storing large API returns to your hard disk in order to use resources carefully.
"""
Example using the Natural Flows API
"""
import urllib.request
from urllib.parse import urlencode
URL = 'https://flow-api.codefornature.org/v2/stream/'
def main():
query = {
'comids': [15039097, 2803945],
'statistics': ['min', 'max'],
'variables': 'estimated',
'begin_year': 2014,
'months': [1]
}
url = '?'.join([URL, urlencode(query, True)])
print('Requested URL', url)
csv_file = urllib.request.urlopen(url)
for line in csv_file:
print(line.decode('utf8'), end='')
if __name__ == '__main__':
main()Here is a very simple R example which is not yet equivalent to the Python example:
library(httr)
url <- "https://flow-api.codefornature.org/v2/stream/?comids=15039097"
r <- GET(url)
# The content function of the httr library uses the Content-Type header
# to determine how to parse the data, text/csv in our case
content(r)
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
Explore auxiliary applications, dashboards, and visualizations that draw from the Natural Flows Database
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
You can use the map or search feature to find any stream or river in California. To use the map, open the map page, then zoom in using the plus buttons in the upper left of the screen, the mouse wheel, or pinch gesture on mobile and touch screens. As you zoom in, more streams and rivers will appear on the map. Click on your river of interest to see the natural flow estimates for that location.
To use the search feature, click on the magnifying glass in the upper right of the map screen. Type in a river name, a stream gage name, a place name, the COMID for a stream segment from the NHDPlus (v2) dataset, or even the latitude and longitude coordinates. As you type, a list of search results will appear below the search box, organized into groups including stream segments, stream gages, and places from the Esri geocoding service. Click on a search result and the map will automatically zoom to that location.
Natural flows (both monthly and functional flow estimates) were estimated based on watershed characteristics, rainfall, and temperature data. The relationship between these predictor variables and the flow estimates were developed using machine learning models developed from reference stream gages. Reference stream gages have relatively natural watersheds with little flow impairment from dams or diversions for at least a portion of time when the gage was recording data. The reference gages are symbolized with blue circles on the map, and clicking on them will indicate the time period when the gage had relatively unimpaired flows. Note that some of the reference gages were not used in the functional flow models. Also, many reference gages may not be considered reference for the entire period of record. For more information, see the science page.
Functional flow metrics were predicted for all streams across all years and by three water year types (dry, moderate, and wet), with the exception of the peak flow metrics. Peak flows (2-year, 5-year, and 10-year floods) were predicted across all years, because they are based on flow recurrence intervals (see science page for more information on these metrics). Peak flow duration and frequency metrics may be missing for some smaller stream segments because they inferred from reference gages and there was insufficient information to relate some smaller stream segments to reference gages. Observed functional flow metrics are currently only available on a subset of stream segments with USGS stream gages. Missing data for one or more metrics or water year types indicates insufficient observed data for calculation.
Yarnell SM, Petts GE, Schmidt JC, Whipple AA, Beller EE, Dahm CN, Goodwin P, Viers JH. 2015. Functional Flows in Modified Riverscapes: Hydrographs, Habitats and Opportunities. BioScience. 65:10:963–972. https://doi.org/10.1093/biosci/biv102
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
The California Natural Flows Database is made available under the Open Database License. Find the terms and conditions at opendatacommons.org.
The database and all its data are "as is" and "as available"
without warranty of any kind either express or implied, including
but not limited to the implied warranties of merchantability,
fitness for a particular purpose, freedom from contamination by
computer viruses and malware, and non-infringement. The Nature
Conservancy makes no warranty as to the accuracy, completeness or
reliability of any data available through the database and the
website. You are responsible for verifying any information before
relying on it. use of the website, database, and the data is at
your sole risk. If you have obtained data from a source other
than https://rivers.codefornature.org, be aware that
electronic data can be altered subsequent to original
distribution. Data can also quickly become out-of-date.
To the maximum extent permitted by law, The Nature Conservancy disclaims all liability, whether based in contract, tort (including negligence), strict liability or otherwise, and further disclaims all losses, including without limitation indirect, incidental, consequential, or special damages arising out of or in any way connected with access to or use of the website, database, or the data even if The Nature Conservancy has been advised of the possibility of such damages.
California Environmental Flows Working Group (CEFWG). California Natural Flows Database: Functional flow metrics v1.2.1, May 2021. https://rivers.codefornature.org/ (Date Accessed)
Julie K.H. Zimmerman, Daren M. Carlisle, Jason T. May, Kirk R. Klausmeyer, Theodore E. Grantham, Larry R. Brown, Jeanette K. Howard. California Unimpaired Flows Database v2.1.2, 2023. The Nature Conservancy. San Francisco CA. https://rivers.codefornature.org/ (Date Accessed)
© Copyright The Nature Conservancy. Terms of Use | Privacy Policy
