StreamStats Documentation Status

Python package for interfacing with the USGS StreamStats API.


  • Plot the GeoJSON of a watershed containing a spatial point in the United States

  • Find available basin characteristics of an identified watershed

  • Find the hydrologic unit code (HUC) of an identified watershed


Stable release

To install StreamStats via pip use:

$ pip install streamstats

This is the preferred method to install StreamStats, as it will always install the most recent stable release. If you don’t have pip installed, this Python installation guide can guide you through the process.

Alternatively, StreamStats can be installed from the conda-forge repository using Conda:

$ conda install -c conda-forge streamstats

From sources

The sources for StreamStats can be downloaded from the GitHub repository .

You can either clone the public repository:

$ git clone git://

Once you have a copy of the source, you can install it with:

$ python install

How to Contribute

The steps to set up StreamStats for local development are as follows:

  1. Fork the streastats repo on GitHub

  2. Clone your fork locally:

$ git clone git://
  1. Install your local copy into a new environment

If you have virutalenvwrapper installed:

$ mkvirtualenv streamstats

If you are using conda:

$ conda create -n streamstats python=3
$ conda activate streamstats

Then install StreamStats:

$ cd streamstats/
$ pip install -r requirements.txt
$ pip install -r requirements_dev.txt
$ install -e .
  1. Create a branch for local development:

$ git checkout -b name-of-your-bugfix/feature

Now you can make your changes locally

5. When your changes are complete, check that your changes pass flake8 and the tests, including other Python versions with tox:

$ pytest
$ tox
  1. Commit your changes and push your branch to GitHub:

$ git add
$ git commit -m "Your detailed description of your changes"
$ git push origin name-of-your-bugfix/feature
  1. Submit a pull request through the GitHub website

We welcome and greatly appreciate contributions to StreamStats! The best way to send feedback is to file an issue at To read more on ways to contribute and pull requests, click here.


Development Lead


This package was created with Cookiecutter.