API Reference

WeatherMax API

Base URL https://api.weathermax.app/api. All responses are JSON. Create a key in your dashboard.

Authentication

Send your key on every request. Either header works:

X-API-Key: wmx_live_your_key_here
# or
Authorization: Bearer wmx_live_your_key_here

Example:

curl "https://api.weathermax.app/api/weather?lat=40.71&lon=-74.01" \
  -H "X-API-Key: wmx_live_your_key_here"

On Windows PowerShell use curl.exe — plain curlis an alias for Invoke-WebRequest and won’t accept -H:

curl.exe "https://api.weathermax.app/api/weather?lat=40.71&lon=-74.01" -H "X-API-Key: wmx_live_your_key_here"

const res = await fetch(
  "https://api.weathermax.app/api/weather?lat=40.71&lon=-74.01",
  { headers: { "X-API-Key": process.env.WMX_API_KEY } }
);
const data = await res.json();

Endpoints

Weather

GET/weather

Full weather bundle: current, hourly, 7-day forecast, AQI, pollen, alerts.

Params: lat, lon, city?, state?, countryCode?

GET/weather/quick

Minimal fast payload — current conditions plus sunrise/sunset.

Params: lat, lon

POST/weather/refresh

Lightweight refresh (forecast, hourly and alerts only).

Params: JSON body with location

Alerts

GET/alerts

Active weather alerts for a point. US and Canada only.

Params: lat, lon, countryCode?

GET/national-alerts

Summarized active US Extreme/Severe alerts.

Params: —

GET/national-alerts/geo

National alerts with polygon geometry (GeoJSON).

Params: —

Location

GET/geocode/search

Forward geocoding — place or ZIP to coordinates and labels.

Params: q

GET/geocode/reverse

Reverse geocoding — coordinates to city and state.

Params: lat, lon

GET/ipweather

Weather for the caller's IP-based location (US).

Params: —

Environment

GET/astro

Sun and moon rise/set, moon phase, UV index.

Params: lat, lon, date?

GET/lightning/nearby

Recent cloud-to-ground lightning strikes near a point.

Params: lat, lon, radiusKm?, minutes?

GET/lightpollution

Light-pollution level for a point (NASA VIIRS night-lights) as a 0–100% scale with a label. US only.

Params: lat, lon

GET/cams

Nearby traffic and weather cameras.

Params: lat, lon, radius?, limit?

Rate limits & quotas

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Policy. On a 429, honour Retry-After rather than retrying immediately.

Plan	Monthly quota	Rate limit
Free	5,000 / mo	30 / min
Starter	100,000 / mo	120 / min
Pro	2,000,000 / mo	600 / min

Errors

401	Missing, invalid, or suspended API key.
403	Request rejected — no credential and no trusted origin.
429	Rate limit or monthly quota exceeded — see Retry-After.
400	Missing or invalid parameters (for example lat/lon).
501	Requested outside supported coverage (US and Canada).
502 / 504	Upstream weather source temporarily unavailable — retry.

Coverage

Forecasts and alerts cover the United States and Canada. US alerts come from the National Weather Service and Canadian alerts from Environment Canada — both authoritative sources rather than model output. Requests for points outside that area return 501 on the alerts endpoint.

Need a key? See plans & get access →