vertical-weather

TypeScript and JavaScript client for the Vertical Weather API. Ask for wind, temperature, pressure, humidity and air density at the heights you choose above a point, from NOAA's GFS model.

npm install vertical-weather

Needs Node 22.18 or later, and has no dependencies. Get an API key from the dashboard; the API is in free beta.

Example

import { getProfile } from "vertical-weather";

const profile = await getProfile(process.env.VERTICAL_WEATHER_API_KEY!, {
  latitude: 35.052,
  longitude: -117.985,
  time: "2026-10-03T18:00:00Z",
  altitudes_m: [1000, 2000, 5000],
  altitude_reference: "agl",
});
for (const level of profile.levels) {
  console.log(level.altitude_agl_m, level.wind_speed_ms, level.wind_direction_deg);
}

The package ships type declarations. PROFILE_UNITS names the unit of every level field.

Keep the key on a server. Don't ship it in a mobile app, browser code or a public repository.

Reading the results

• Heights are metres above ground (agl) or above mean sea level (msl). Ground is the model's terrain unless you pass ground_elevation_m_msl.
• Wind u points east and v north, in m/s. wind_direction_deg is where the wind comes from, clockwise from true north; 0 at zero speed means calm.
• valid_time is the model time actually used and can differ from the time you asked for. provenance names the model run and grid point.
• Relative humidity can be above 100%.

Options

The third argument:

| Option | Default | Meaning | | --- | --- | --- | | baseUrl | https://api.verticalweather.com | API address | | timeoutMs | 30000 | Time limit per attempt (1 to 300000) | | maxElapsedMs | 30000 | Time limit for the whole call, including waits | | maxAttempts | 1 | Up to 5; retries only 429 rate_limited and 503 source_busy |

Retries wait for Retry-After when the server sends it. Timeouts and network errors are never retried, since the server may already have done the work.

Errors

Every failure throws AtmosphereError with code, status, requestId, retryAfterMs and coverage.

| Code | What to do | | --- | --- | | unauthorized (401) | Check the key. | | profile_out_of_range (409) | A height is outside the model column; coverage has the available range. | | rate_limited (429) | Wait retryAfterMs, or allow retries. | | source_busy (503) | Try again shortly. | | timeout, network_error | The request may or may not have completed. | | invalid_response, unexpected_status | The response didn't match the contract. | | invalid_request, missing_key, invalid_url, invalid_options | Fix the input. |

The client checks every response against the request (heights, time, ground, coverage, derived wind) and never fills in missing values. It follows no redirects and never logs your key.

Links

• Guides: https://verticalweather.com
• Support: [email protected]

MIT license.