flow-forecast

Table of Contents

• Introduction
• Features
• Overview
• Getting Started
  • Prerequisites
  • Development
  • Using Docker
• Making Requests
• OpenAPI & Client SDKs
• Swift Integration
• Considerations
• Related Projects
• Contributing
• License

Introduction

flow-forecast is an experimental project aimed at forecasting the flow rate of rivers using historical data. Leveraging Facebook's Prophet library, the API provides valuable insights for kayakers, rafters, and river enthusiasts to plan their trips effectively.

This project is experimental and is subject to change. There is ample room for improvement. Contributions and suggestions are highly encouraged!

Features

• ✅ Flow Rate Forecasting: Predict river flow rates based on historical data.
• ✅ Dockerized API: Simplify deployment with Docker.
• ✅ OpenAPI Documentation: Comprehensive API documentation for easy integration.

Overview

Using Prophet, the project analyzes historical river flow data to generate accurate forecasts. The primary goal is to assist outdoor enthusiasts in anticipating river conditions, enhancing safety and planning for their adventures.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.12: Download Python
• Poetry: A dependency management and packaging tool for Python.
• Node.js: Required for generating client SDKs.

Development

Follow these steps to set up the development environment:

1. Clone the Repository

   git clone https://github.com/drewalth/flow-forecast.git
   cd flow-forecast

2. Install Dependencies

   poetry install

3. Run the Application

   poetry run start

4. Make a Test Request

   curl -X GET "http://127.0.0.1:8000/forecast?site_id=09359500"

Using Docker

Docker simplifies the setup/deployment process. Here's how to build and run the application using Docker:

1. Build the Docker Image

   docker build -t flow-forecast .

2. Run the Docker Container

   docker run -p 8000:8000 flow-forecast

   Alternatively, use Docker Compose:

   docker compose up

3. Make a Test Request

   curl -X GET "http://127.0.0.1:8000/usgs/forecast?site_id=09359500"

Making Requests

To interact with the API, provide a site_id as a query parameter. This ID corresponds to a specific USGS monitoring station.

• Find a Site ID: Search for rivers on the USGS website to obtain the site_id.

• Example: The site ID 09359500 corresponds to the Animas River at Tall Timber Resort Above Tacoma, CO.

OpenAPI & Client SDKs

The API is documented using OpenAPI. Use the provided OpenAPI Specification to generate client SDKs in various languages.

Generating Client SDKs

Ensure you have Node.js and npm installed, then run:

npm install

Generate all client SDKs:

make generate_clients

Considerations

• Data Source: Utilizes publicly available data from USGS.
• Data Limitations: The model currently doesn't account for factors like weather, temperature, snowpack, or dam releases, which can influence river flow rates.

Related Projects

• wh2o-vue: The official JS frontend for American Whitewater.
• aw-ios: The official iOS app for American Whitewater.
• aw-android: The official Android app for American Whitewater.
• FlowKit: A Swift package for working with flow data from USGS, Canadian Hydrometric Data, and other sources.
• GaugeWatcher: An iOS app for tracking river flow rates in North America and New Zealand.

Contributing

We welcome contributions and suggestions! To get started:

1. Fork the Repository
2. Create a Feature Branch

   git checkout -b feature/YourFeature

3. Commit Your Changes

   git commit -m "Add your message"

4. Push to the Branch

   git push origin feature/YourFeature

5. Open a Pull Request

Please ensure your code adheres to the project's coding standards and all tests pass. For detailed guidelines, refer to the CONTRIBUTING.md file.

License

This project is licensed under the MIT License. See the LICENSE file for details.