HAB Predictor

Overview

HAB Predictor is a Node.js application designed to monitor and predict the landing location of weather balloons based on Global Forecast System (GFS) data from https://weather.uwyo.edu/upperair/balloon_traj.html. The application calculates the distance from a base location to the predicted landing site and determines whether the landing site is on water or land, distance, etc. If certain conditions are met, it sends an email notification with the prediction results, including a static map image generated using the Mapbox Static Images API.

Features

Automatically fetches weather balloon trajectory data.
Calculates the distance between the base location and the predicted landing site.
Determines if the predicted landing site is on water or land using the isitwater API.
Generates static map images using the Mapbox Static Images API.
Sends email notifications based on the prediction results.
Configurable via environment variables.
Scheduled to run daily at 11:00 AM UTC.

Prerequisites

Node.js (v14.x or later)
npm (v6.x or later)
pm2 (for running the application as a background process)
isitwater API key (free tier)
Mapbox Static Images API key (free tier)
Mailgun API key

Installation

Clone the repository:

git clone https://github.com/your-username/weather-balloon-tracker.git
cd weather-balloon-tracker

Install dependencies:
```
npm install
```
Create and configure the .env file:
```
cp .env.example .env
```
Edit the .env file with your preferred editor and add the necessary API keys and configuration variables.
Run the application:

To run the application manually:
```
npm start
```

Environment variables

The application uses environment variables to configure its behavior. Below is an explanation of each variable found in the .env file:

App settings

LAUNCH_LAT: Latitude of the balloon launch site. This value is used to determine the starting point of the balloon's trajectory.
LAUNCH_LON: Longitude of the balloon launch site. This value is paired with LAUNCH_LAT to pinpoint the exact launch location.
BASE_LAT: Latitude of your base location. The application calculates the distance between this point and the predicted landing site.
BASE_LON: Longitude of your base location. Used with BASE_LAT to calculate the distance to the predicted landing site.
MAX_DISTANCE: The maximum distance (in kilometers) you're willing to travel to recover the balloon. If the predicted landing site is within this distance, it's considered a "matching" result.
BALLOON_CEILING: The maximum altitude (in meters) the balloon is expected to reach. This value is used in the trajectory calculations.
CITY: The name of the city where the base location is situated. This is used for informational purposes in notifications.
TIMEZONE: The timezone of your base location, used to adjust the timing of notifications and calculations relative to your local time.
NOTIFICATION_EMAILS: A comma-separated list of email addresses that will receive the notifications. Ensure you provide a valid email address.
SEND_NOTIFICATIONS: Specifies when to send notifications. Set to all to send notifications regardless of the results, or matching to send notifications only when the predicted landing site is within the MAX_DISTANCE and not over water.

Scheduling

SCHEDULE_TIME: The time of day (in 24-hour format) when the application should run, in UTC. For example, 11:00 means the application will run at 11:00 UTC.

Mailgun for email notifications

MAILGUN_DOMAIN: The domain you have configured with Mailgun for sending emails. Ensure this is a valid domain associated with your Mailgun account.
MAILGUN_API_KEY: Your Mailgun API key, which is used to authenticate your requests to send emails. Keep this key secure.

RapidAPI for `isitwater.com`

RAPIDAPI_HOST: The host for the isitwater.com API on RapidAPI.
RAPIDAPI_KEY: Your RapidAPI key for accessing the isitwater.com API. This key is used to authenticate your requests to check whether the predicted landing site is over water.

Mapbox for map screenshots

MAPBOXAPI_KEY: Your Mapbox API key used to generate static map images. This key is required to authenticate requests to the Mapbox Static Images API.
MAPBOX_IMAGE_WIDTH: The width (in pixels) of the static map image generated by the Mapbox API. Adjust this value to change the size of the image.
MAPBOX_IMAGE_HEIGHT: The height (in pixels) of the static map image. This determines how tall the image will be.
MAPBOX_IMAGE_ZOOM: The zoom level for the static map image. A higher value means more zoomed-in. Typical values range from 0 (whole world) to 22 (buildings).

Test Mode

TEST_MODE: Set this to true to run the application in test mode, which will execute the script immediately without waiting for the scheduled time. This is useful for debugging and verifying the setup.

Deploy on Railway

You can test the app free on railway. Just create an account and complete your environment variables.

Deploy on custom machine/VPS

To keep the application running in the background and automatically restart on failures, you can use pm2.

Install pm2 globally:
```
npm install -g pm2
```

Start the application with pm2:

pm2 start index.js --name "weather-balloon-predictor"

Save the pm2 process list:
```
pm2 save
```
Set pm2 to start on system boot:
```
pm2 startup
```

Schedule

The application is scheduled to run daily at 11:00 AM UTC. This schedule is defined in the script and will trigger the execution of the job at the specified time.

Contributing

If you want to contribute to this project, please fork the repository, create a new branch, and submit a pull request. Contributions are welcome!

License

This project is licensed under the GNU General Public License v3.0.

danielcharrua/hab-predictor