V1 API — Combined GB/NL Final Checklist

[braddf]

V1 API — Final Checks Checklist

Note

Current Plan: run through all those relevant to NL first, then we'll circle back and test GB.

Preliminary checks

• all routes work
• all routes have values in them, non empty
• default NL forecast matches analysis dashboard for nl_national
• default NL forecast matches analysis dashboard for nl_national, probabilistic values
• default generation, matches analysis dashboard for nl_national
• we can pull a different model for nl national, and it matches the analysis dashboard
• start and end datetime filters work

API discovery

• List available energy sources
• List available countries, with capacity, centroid, region types, forecast models, and generation observers per country
• List region types for a country, with available forecast models per type
• List generation observers for a country

Regions

• List all regions for a country (no filter)
• Filter regions by type (e.g. national, GSP, province)
• Filter regions by parent (returns direct children)
• Filter regions by name (case-insensitive substring)
• Get detail for a single region by name or national

Forecast data

• Get forecast time series for a single region — default window (now → +48 h)
• Narrow or shift the forecast window with start_utc / end_utc
• Retrieve forecast "as it was known" at a past time (creation_limit_utc)
• Filter to a specific forecast horizon (e.g. 1-hour-ahead only)
• Check when the forecast for a region was last updated
• Get a point-in-time snapshot of forecasts across all regions of a given type (cached 2 min)
• Get forecasts for all regions across a time window in one request — matrix format (pre-warmed cache)
• Narrow the matrix window in-memory without a new backend call
• Filter the matrix to a subset of regions by name

GB national forecast models

• blend — blended model (default for intraday fallback)
• blend_adjust — blend with trend correction (default)
• pvnet_intraday — PVNet v2 intraday
• pvnet_intraday_adjust — PVNet v2 intraday with trend correction
• pvnet_ecmwf — PVNet intraday (ECMWF input only)
• pvnet_ecmwf_adjust — PVNet intraday (ECMWF, trend corrected)
• pvnet_sat — PVNet intraday (satellite input only)
• pvnet_sat_adjust — PVNet intraday (satellite, trend corrected)
• pvnet_ukv — PVNet intraday (Met Office UKV input only)
• pvnet_ukv_adjust — PVNet intraday (Met Office UKV, trend corrected)
• pvnet_day_ahead — PVNet day-ahead
• pvnet_day_ahead_adjust — PVNet day-ahead with trend correction

GB GSP forecast models

• blend (default)
• pvnet_intraday
• pvnet_day_ahead

NL national forecast models

• blend
• blend_adjust (default)
• blend_adjust (explicitly selected)
• ecmwf_mo_sat_uncurtailed
• ecmwf_mo_sat_uncurtailed_adjust

NL province forecast models

• blend
• ecmwf_mo_sat_uncurtailed

GB intraday-only access (read:uk-intraday)

• National: pvnet_intraday and pvnet_intraday_adjust accessible
• National: non-intraday models (e.g. blend) return 403
• GSP: pvnet_intraday accessible
• GSP: non-intraday models (e.g. blend) return 403

Observed generation

GB observers

• pvlive_in_day — in-day estimates (default), per-region time series
• pvlive_in_day — point-in-time snapshot across all GSPs
• pvlive_in_day — period matrix across all GSPs
• pvlive_day_after — finalised day-after values, per-region time series
• pvlive_day_after — point-in-time snapshot across all GSPs
• pvlive_day_after — period matrix across all GSPs

NL observers

• nednl — NED NL estimated generation, per-region time series
• nednl — point-in-time snapshot across all provinces
• nednl — period matrix across all provinces

General generation behaviour

• Narrow or shift the generation window with start_utc / end_utc
• Snapshot resolves the most recent available timestamp automatically when time_utc is omitted
• Narrow the generation matrix window or filter to a subset of regions by name

Cache management

• Period endpoints return 503 + Retry-After: 60 when cache is cold
• Admin can trigger cache re-warm for forecasts (POST .../forecasts/refresh)
• Admin can trigger cache re-warm for generation (POST .../generation/refresh)

Auth & access control

• read:gb grants full GB access
• read:nl grants full NL access
• read:uk-intraday restricts to intraday models only (see GB intraday section above)
• read:trial / read:partner grant access to all countries
• Missing permission returns 403 with a contact address

Validation & errors

• Unknown country → 422
• Unknown region type → 400 with available types listed
• Unknown model for region type → 400 with available models listed
• Region not found → 404
• start_utc more than 1 year in the past → 422
• Requested single forecast window larger than 3 months (92 days) → 400

---