{"id":15091141,"url":"https://github.com/drewalth/flow-forecast","last_synced_at":"2026-02-14T22:02:39.446Z","repository":{"id":254755607,"uuid":"847432493","full_name":"drewalth/flow-forecast","owner":"drewalth","description":"Predict river flow rates based on historical data","archived":false,"fork":false,"pushed_at":"2024-11-16T02:57:00.000Z","size":510,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-07T00:58:53.682Z","etag":null,"topics":["flow","forecast","forecasting","river","whitewater"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drewalth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-25T20:00:29.000Z","updated_at":"2025-02-21T03:41:18.000Z","dependencies_parsed_at":"2024-11-16T03:23:57.950Z","dependency_job_id":"648da66a-6f1e-460c-93f6-07bf81f7fcda","html_url":"https://github.com/drewalth/flow-forecast","commit_stats":{"total_commits":26,"total_committers":1,"mean_commits":26.0,"dds":0.0,"last_synced_commit":"50c331f1ef9a31263f0c59df64457a0a5b93deb7"},"previous_names":["drewalth/flow-forecast"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/drewalth/flow-forecast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fflow-forecast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fflow-forecast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fflow-forecast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fflow-forecast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drewalth","download_url":"https://codeload.github.com/drewalth/flow-forecast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fflow-forecast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29457793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T21:29:27.764Z","status":"ssl_error","status_checked_at":"2026-02-14T21:28:11.111Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flow","forecast","forecasting","river","whitewater"],"created_at":"2024-09-25T10:35:51.447Z","updated_at":"2026-02-14T22:02:39.428Z","avatar_url":"https://github.com/drewalth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flow-forecast\n\n![Hero](assets/flowforecast-logo.jpeg)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python Version](https://img.shields.io/badge/Python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3120/)\n[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0.0-green.svg)](https://swagger.io/specification/)\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Overview](#overview)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Development](#development)\n  - [Using Docker](#using-docker)\n- [Making Requests](#making-requests)\n- [OpenAPI \u0026 Client SDKs](#openapi--client-sdks)\n- [Swift Integration](#swift-integration)\n- [Considerations](#considerations)\n- [Related Projects](#related-projects)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Introduction\n\n**flow-forecast** is an experimental project aimed at forecasting the flow rate of rivers using historical data. Leveraging Facebook's [Prophet](https://facebook.github.io/prophet/) library, the API provides valuable insights for kayakers, rafters, and river enthusiasts to plan their trips effectively.\n\n\u003e This project is _experimental_ and is subject to change. There is ample room for improvement. Contributions and suggestions are highly encouraged!\n\n## Features\n\n- ✅ **Flow Rate Forecasting**: Predict river flow rates based on historical data.\n- ✅ **Dockerized API**: Simplify deployment with Docker.\n- ✅ **OpenAPI Documentation**: Comprehensive API documentation for easy integration.\n\n## Overview\n\nUsing 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.\n\n## Getting Started\n\n### Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n- **Python 3.12**: [Download Python](https://www.python.org/downloads/)\n- **[Poetry](https://python-poetry.org/)**: A dependency management and packaging tool for Python.\n- **[Node.js](https://nodejs.org/en)**: Required for generating client SDKs.\n\n### Development\n\nFollow these steps to set up the development environment:\n\n1. **Clone the Repository**\n    ```bash\n    git clone https://github.com/drewalth/flow-forecast.git\n    cd flow-forecast\n    ```\n\n2. **Install Dependencies**\n    ```bash\n    poetry install\n    ```\n\n3. **Run the Application**\n    ```bash\n    poetry run start\n    ```\n\n4. **Make a Test Request**\n    ```bash\n    curl -X GET \"http://127.0.0.1:8000/forecast?site_id=09359500\"\n    ```\n\n### Using Docker\n\nDocker simplifies the setup/deployment process. Here's how to build and run the application using Docker:\n\n1. **Build the Docker Image**\n    ```bash\n    docker build -t flow-forecast .\n    ```\n\n2. **Run the Docker Container**\n    ```bash\n    docker run -p 8000:8000 flow-forecast\n    ```\n    *Alternatively, use Docker Compose:*\n    ```bash\n    docker compose up\n    ```\n\n3. **Make a Test Request**\n    ```bash\n    curl -X GET \"http://127.0.0.1:8000/usgs/forecast?site_id=09359500\"\n    ```\n\n## Making Requests\n\nTo interact with the API, provide a `site_id` as a query parameter. This ID corresponds to a specific USGS monitoring station.\n\n- **Find a Site ID**: Search for rivers on the [USGS website](https://waterdata.usgs.gov/nwis) to obtain the `site_id`.\n  \n- **Example**: The site ID `09359500` corresponds to the [Animas River at Tall Timber Resort Above Tacoma, CO](https://waterdata.usgs.gov/monitoring-location/09359500/).\n\n## OpenAPI \u0026 Client SDKs\n\nThe API is documented using **OpenAPI**. Use the provided [OpenAPI Specification](flow-forecast.openapi.yml) to generate client SDKs in various languages.\n\n### Generating Client SDKs\n\nEnsure you have **Node.js** and **npm** installed, then run:\n\n```bash\nnpm install\n```\n\nGenerate all client SDKs:\n\n```bash\nmake generate_clients\n```\n\n## Considerations\n\n- **Data Source**: Utilizes publicly available data from [USGS](https://www.usgs.gov/).\n- **Data Limitations**: The model currently doesn't account for factors like weather, temperature, snowpack, or dam releases, which can influence river flow rates.\n\n## Related Projects\n\n- [wh2o-vue](https://github.com/AmericanWhitewater/wh2o-vue): The official JS frontend for American Whitewater.\n- [aw-ios](https://github.com/AmericanWhitewater/aw-ios): The official iOS app for American Whitewater.\n- [aw-android](https://github.com/AmericanWhitewater/aw-android): The official Android app for American Whitewater.\n- [FlowKit](https://github.com/drewalth/FlowKit): A Swift package for working with flow data from USGS, Canadian Hydrometric Data, and other sources.\n- [GaugeWatcher](https://apps.apple.com/us/app/gaugewatcher/id6498313776): An iOS app for tracking river flow rates in North America and New Zealand.\n\n## Contributing\n\nWe welcome contributions and suggestions! To get started:\n\n1. **Fork the Repository**\n2. **Create a Feature Branch**\n    ```bash\n    git checkout -b feature/YourFeature\n    ```\n3. **Commit Your Changes**\n    ```bash\n    git commit -m \"Add your message\"\n    ```\n4. **Push to the Branch**\n    ```bash\n    git push origin feature/YourFeature\n    ```\n5. **Open a Pull Request**\n\nPlease ensure your code adheres to the project's coding standards and all tests pass. For detailed guidelines, refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Fflow-forecast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrewalth%2Fflow-forecast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Fflow-forecast/lists"}