Forecasts

Forecasts cover three time horizons: short-term (~15 days), subseasonal (up to 6 weeks), and seasonal (up to 6 months). The current endpoints blend all three into a single continuous timeline; the legacy endpoints expose each horizon separately.

Current

ClimateAI's forecast system blends the three horizons into one continuous timeline using an AI-driven stitching process. One call to /v2/forecast returns a consistent forecast from today through ~6 months out, with no manual splicing across timescale boundaries. Supersedes the three legacy endpoints /v1/forecast/short-term, /v1/forecast/subseasonal, and /v1/forecast/seasonal.

Raw runs

GET /v2/forecast

Returns raw ensemble members from the blended forecast. Use this when you want full control over the distribution — e.g. computing your own risk metrics across the ~31 ensemble members.

Parameter	Type	Required	Description
lat	float	yes	Latitude (−90 to 90)
lon	float	yes	Longitude (−180 to 180)
var	string	no	Variable(s). Uses the same slugs as the legacy endpoints (temp_mean, precipitation, etc.). Single (temp_mean), comma-separated (temp_mean,precipitation), or repeated (?var=temp_mean&var=precipitation).
start_date	string	no	YYYY-MM-DD
end_date	string	no	YYYY-MM-DD
use_downscaling	bool	no	Request downscaled (1 km / 0.0083°) data when available (default true). Has effect only if the API key is provisioned for 1 km downscaling and only for downscalable variables (temperature trio + solar radiation). Contact your account manager to enable 1 km on your key — see Variables, Units & Resolution.

Statistics

GET /v2/forecast/statistics

Returns mean and configurable quantiles over the ensemble, with optional temporal aggregation.

Parameter	Type	Required	Description
lat	float	yes	Latitude (−90 to 90)
lon	float	yes	Longitude (−180 to 180)
var	string	no	Variable(s) — same slugs and forms as /v2/forecast.
start_date	string	no	YYYY-MM-DD
end_date	string	no	YYYY-MM-DD
use_downscaling	bool	no	Same as on /v2/forecast above: request downscaled data (default true); effective only on keys provisioned for 1 km.
statistics	string	no	Comma-separated quantiles in [0, 1] (default 0.05,0.25,0.50,0.75,0.95)
granularity	string	no	daily (default), weekly, or monthly.

Aggregation behavior:

• daily — returns daily statistics keyed by date ("2025-01-15").

• weekly — returns ISO weeks ("2025-W03") running Monday–Sunday. Only complete weeks are included.

• monthly — returns calendar months ("2025-01"). Only complete months are included.

Aggregation is variable-aware. Daily values are first combined within the window before quantiles are computed:

• Precipitation and evapotranspiration are summed within the window.

• Temperature, humidity, wind, and other intensive variables are averaged within the window.

For example, weekly precipitation with 31 ensemble members: each member's 7 daily values are summed, then quantiles are computed from the 31 summed values.

Legacy

The legacy API exposes each horizon as a separate endpoint. None accept date-range parameters — each call returns the current forecast for the endpoint's predefined horizon. Each returns a fixed set of quantiles (q05, q25, q50, q75, q95) and the variables available for that scope. The three endpoints are independent products — they don't combine into a continuous timeline cleanly: granularities differ (daily-only, daily+weekly, daily+monthly), and weekly/monthly responses add tercile probabilities that the daily ones don't have. Customers who need a unified short-to-seasonal forecast should use the Statistics endpoint above instead.

By lat/lon

Path	Granularity	Horizon	Notes
GET /v1/forecast/short-term	daily	~15 days	Max Wind Gust available only for the first 10 days.
GET /v1/forecast/subseasonal	daily, weekly	weeks 2–6	Weekly responses include probabilistic terciles in addition to quantiles. Drops Max Wind Speed and Max Wind Gust.
GET /v1/forecast/seasonal	daily, monthly	months 1–6	Monthly responses include probabilistic terciles in addition to quantiles. Drops Max Wind Speed and Max Wind Gust.

By location ID

Stored-location variants of the three coordinate endpoints. Same responses and constraints, but addressed by a server-side location ID instead of lat/lon.

Path	Horizon
GET /v1/forecast/short-term/location/{id}	~15 days
GET /v1/forecast/subseasonal/location/{id}	weeks 2–6
GET /v1/forecast/seasonal/location/{id}	months 1–6

See Variables, Units & Resolution for the per-endpoint variable availability matrix.

---

History

Historical weather data — what actually happened at a given location, day by day. The current endpoint covers 30+ years (1995–present); the legacy endpoints cover a rolling 12 months.

Current

By lat/lon

GET /v2/history

30+ years of historical data (1995–present), backed by ERA5 with automatic gap-fill for the ERA5-to-present lag. Data is fetched on demand if not yet cached — there's no pre-loading step. Supersedes the legacy /v1/history endpoint, which only covers the last 366 days.

Parameter	Type	Required	Description
lat	float	yes	Latitude (−90 to 90)
lon	float	yes	Longitude (−180 to 180)
var	string	no	Variable(s). Defaults to all non-derived variables.
start_date	string	no	YYYY-MM-DD
end_date	string	no	YYYY-MM-DD
granularity	string	no	daily (default), weekly (ISO weeks), or monthly
use_downscaling	bool	no	Request downscaled (1 km / 0.0083°) data (default true). Effective only if the API key is provisioned for 1 km downscaling, and only for downscalable variables (temperature trio + solar radiation). See Variables, Units & Resolution.

Aggregation is variable-aware: precipitation/evaporation are summed; temperature/humidity/wind are averaged.

Legacy

By lat/lon

GET /v1/history

Returns a rolling 12 months (~366 days) of observed/reanalysis data at daily granularity, fixed. Query parameters are limited to lat, lon, var — there is no date-range or granularity control. Some locations may return errors if they haven't been pre-loaded.

By location ID

GET /v1/history/location/{id}

Stored-location variant of /history: same response, same constraints, but addressed by a server-side location ID instead of lat/lon coordinates.

---

Climatology

Long-term statistical baselines computed from 30 years of historical data — the distribution of what's typical at a given location and time of year. Useful as context for forecasts (is today's temperature unusual?) and for long-term planning where year-to-year variability matters more than any specific year.

Legacy

By lat/lon

GET /v1/climatology

Long-term statistical distributions computed from a fixed 30-year reference period (1993–2022) of historical data. The reference window is fixed and refreshed periodically by the ClimateAI team — it does not roll forward with each request. Returns the fixed quantile set [0.05, 0.25, 0.50, 0.75, 0.95] only — no mean, no terciles — at daily, weekly, or monthly granularity.

Parameter	Type	Required	Description
lat	string	yes	Latitude (−90 to 90)
lon	string	yes	Longitude (−180 to 180)
var	string	no	Variable slug (see Variables, Units & Resolution)
granularity	string	no	daily, weekly, or monthly

By location ID

GET /v1/climatology/location/{id}

Stored-location variant. Same parameters as above except lat/lon are replaced by a server-side location ID in the path.

---

Coming soon

The following capabilities are in development. Paths and parameters are not yet finalized.

Flexible Climatology

A more flexible replacement for the legacy /v1/climatology endpoint. Choose the historical reference period (instead of being locked to 1993–2022), request custom quantiles, select variables, and pick daily, weekly, or monthly granularity.

Growing Degree Days (GDD)

Crop-relevant heat accumulation computed from historical and forecast temperature, plus cross-year statistics and multi-location/multi-planting stage tracking. Built on the same data pipelines as History and Forecasts.

Alerts

Subscribe to threshold-based weather events (e.g. "notify when forecast precipitation exceeds X mm over the next 5 days at this location").