{"id":28758540,"url":"https://github.com/drhdev/carstorms","last_synced_at":"2025-06-17T04:08:51.958Z","repository":{"id":287960922,"uuid":"966369343","full_name":"drhdev/carstorms","owner":"drhdev","description":"A python script to get data about tropical storms and hurricanes from NHC on storms in the Caribbean.","archived":false,"fork":false,"pushed_at":"2025-06-14T13:46:21.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-14T14:35:42.328Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drhdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null}},"created_at":"2025-04-14T20:19:41.000Z","updated_at":"2025-06-14T13:46:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"0510ee6e-a08c-4800-b158-233e2b013b55","html_url":"https://github.com/drhdev/carstorms","commit_stats":null,"previous_names":["drhdev/carstorms"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/drhdev/carstorms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhdev%2Fcarstorms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhdev%2Fcarstorms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhdev%2Fcarstorms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhdev%2Fcarstorms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drhdev","download_url":"https://codeload.github.com/drhdev/carstorms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhdev%2Fcarstorms/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260288446,"owners_count":22986668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-17T04:08:51.223Z","updated_at":"2025-06-17T04:08:51.947Z","avatar_url":"https://github.com/drhdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# carstorms\n\nA python script to get data about tropical storms and hurricanes from NHC on storms in the Caribbean.\n\n## 🌪️ Overview\n\n`carstorms.py` is a lightweight Python script that fetches and analyzes active tropical storms and hurricanes from the [NOAA National Hurricane Center (NHC)](https://www.nhc.noaa.gov/). It checks if any dangerous systems may affect user-defined locations (e.g., St. John USVI or St. Barths), calculates the closest approach time, and classifies the storm's severity.\n\nThis tool is designed for:\n- small VPS servers \n- integration into monitoring workflows\n- generating a structured `carstorms.json` output file\n- use as a backend data source for dashboards, APIs, or alerts\n\n## 📦 Features\n\n- Parses NOAA's live `nhc.kmz` feed\n- Filters storms based on wind threshold and proximity\n- Outputs detailed storm info (wind, category, explanation, distance)\n- Supports global mode (no location filtering)\n- Uses a simple, editable JSON configuration file\n- Writes structured JSON and rotating logs\n- Resource-efficient and fast\n\n## 📁 Output\n\nThe script generates:\n- `carstorms.json` – JSON file with storm information\n- `carstorms.log` – log file with warnings, fetch events, and errors\n\nExample `carstorms.json` output:\n\n```json\n{\n  \"name\": \"carstorms.py\",\n  \"timestamp\": \"2025-04-14T20:15:00+00:00\",\n  \"status\": \"ok\",\n  \"message\": \"1 active dangerous storm(s) found.\",\n  \"locations_monitored\": [\"St. John (USVI)\", \"St. Barths\"],\n  \"alert_radius_km\": 150,\n  \"storms\": [\n    {\n      \"name\": \"Hurricane Tammy\",\n      \"wind_kt\": 80,\n      \"wind_kmh\": 148,\n      \"category_description\": \"Category 1 of 5: Weak – Roof and tree damage, power outages likely.\",\n      \"locations\": [\n        {\n          \"location\": \"St. Barths\",\n          \"closest_time\": \"2025-04-15 02:00 AST\",\n          \"distance_km\": 108\n        }\n      ]\n    }\n  ]\n}\n```\n\n---\n\n## 🛠️ Installation\n\n### Requirements\n\n- Python 3.7+\n- requirements.txt\n\nYou can install requirements via pip:\n\n```bash\npip install requirements.txt\n```\n\n### Clone the repository\n\n```bash\ngit clone https://github.com/drhdev/carstorms.git\ncd carstorms\n```\n\n---\n\n## ⚙️ Configuration\n\nAll settings are defined in a single JSON file: `carstorms.config`\n\nExample:\n\n```json\n{\n  \"alert_radius_km\": 150,\n  \"wind_threshold_kt\": 60,\n  \"locations\": {\n    \"St. John (USVI)\": [18.33, -64.73],\n    \"St. Barths\": [17.9, -62.83]\n  },\n  \"webhook_url\": \"https://your-n8n-webhook-url\"\n}\n```\n\n- `alert_radius_km`: Alert radius in kilometers for proximity checks.\n- `wind_threshold_kt`: Minimum wind speed (knots) to consider a storm dangerous.\n- `locations`: Dictionary of monitored locations (name: [lat, lon]).\n- `webhook_url`: (Optional) If set, the script will POST the output JSON to this URL after each run. This is ideal for integration with automation tools like n8n.\n\n### 🌐 Webhook Integration (n8n Example)\n\nTo receive alerts in [n8n](https://n8n.io/):\n1. Create a Webhook node in n8n.\n2. Set the HTTP Method to **POST**.\n3. Copy the webhook URL and paste it as `webhook_url` in your `carstorms.config`.\n4. The script will POST the full output JSON to this webhook after each run.\n\n### 🌍 Global mode\n\nTo track **all active systems globally**, remove or leave `\"locations\"` empty:\n\n```json\n\"locations\": {}\n```\n\n---\n\n## 🚀 Usage\n\nRun manually:\n\n```bash\npython3 carstorms.py\n```\n\nThis updates:\n- `carstorms.json`\n- `carstorms.log`\n\n---\n\n## 🔄 Automate with Cron \u0026 Virtual Environment (Recommended for Ubuntu/Linux)\n\n### 1. Set up a Python virtual environment in your project directory\n\n```bash\ncd ~/python/carstorms\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n- This creates and activates a virtual environment in `~/python/carstorms/venv`.\n- Install dependencies inside the venv for isolation and portability.\n\n### 2. Run the script manually using the venv\n\n```bash\ncd ~/python/carstorms\nsource venv/bin/activate\nvenv/bin/python carstorms.py\n```\n\n### 3. Run the test suite using the venv\n\n```bash\ncd ~/python/carstorms\nsource venv/bin/activate\nvenv/bin/python -m unittest test_carstorms.py -v\n```\n\n### 4. Set up a cron job to run the script every hour at 7 minutes past the hour\n\nEdit your crontab:\n\n```bash\ncrontab -e\n```\n\nAdd this line:\n\n```cron\n7 * * * * cd \"$HOME/python/carstorms\" \u0026\u0026 ./venv/bin/python carstorms.py \u003e\u003e carstorms_cron.log 2\u003e\u00261\n```\n\n- This will run the script at 7 minutes past every hour.\n- All dependencies and the script will use the virtual environment.\n- Output and errors will be appended to `carstorms_cron.log` in the project directory.\n\n---\n\n## 🧪 Testing \u0026 Simulation\n\nYou can run the test suite to:\n- Validate all core logic and config loading.\n- Simulate a hurricane scenario and see the output structure.\n- Ensure the script works with your real `carstorms.config` (all tests use the real config).\n\nTo run all tests:\n\n```bash\npython3 -m unittest test_carstorms.py -v\n```\n\n- The test suite will simulate a hurricane and show the output JSON as it would be sent to your webhook.\n- You can use this to verify your config, webhook integration, and output format.\n\n---\n\n## 📄 License\n\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) – Free as in freedom.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrhdev%2Fcarstorms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrhdev%2Fcarstorms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrhdev%2Fcarstorms/lists"}