Skip to main content

Migrating to the Core API Platform (v3)

The legacy Point Forecast API (v2) has been deprecated and split into two specialized, high-performance APIs: the Forecast API and the Ocean API. This guide covers exactly how to map your legacy requests to the new format.

1. Domain Separation​

  • Atmospheric Data: Migrates to https://api.weather.metservice.com/forecast/v1/points
  • Marine Data: Migrates to https://api.marine.metservice.com/ocean/v1/points

2. Parameter Mapping​

We have eliminated the "Object Tax" and deeply nested conventions.

Standard Query Parameters:

  • lat ➔ lat (No change)
  • lon ➔ lon (No change)
  • from ➔ from (No change, ISO 8601 UTC)
  • repeat ➔ repeat (No change)
  • models ➔ models (Arrays are now comma-separated style: form instead of repeating query strings)
  • variables ➔ variables (Array syntax mapped to comma-separated)

Renamed/Styled Parameters (snake_case conversion):

  • baseModels ➔ base_models
  • outputFormat ➔ output_format
  • joinModels ➔ join_models
  • cycleLock ➔ cycle_lock

Unchanged Toggles:

  • explain, extrapolate, exclude, kind ➔ Preserved as boolean/string flags.

Time Intervals: Time intervals (e.g. PT15M) now accept simple human-readable strings like 15min and 1h, though standard ISO 8601 strings are still supported natively.

2.1 Informational Endpoints​

The legacy informational endpoints remain available but have been converted to standard JSON and segregated by domain. For example, api.weather.metservice.com.../variables will only return atmospheric variables, while the marine URL returns oceanographic variables.

  • /variables/ ➔ /variables
  • /models/ ➔ /models
  • /units/ ➔ /units
  • /modelsummaries/ ➔ /model_summaries
  • /models/{model} ➔ /models/{model}

2.2 Route Forecasting​

Route forecasting continues to be fully supported in the v3 APIs. To comply with modern API resource naming standards, the paths have been pluralized:

  • POST /route/time ➔ POST /routes/time
  • POST /route/speed ➔ POST /routes/speed

3. The Flat Vector Migration & noData Handling​

You no longer need to parse the separate noDataReasons map or handle parallel arrays. Missing data is handled completely in-line using standard RFC 9457 warnings. If a variable at a specific timestamp is invalid (e.g., an ocean variable over land), the value will be null.

You can check the root-level warnings array to determine why a variable returned null at any given timestamp.

Legacy Structure (v2)​

{
  "wind.speed.at-10m": {
    "values": [5.0, 5.2],
    "noData": [0, 1]
  },
  "noDataReasons": {
    "1": "landMaskError"
  }
}

New Platform Structure (v3)​

{
  "warnings": [
    {
      "type": "https://developer.metservice.com/docs/error-handling/#partial-data-land",
      "title": "Landmask Conflict",
      "detail": "Data is unavailable because the coordinate lies over land.",
      "affected_variables": ["wind_speed_10m"]
    }
  ],
  "timestamps": ["2026-04-17T00:00:00Z", "2026-04-17T01:00:00Z"],
  "variables": {
    "wind_speed_10m": [5.0, null]
  }
}

4. Glass Box Variable Renaming​

All variables have been renamed to snake_case identifying precisely what they measure and at what elevation/depth, keeping your integration standard and simple.

  • wind.speed.at-10m ➔ wind_speed_10m
  • air.temperature.at-2m ➔ air_temperature_2m
  • wave.height ➔ sea_surface_wave_significant_height