Migration

A note for existing customers. The legacy endpoints are served at both the versioned form (/v1/forecast/short-term, etc.) and the original unversioned form (/forecast/short-term, etc.) — your current integration keeps working as-is. The /v1/ prefix is the canonical form going forward; the unprefixed form is an alias maintained for backward compatibility.

Forecasts: from three endpoints to stitched

Each legacy forecast call has a direct equivalent on /v2/forecast/statistics. Pick the date range and granularity that matches what you were getting before.

What you gain by migrating to current endpoints

• A single continuous timeline from today through ~6 months at a single granularity of your choice — something the three legacy endpoints don't combine into cleanly.

• Custom quantiles (any value in [0, 1]) instead of the fixed five.

• Variable selection (?var=temp_mean&var=precipitation) instead of every variable for the scope.

• Access to raw ensemble members via /v2/forecast when you need full distributional control.

• Date-range control (start_date, end_date) — legacy forecast endpoints don't accept these.

• Forecast traceability in the response: init_time (when the model run was issued), version (model/dataset version), generation (unique generation ID).

• Explicit snapping: response shows location.requested alongside location.closest_location so the snap-to-grid is transparent.

Only on legacy

A couple of legacy features don't have a current equivalent yet. If your integration depends on them, stay on the legacy endpoints.

• Native tercile probabilities in the response. Legacy subseasonal-weekly and seasonal-monthly include [0.00–0.33, 0.33–0.67, 0.67–1.0] next to the quantiles. The stitched-statistics endpoint returns mean + quantiles only, and there's no clean client-side recompute (terciles need climatology's 33rd and 67th percentiles, and /v1/climatology only exposes [0.05, 0.25, 0.50, 0.75, 0.95]). We're measuring legacy tercile usage before deciding whether to expose terciles natively on the current endpoint.

• Stored-location ID variant. /v2/forecast/location/{id} does not exist; current endpoints only accept lat/lon. If you currently call /v1/forecast/seasonal/location/{id} etc., you'll need to pass coordinates instead.

Requests

Legacy

Three independent endpoints, one per horizon:

GET /v1/forecast/short-term?lat=40&lon=-89&var=temp_mean       # daily, ~15 days

GET /v1/forecast/subseasonal?lat=40&lon=-89&var=temp_mean      # daily/weekly, weeks 2–6

GET /v1/forecast/seasonal?lat=40&lon=-89&var=temp_mean         # daily/monthly, months 1–6

Current

One endpoint, parameterized by date range and granularity. Replace each legacy call with the matching one below:

# Short-term equivalent (next ~15 days, daily)
GET /v2/forecast/statistics?lat=40&lon=-89&var=temp_mean&end_date=<today+15d>&granularity=daily

# Subseasonal equivalent (weeks 2–6, weekly)
GET /v2/forecast/statistics?lat=40&lon=-89&var=temp_mean&start_date=<today+14d>&end_date=<today+42d>&granularity=weekly

# Seasonal equivalent (months 1–6, monthly)
GET /v2/forecast/statistics?lat=40&lon=-89&var=temp_mean&start_date=<today+30d>&end_date=<today+180d>&granularity=monthly

Bonus: a new capability. Beyond the one-for-one replacements above, the current endpoint can return the entire short-to-seasonal timeline at a single granularity in one call — something the legacy endpoints can't do, since each enforces its own granularity:

GET /v2/forecast/statistics?lat=40&lon=-89&var=temp_mean&end_date=<today+180d>&granularity=weekly

Responses

Structure

Legacy returns { meta: {...}, data: [...] } where data is an array of per-date entries (attributes.<var> under each). Current returns flat top-level metadata plus a variables object keyed by variable name, with dates as keys inside variables.<var>.statistics (e.g. "2025-01-01": { "mean": ..., "q05": ..., ... }).

Statistic field renames

New metadata fields

Current responses add:

• init_time — when the forecast run was issued

• version — model/dataset version

• generation — unique generation ID

• location.requested vs location.closest_location — makes snap-to-grid explicit

History: 1 year → 30+ years

What you gain by migrating to current endpoints

• 30+ years of coverage (1995–present), not 1 year.

• Date-range control via start_date / end_date (legacy /v1/history doesn't accept these).

• Automatic ERA5 fetch — no "location not ingested" errors.

• Variable-aware weekly/monthly aggregation built in.

• ~70–80% smaller responses thanks to the date-keyed format.

Only on legacy

• Stored-location ID variant. /v2/history/location/{id} does not exist. If you currently call /v1/history/location/{id}, you'll need to pass coordinates instead. Otherwise nothing functional is lost — locations were already snapped to the 0.25° grid on legacy /v1/history.

Requests

Legacy

GET /v1/history?lat=40&lon=-89&var=temp_mean
# Last ~366 days, daily granularity, no date-range control.

(Plus the stored-location variant: GET /v1/history/location/{id} — same response shape.)

Current

GET /v2/history?lat=40&lon=-89&var=temp_mean&start_date=1995-01-01&end_date=2025-12-31&granularity=monthly
# 30+ years, auto-fetched on first request, with daily/weekly/monthly granularity.

Responses

The response shape changes the same way as for Forecasts. One thing to update in your parser:

• Structure. Legacy returns { meta: {...}, data: [...] } with data as an array of per-date entries (attributes.<var>.values under each). Current returns a per-variable object with dates as keys, e.g. data.<var>.values = { "2024-01-01": 11.4, "2024-01-02": 12.1, ... }. ~70–80% smaller payload as a result.

Climatology

No migration available today — climatology lives only on the legacy endpoint. A new endpoint with a flexible reference period, custom quantiles, granularity, and variable selection is coming soon.