External data¶

Neptoon can attach external data that are needed for CRNS processing and diagnostics. The most common sources are:

NMDB.eu neutron-monitor data for incoming-radiation corrections.
DWD weather-station data for pressure, temperature, relative humidity, precipitation and solar-radiation context in Germany.
external_meteo providers for ordered public meteorological fallback data, including DWD.
remote_sensing products for gridded Earth-observation reference series such as vegetation indices, biomass and land cover. See remote-sensing reference data.

External data are attached before the main correction and soil-moisture workflow uses the required columns. Local sensor columns remain the preferred source unless a provider is configured to overwrite them.

NMDB neutron-monitor data¶

The NMDB.eu database collates high-energy neutron-monitor measurements from stations around the world. Neptoon can download these data directly and use them for incoming-radiation correction.

Standalone NMDB downloader¶

from neptoon import NMDBDataDownloader

df = NMDBDataDownloader.download(
    "JUNG",
    "2022-01-01",
    "2022-01-10",
    "10Min",
)

The downloader returns a UTC-indexed pandas DataFrame with a count column. It reuses Neptoon's NMDB cache by default; pass use_cache=False for a fresh request or cache_dir=... to choose the cache location. Integer minute resolutions and pandas-compatible intervals such as "10Min" or "1h" are accepted. When no explicit cache is supplied, NEPTOON_CACHE_DIR can override the platform cache location. An explicitly configured override must be writable; Neptoon surfaces an error rather than silently using a different cache. If no override is set and the normal platform cache is unavailable or read-only, Neptoon logs a warning and falls back to <system-temp>/neptoon/cache; cache data may therefore be ephemeral in locked-down containers.

The existing neptoon.external.fetch_nmdb_data(...) function remains available as a cache-free compatibility API.

The same downloader is available from the command line:

neptoon nmdb download \
  --station JUNG \
  --start-date 2022-01-01 \
  --end-date 2022-01-10 \
  --resolution 10min \
  --cache-dir ./cache/nmdb \
  --output nmdb_jung.csv

The CLI caches downloads by default. Use --no-cache to force a fresh, cache-free request. --resolution accepts whole-minute values either as a number of minutes or as a pandas-compatible duration, including 1, 10, 10min, 60min, 1h, and 1d. Sub-minute intervals are rejected because NMDB requests are minute based. Use --no-cache-fallback when a failed refresh must not return already cached observations.

To list built-in reference stations:

neptoon nmdb stations

Attach NMDB data in Python¶

data_hub.attach_nmdb_data(
    station="JUNG",
    resolution="60",
    nmdb_table="revori",
)

Common station codes include AATB, INVK, JUNG, KERG, KIEL, MXCO, NEWK, OULU, PSNM, SOPO, TERA, and THUL. Use the revised original table revori unless you have a reason to use another NMDB table.

Meteorological source order¶

Meteorological inputs such as pressure, air temperature and relative humidity can be provided by local columns, DWD, or ordered external_meteo fallback providers. Generic providers are applied in YAML order while preserving local values by default. The legacy dedicated dwd block is a separate post-alignment step; provider: dwd instead makes DWD participate directly in the generic provider order.

By default, DWD and external_meteo fill missing local values only. Set prefer_dwd_values: true or prefer_external_values: true only when provider values should overwrite local measurements where both are available.

Interpolation is separate from external filling

Provider attachment fills or adds values from the provider. The later missing_value_interpolation step is a separate sensor-config option. Keep this distinction clear when diagnosing gaps: provider values explain source provenance, interpolation explains synthetic gap filling.

DWD weather data¶

DWD support is intended for German stations and nearby sites where DWD observations are appropriate. It can fill missing pressure, temperature and relative humidity and can attach precipitation or solar-radiation columns for diagnostics and report plots.

DWD from column markers¶

A convenient way to request DWD filling is to use the special marker DWD in the meteorological column lists. This enables the DWD configuration automatically for the requested variables.

time_series_data:
  key_column_info:
    pressure_columns: [DWD]
    temperature_columns: [DWD]
    relative_humidity_columns: [DWD]

You can still add a dwd block to control station selection, cache and overwrite behaviour:

dwd:
  enabled: true
  station: nearest
  max_distance_km: 100
  request_timeout: 30
  cache_dir: ./cache/dwd
  use_cache: true
  max_nearest_timedelta: 1h
  fill_pressure: true
  fill_temperature: true
  fill_relative_humidity: true
  include_precipitation: false
  include_solar_radiation: false
  precipitation_daily_fallback: true
  precipitation_product: auto
  prefer_dwd_values: false
  required: false

station: nearest selects the nearest DWD station that can provide the requested product. Use an explicit DWD station id when you need exact reproducibility or a manually reviewed station choice.

DWD through the generic provider path¶

DWD can alternatively participate in the normal ordered provider chain. This is useful when Germany-specific station data should be tried at a particular position among other fallbacks rather than in the separate post-alignment DWD step. The generic route delegates to the same DWD CDC implementation.

external_meteo:
  - enabled: true
    provider: dwd
    station: nearest
    product: hourly
    max_distance_km: 100
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: false
    prefer_external_values: false
    required: false
    options:
      dwd_request_retries: 3
      dwd_precipitation_daily_fallback: true
      dwd_precipitation_product: null

prefer_external_values is the generic equivalent of prefer_dwd_values. The DWD-specific options are optional; omitting them uses the same safe defaults as the dedicated integration. Do not enable the same DWD source in both paths unless that duplication is deliberate.

DWD configuration reference¶

Option	Default	Description
`enabled`	`false`	Enables DWD attachment. This can also be turned on automatically by `DWD` column markers.
`station`	`nearest`	DWD station id or `nearest`. Numeric ids are normalised to five digits.
`max_distance_km`	`null`	Optional maximum nearest-station distance. If no station is within the limit, the provider cannot fill data.
`request_timeout`	`30`	HTTPS timeout in seconds.
`cache_dir`	`null`	Optional cache directory for downloaded DWD products. Relative YAML paths resolve relative to the config file.
`use_cache`	`true`	Reuse downloaded DWD products when possible and write new downloads to cache.
`max_nearest_timedelta`	`1h`	Maximum time offset allowed when aligning provider values to CRNS timestamps. Use a pandas-compatible timedelta string.
`fill_pressure`	`true`	Fill missing `air_pressure` values from DWD pressure data.
`fill_temperature`	`true`	Fill missing `air_temperature` values from DWD temperature data.
`fill_relative_humidity`	`true`	Fill missing `air_relative_humidity` values from DWD humidity data.
`include_precipitation`	`false`	Attach DWD precipitation as an additional weather/report column.
`include_solar_radiation`	`false`	Attach DWD solar/global-radiation data as an additional weather/report column.
`precipitation_daily_fallback`	`true`	Fall back to daily precipitation products when hourly precipitation cannot be downloaded or parsed.
`dwd.precipitation_product` / `precipitation_product`	`auto`	Manual precipitation product. Supported values are `auto`, `hourly`, `hourly_rr`, `daily`, `daily_rr`, `daily_more_precip`, and `daily_kl`.
`prefer_dwd_values`	`false`	If `true`, DWD overwrites local values where DWD values exist. If `false`, DWD only fills local gaps.
`required`	`false`	If `true`, DWD download/parse/attachment failures abort the pipeline. If `false`, processing continues where possible.

DWD station lookup CLI¶

Use the station lookup before writing a production config:

neptoon dwd-stations --lat 51.369597 --lon 12.557120 \
  --variables pressure,temperature,relative_humidity \
  --max-distance-km 100 \
  --limit 10

Write the full table to CSV when you want to review candidates:

neptoon dwd-stations --lat 51.369597 --lon 12.557120 \
  --variables pressure,temperature \
  --output dwd_station_candidates.csv

Supported --variables names include pressure, temperature, relative humidity, precipitation and solar radiation. Run neptoon dwd-stations --help to see the exact names supported by your installed version.

DWD provenance columns¶

When DWD data are attached, Neptoon also keeps provenance information where available. Typical columns include station identifiers, station names, distances and source-product labels, for example:

dwd_station_id
dwd_station_name
dwd_station_distance_km
dwd_pressure_source_product
dwd_pressure_source_column
dwd_temperature_source_product
dwd_temperature_source_column
dwd_relative_humidity_source_product
dwd_relative_humidity_source_column
dwd_precipitation_station_id
dwd_precipitation_station_name
dwd_precipitation_station_distance_km

Exact provenance columns depend on the requested variables and available DWD products. The meteorological source columns also record when a provider filled a value, for example dwd:<product-label>.

`external_meteo` providers¶

For a compact comparison of every included meteorological provider, country/coverage, credentials, selection mode, and canonical variable support, see the Meteorological provider overview.

Use external_meteo for ordered public meteorological data, including DWD when desired. Multiple providers can be listed; they are applied in YAML order. This makes it possible to prefer a local national provider first and then fall back to a global gridded provider.

external_meteo:
  - enabled: true
    provider: open_meteo
    station: nearest
    product: hourly
    max_distance_km: null
    request_timeout: 30
    cache_dir: ./cache/open_meteo
    use_cache: true
    max_nearest_timedelta: 1h
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: false
    include_wind_speed: false
    include_reference_et0: false
    prefer_external_values: false
    required: false

  - enabled: true
    provider: meteostat
    station: nearest
    product: hourly
    max_distance_km: 100
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true

Provider names and products¶

Supported canonical provider names are:

Provider	Supported product	Typical use	Notes
`open_meteo`	`hourly`	Global gridded archive fallback.	Token-free Open-Meteo archive adapter.
`era5_open_meteo`	`hourly`	ERA5 via Open-Meteo.	Alias `era5`.
`era5_land_open_meteo`	`hourly`	ERA5-Land via Open-Meteo.	Alias `era5_land`.
`nasa_power`	`hourly`	NASA POWER global gridded point meteorology.	Token-free; requests UTC hourly data directly from POWER.
`meteostat`	`hourly`	Global station data.	No true GHI product in this adapter.
`noaa_isd`	`hourly`	NOAA Integrated Surface Database.	Good station fallback for pressure/temperature/humidity/precipitation where available.
`noaa_ghcn_daily`	`daily`	NOAA GHCN-Daily.	Daily only; broad coverage for precipitation/temperature.
`noaa_uscrn`	`hourly` or `daily`	NOAA US Climate Reference Network.	High-quality US reference stations.
`noaa_nws`	`hourly`	NOAA/NWS `api.weather.gov` surface observations.	Token-free; requires an identifying User-Agent. Current surface-observation coverage is primarily CONUS.
`inmet`	`hourly`	Brazilian INMET automatic SYNOP stations.	Token-free WIS2/OGC API with WIGOS station metadata.
`jma_amedas`	`hourly`	Japan JMA AMeDAS recent observations.	Token-free public web feed with limited remote retention; local JSON is supported for pinned/older runs.
`eobs`	`daily`	E-OBS European gridded data.	Local E-OBS files are required by the config validator.
`aemet`	`daily`	AEMET OpenData climatological station observations for Spain.	Requires an AEMET API key; supports explicit or nearest station selection.
`meteoswiss`	`hourly`	Swiss station/open-data files.	Uses local files or configured open-data URL/STAC collection.
`knmi`	`hourly` or `daily`	Dutch station observations.	Uses local files or KNMI Data Platform settings.
`meteo_france`	`hourly` or `daily`	Météo-France/DPClim.	Local files or configured API; nearest station benefits from a station catalog.
`chmi`	`hourly` or `daily`	Czech Hydrometeorological Institute (ČHMÚ/CHMI) station observations.	Token-free CHMI climate Open Data; nearest-station selection uses WIGOS station metadata.
`arso`	`hourly` or `daily`	Slovenian Environment Agency (ARSO / meteo.si) automatic-station observations.	Token-free public XML; nearest-station selection uses ARSO station coordinates. The public per-station history is a rolling recent window.
`rmi_belgium`	`hourly`	Belgian RMI/KMI automatic weather stations.	Public token-free WFS; aliases: `kmi_be`, `rmi`, `irm`.
`vmm_waterinfo`	`hourly`	Flemish VMM meteorological stations.	Anonymous KIWIS access for pressure, temperature, relative humidity and precipitation; aliases: `vmm`, `waterinfo`, `waterinfo_be`.
`met_office_datahub`	`hourly`	UK Met Office Weather DataHub.	Local files or API key + API URL. No true solar-radiation product in this adapter.
`fmi`	`hourly`	Finnish Meteorological Institute.	Token-free URL/file/WFS adapter.
`smhi`	`hourly`	Swedish Meteorological and Hydrological Institute observations.	Token-free metobs API with nearest-station selection across requested variables; aliases include `smhi_open_data`.
`imgw`	`hourly`	Polish IMGW-PIB synoptic observations.	Token-free public synop API; pressure, temperature, RH and wind are mapped. Local snapshots support reproducible runs.
`met_eireann`	`hourly`	Met Éireann Open Data.	Token-free 60-minute OGC EDR/CoverageJSON observations with nearest-station selection.
`ipma`	`hourly`	Portugal IPMA Open Data.	Token-free latest-24-hour station observations with `station: nearest`; aliases include `ipma_open_data`.
`eccc_geomet`	`hourly`	Environment and Climate Change Canada GeoMet.	Token-free OGC API/file adapter.
`bom`	`hourly`	Australian Bureau of Meteorology.	`station: nearest` uses the national station catalog and public rolling 72-hour JSON observations; explicit URL/files remain available for archives.
`geosphere_austria`	`hourly`	GeoSphere Austria quality-checked station data.	Token-free `klima-v2-1h` API with nearest-station selection; aliases include `geosphere`, `geosphere_at` and `zamg`.
`frost`	`hourly`	MET Norway Frost observations.	Nearest-station historical observations; requires a Frost client id for API access. Aliases include `met_norway` and `metno_frost`.
`dmi`	`hourly`	Danish Meteorological Institute Open Data.	Token-free Meteorological Observation API with nearest-station selection; alias `dmi_open_data`.
`dwd`	`hourly`	German DWD Climate Data Center station observations.	Token-free; reuses the dedicated DWD CDC implementation and supports nearest-station selection.

Provider aliases such as openmeteo, era5, power, nasa_power_hourly, aemet_open_data, ghcn, ghcnd, uscrn, nws, weather_gov, brazil_inmet, amedas, jma, meteofrance, kmi_be, rmi, irm, vmm, waterinfo, waterinfo_be, metoffice, swissmetnet, eccc, smhi_open_data, imgw_pib, met_eireann_open_data, ipma_open_data, portugal_ipma, bureau_of_meteorology, geosphere, zamg, met_norway, metno_frost, dmi_open_data, dwd_open_data, deutscher_wetterdienst, chmu, čhmú, meteosi, meteo.si and meteo_si are normalised internally, but canonical names are recommended in shared configs.

product: auto chooses the provider default: daily for aemet, eobs and noaa_ghcn_daily, otherwise hourly. Only knmi, meteo_france, noaa_uscrn, chmi and arso support both hourly and daily in the current adapter registry.

Common `external_meteo` configuration reference¶

Option	Default	Description
`enabled`	`false`	Enables this provider block. Disabled entries can remain in template configs.
`external_meteo.provider` / `provider`	`meteostat`	Canonical provider name or supported alias.
`station`	`nearest`	Provider station id or `nearest`. Gridded providers use the CRNS coordinates.
`product`	`auto`	`auto`, `hourly` or `daily`, subject to provider support.
`max_distance_km`	`null`	Optional maximum nearest-station distance.
`request_timeout`	`30`	HTTPS timeout in seconds.
`cache_dir`	`null`	Optional cache directory for downloaded catalogs and data files. Relative YAML paths resolve relative to the config file.
`use_cache`	`true`	Reuse downloaded provider files when possible and write new downloads to cache.
`max_nearest_timedelta`	`1h`	Maximum time offset allowed when aligning provider values to CRNS timestamps. Daily providers often need a wider value such as `12h`.
`fill_pressure`	`false`	Fill missing `air_pressure` values from this provider when available.
`fill_temperature`	`false`	Fill missing `air_temperature` values from this provider when available.
`fill_relative_humidity`	`false`	Fill missing `air_relative_humidity` values from this provider when available.
`include_precipitation`	`true`	Attach/fill precipitation from this provider.
`include_solar_radiation`	`false`	Attach global-radiation/solar-radiation where the provider product exposes it.
`include_wind_speed`	`false`	Attach canonical wind speed in m/s. Available through NASA POWER, Open-Meteo/ERA5, AEMET, NOAA/NWS, INMET, JMA AMeDAS, BoM, GeoSphere Austria, Frost, DMI, CHMI, ARSO, SMHI, IMGW and Met Éireann; unsupported providers skip it unless `required: true`.
`include_reference_et0`	`false`	Attach hourly FAO-56 reference ET0 amounts in mm. Available through Open-Meteo archive adapters and usable as the direct reference-ET input of the soil-profile model.
`temporal_semantics`	`{}`	Advanced per-variable override of provider time semantics (`state`, `interval_total`, or `interval_mean`, plus `duration` and `label`). Built-in provider fields already use provider-specific defaults; override only custom/local extracts whose timestamp contract differs.
`prefer_external_values`	`false`	If `true`, this provider overwrites local/DWD values where provider data exist. If `false`, it only fills gaps.
`required`	`false`	If `true`, provider failures abort the pipeline. If `false`, processing continues where possible.
`station_candidate_limit`	`25`	Number of nearest station candidates to try before giving up. Applies to providers with station catalogs.

Temporal semantics and accumulated weather values¶

Neptoon distinguishes point/state observations from values which represent a time interval. This distinction is important for precipitation and reference ET0: copying a one-hour total onto four 15-minute rows would multiply the later water balance, while selecting one hourly value for a three-hour target grid would lose water. Interval totals are therefore rebinned by exact time overlap, so the amount is conserved when changing resolution in either direction. Interval means such as hourly mean radiation use overlap-duration weighting instead.

The normal user does not need to configure this. Provider adapters attach their native contract before Neptoon aligns the data. Important built-in defaults include:

Provider/source	Built-in temporal treatment
Open-Meteo / ERA5 `precipitation`, `et0_fao_evapotranspiration`	one-hour total ending at the provider timestamp
Open-Meteo / ERA5 `shortwave_radiation`	one-hour mean ending at the provider timestamp
NASA POWER hourly precipitation	one-hour total starting at the UTC provider timestamp
NASA POWER pressure, temperature, RH, solar radiation and wind	one-hour mean starting at the UTC provider timestamp
AEMET daily precipitation	one-day total starting at the UTC calendar date
MeteoSwiss `rre150z0` / `rre150h0`	10-minute / one-hour precipitation total ending at the timestamp
MeteoSwiss `gre000z0` / `gre000h0`	10-minute / one-hour radiation mean ending at the timestamp
KNMI `RH`	one-hour precipitation total ending at the timestamp; raw values are converted from 0.1 mm and trace `-1` to canonical mm
KNMI `Q`	hourly radiation energy is converted to the canonical mean flux before interval alignment
Météo-France `RR1`, `RR3`, `RR6`, `RR12`, `RR24`	total over the stated preceding N-hour interval; overlapping rolling totals are rejected instead of double-counted
BoM `rain_since_9am`	cumulative rain is de-accumulated into non-overlapping increments using the 09:00 local reset before alignment
GeoSphere Austria `rr`	one-hour precipitation total ending at the timestamp; `cglo` is a one-hour radiation mean
MET Norway Frost `sum(precipitation_amount PT1H)`	one-hour precipitation total ending at `referenceTime`
DMI `precip_past1h`	one-hour precipitation total ending at `observed`; `*_past1h` state drivers and global radiation are treated as preceding-hour means
NOAA ISD one-hour `AA*` / NOAA USCRN Hourly02	one-hour amount ending at the observation timestamp
NOAA/NWS `precipitationLastHour`	one-hour amount ending at the observation timestamp
INMET WIS2 SYNOP total precipitation	one-hour SYNOP amount ending at `phenomenonTime`
JMA AMeDAS `precipitation1h`	one-hour amount ending at the JST observation timestamp; timestamps are converted to UTC
FMI `r_1h`, `precipitation1h`, `prd_pt1h_acc`	one-hour amount ending at the timestamp
IPMA `precAcumulada`	one-hour precipitation total ending at the timestamp; hourly radiation energy in kJ/m2 is converted to mean W/m2
SMHI parameter 7	one-hour precipitation total ending at the observation timestamp
Met Éireann hourly precipitation / solar radiation	one-hour total / one-hour mean ending at the timestamp
CHMI, ARSO, RMI Belgium, VMM Waterinfo hourly adapters	source observations are first aggregated to Neptoon-owned left-labelled hourly buckets; precipitation is then treated as a one-hour total

Provider parsers also retain which native source field was selected. If several local files would mix incompatible contracts for the same canonical variable (for example Météo-France RR1 and RR3), Neptoon rejects the attachment instead of silently falling back to a generic one-hour assumption.

For a custom/local extract with a different contract, override the relevant canonical variable explicitly:

external_meteo:
  - enabled: true
    provider: open_meteo
    include_precipitation: true
    temporal_semantics:
      precipitation:
        kind: interval_total
        duration: 30min
        label: end

kind: state has no duration and uses label: instant. Interval values use kind: interval_total or kind: interval_mean together with label: start or label: end. Overrides take precedence over provider defaults, so they should only be used when the actual source-file contract is known.

Provider-specific options¶

Provider	Options
`aemet`	`aemet_api_key` or `aemet_api_key_env`, plus optional `aemet_base_url`. Remote API access requires the key.
`nasa_power`	Optional `nasa_power_base_url` for endpoint override/testing. No credential is required.
`noaa_isd`	`noaa_station_history_path` for a local `isd-history.csv` station catalog.
`noaa_ghcn_daily`	`noaa_ghcn_stations_path`, `noaa_ghcn_inventory_path` for local GHCN-Daily metadata.
`noaa_uscrn`	`noaa_uscrn_station_catalog_url`, `noaa_uscrn_station_catalog_path` for station catalog overrides.
`noaa_nws`	`nws_base_url`, `nws_user_agent`, `nws_file_paths`, `nws_station_catalog_path`. No API key is used; `nws_user_agent` is an identifying HTTP header, not a secret.
`inmet`	`inmet_base_url`, `inmet_file_paths`, `inmet_station_catalog_path`. Remote access uses the token-free INMET WIS2 OGC API.
`jma_amedas`	`jma_base_url`, `jma_file_paths`, `jma_station_catalog_path`. Remote access is intended for recent observations; local files are the reproducible/archive path.
`meteostat`	`meteostat_station_db_path` for a local Meteostat `stations.db`.
`open_meteo`, `era5_open_meteo`, `era5_land_open_meteo`	`open_meteo_model`, for example `era5` or `era5_land`. The dedicated ERA5 provider aliases set the model implicitly.
`eobs`	`eobs_data_dir` and/or `eobs_file_paths`. At least one of these is required when `provider: eobs` is enabled.
`meteoswiss`	`meteoswiss_file_paths`, `meteoswiss_data_url`, `meteoswiss_stac_collection_url`.
`knmi`	`knmi_api_key` or `knmi_api_key_env`, plus `knmi_dataset_name`, `knmi_dataset_version`, `knmi_file_paths`, `knmi_max_files`. If `knmi_dataset_version` is set, `knmi_dataset_name` must also be set.
`meteo_france`	`meteo_france_api_key` or `meteo_france_api_key_env`, plus `meteo_france_api_url`, `meteo_france_file_paths`, `meteo_france_station_catalog_url`, `meteo_france_station_catalog_path`.
`chmi`	`chmi_file_paths`, `chmi_station_catalog_path`, `chmi_station_catalog_url`, `chmi_base_url`, `chmi_allowed_quality_values`, `chmi_allowed_flag_values`.
`arso`	`arso_file_paths`, `arso_station_catalog_path`, `arso_station_catalog_url`, `arso_base_url`, `arso_allowed_state_values`.
`rmi_belgium`	`rmi_belgium_wfs_url` to override the public `opendata.meteo.be` WFS endpoint. No API key is used.
`vmm_waterinfo`	`vmm_waterinfo_url` plus the configurable pressure, temperature, relative-humidity and precipitation group ids. Anonymous requests need no API key, but Waterinfo applies request/data limits and recommends tokens for sustained automation.
`met_office_datahub`	`met_office_api_key` or `met_office_api_key_env`, plus `met_office_api_url`, `met_office_file_paths`. Without local files, an API key source and API URL are normally both needed.
`fmi`	`fmi_data_url`, `fmi_file_paths`, `fmi_stored_query_id`, `fmi_parameters`.
`smhi`	`smhi_base_url`, `smhi_file_paths`, `smhi_period`. The token-free metobs adapter uses parameter-specific station metadata and can combine recent and corrected archive periods.
`imgw`	`imgw_data_url`, `imgw_file_paths`, `imgw_station_catalog_url`, `imgw_station_catalog_path`. Remote synop access is token-free; nearest-station selection uses Neptoon's built-in IMGW synoptic coordinate inventory unless a catalogue override is supplied. Local snapshots are recommended for pinned historical use.
`met_eireann`	`met_eireann_base_url`, `met_eireann_collection_id`, `met_eireann_file_paths`, `met_eireann_station_catalog_path`. The default collection is the token-free 60-minute EDR observation collection.
`ipma`	`ipma_data_url`, `ipma_file_paths`, `ipma_station_catalog_url`, `ipma_station_catalog_path`. Public remote observations cover the latest 24 hours and require no API key.
`eccc_geomet`	`eccc_api_url`, `eccc_collection_id`, `eccc_file_paths`.
`bom`	`bom_data_url`, `bom_file_paths`, `bom_station_catalog_url`, `bom_station_catalog_path`, `bom_product_id`. Without URL/files, `station: nearest` uses the official national station list and state-specific public 72-hour observation product.
`geosphere_austria`	`geosphere_austria_base_url`, `geosphere_austria_resource_id`, `geosphere_austria_file_paths`, `geosphere_austria_station_catalog_path`. The default resource is `klima-v2-1h`; no API key is required.
`frost`	`frost_client_id` or `frost_client_id_env`, plus `frost_base_url`, `frost_file_paths`, `frost_source_file`. API access requires the Frost client id as Basic-auth username with an empty password; local observation files do not.
`dmi`	`dmi_base_url`, `dmi_file_paths`, `dmi_station_catalog_path`. The public DMI Meteorological Observation API requires no key.
`dwd`	`dwd_request_retries`, `dwd_station_products_path`, `dwd_precipitation_daily_fallback`, `dwd_precipitation_product`. DWD Open Data requires no key.

For credential-bearing providers, the *_env option names an environment variable whose value is resolved only at the runtime attachment boundary. Direct secret fields take precedence over environment values. ConfigSaver omits direct secret values but preserves the non-secret *_env reference, so configuration can remain portable without embedding credentials. The provider registry exposes these credential contracts programmatically for future CLI/GUI consumers.

The default VMM group identifiers are 192918 for air pressure, 192922 for air temperature, 192919 for relative humidity and 192897 for hourly precipitation. Pressure, temperature and relative humidity are aggregated to hourly means; precipitation is aggregated to hourly sums. Waterinfo does not guarantee that group identifiers remain stable, so every identifier can be overridden with vmm_waterinfo_pressure_group_id, vmm_waterinfo_temperature_group_id, vmm_waterinfo_relative_humidity_group_id and vmm_waterinfo_precipitation_group_id. The separate VMM irradiance series is not mapped to Neptoon global radiation because its measurement semantics have not been verified as equivalent.

United States, Brazil and Japan token-free station providers¶

provider: noaa_nws uses NOAA/NWS api.weather.gov station observations. Neptoon sends the identifying User-Agent required by weather.gov, but no API key or login is needed. station: nearest resolves the point's NWS observation-station collection and chooses the nearest coordinate subject to max_distance_km. The NWS surface-observation endpoint is currently limited primarily to contiguous-US locations, so the global NOAA archive providers remain better choices outside that operational footprint.

provider: inmet uses Brazil's public WIS2 OGC API and the automatic SYNOP network. station can be a WIGOS identifier or traditional INMET identifier; station: nearest uses the WIS2 station collection. Station pressure is deliberately mapped from non_coordinate_pressure; mean-sea-level pressure is not substituted for CRNS pressure correction.

provider: jma_amedas uses the public JMA AMeDAS station table and recent three-hour point JSON blocks. AMeDAS timestamps are interpreted in Asia/Tokyo and converted to UTC. The public web feed is treated as near-real-time rather than an archival SLA: configure jma_file_paths for old or pinned observations.

external_meteo:
  - enabled: true
    provider: noaa_nws
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_wind_speed: true

  - enabled: false
    provider: inmet
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_wind_speed: true

  - enabled: false
    provider: jma_amedas
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_wind_speed: true

Sweden, Poland and Ireland token-free national providers¶

Sweden is available as provider: smhi. The adapter uses the stable SMHI metobs 1.0 parameter endpoints for temperature, relative humidity, hourly precipitation and wind speed. For station: nearest, Neptoon intersects station availability across all requested variables before selecting the nearest common station. Requests older than the recent rolling period use the corrected archive automatically, while ranges crossing the boundary combine corrected and recent observations.

Poland is available as provider: imgw. The public IMGW-PIB synop endpoint supplies current station pressure, temperature, relative humidity and wind without authentication. station: nearest uses a built-in synoptic coordinate inventory derived from IMGW's public meteorological yearbook and intersects it with stations actually present in the observation payload; imgw_station_catalog_path or imgw_station_catalog_url can override those coordinates. The upstream suma_opadu field is deliberately not attached as canonical precipitation because the live field's accumulation interval is not explicit enough for Neptoon's interval-conserving precipitation semantics; local pinned snapshots can be used for reproducible processing.

Ireland is available as provider: met_eireann. Neptoon uses the public 60-minute OGC EDR observation collection, discovers station locations for station: nearest, and parses CoverageJSON into pressure, temperature, relative humidity, precipitation, solar radiation and wind speed. Local CoverageJSON can be supplied for offline or pinned workflows.

external_meteo:
  - enabled: true
    provider: smhi
    station: nearest
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_wind_speed: true

  - enabled: false
    provider: imgw
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: false
    include_wind_speed: true

  - enabled: false
    provider: met_eireann
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: true
    include_wind_speed: true

Portugal IPMA Open Data¶

Portugal is available as provider: ipma. The adapter uses IPMA's official token-free stations.json catalogue and hourly observations.json feed. With station: nearest, Neptoon filters the catalogue to stations present in the current observations and chooses the closest station subject to max_distance_km. The public observations feed contains the latest 24 hours and is updated hourly, so historical workflows should pin downloaded JSON through ipma_file_paths. IPMA's documented -99.0 no-data values become missing values; precAcumulada is treated as the one-hour precipitation total ending at the timestamp, and hourly radiation energy in kJ/m2 is converted to canonical mean W/m2.

external_meteo:
  - enabled: true
    provider: ipma
    station: nearest
    max_distance_km: 100
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: true
    include_wind_speed: true

Australia, Austria, Norway and Denmark national providers¶

The bom provider can now resolve station: nearest without a manually supplied product URL. Neptoon downloads BoM's national stations.txt, keeps active stations that have a WMO id and a supported state/territory public product, orders them by distance and tries the rolling public observation JSON in nearest-first order. Those anonymous fwo products contain only the previous 72 hours; use bom_data_url or bom_file_paths for older or pinned data.

GeoSphere Austria is available as provider: geosphere_austria. The default klima-v2-1h dataset is quality-checked, hourly, UTC and token-free. station: nearest uses the resource station metadata before requesting only the selected station and requested parameters.

MET Norway is available as provider: frost. Frost requires a client id even for open data; configure it as frost_client_id. Neptoon asks Frost for nearby SensorSystem sources that expose the requested elements, then retrieves the preferred/default time series and accepted quality codes. Local Frost JSON can be supplied through frost_file_paths for reproducible/offline processing.

DMI Open Data is available as provider: dmi. It uses the token-free Meteorological Observation API, resolves the nearest active station and requests only the selected parameters. DMI's hourly mean/accumulation products are used where available; direct station pressure is averaged from the provider's 10-minute observations into hourly values.

external_meteo:
  - enabled: true
    provider: geosphere_austria
    station: nearest
    max_distance_km: 100
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: true
    include_wind_speed: true

  - enabled: false
    provider: frost
    station: nearest
    frost_client_id: YOUR_FROST_CLIENT_ID
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_wind_speed: true

  - enabled: false
    provider: dmi
    station: nearest
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: true
    include_wind_speed: true

CHMI / ČHMÚ Open Data¶

The chmi provider reads Czech Hydrometeorological Institute climate Open Data from https://opendata.chmi.cz/meteorology/climate. It supports station: nearest using WIGOS station identifiers and station coordinates, or an explicit WSI such as 0-20000-0-11450. Hourly mode combines the provider's 10-minute and one-hour products: state variables are averaged, precipitation is summed, and a dedicated one-hour value takes precedence when both resolutions provide the same canonical variable. Daily mode prefers the provider daily station products and falls back to aggregation of the hourly inputs.

CHMI publishes FLAG and QUALITY fields with separate metadata describing their meaning. Neptoon therefore does not assign undocumented good/bad semantics by default. Use chmi_allowed_quality_values and/or chmi_allowed_flag_values only when your project has chosen an explicit quality policy. For CRNS pressure filling, Neptoon maps the direct station-pressure element P and deliberately does not treat the distinct P_hm element as interchangeable. Cache entries are scoped by the full CHMI source URL so identically named now, recent, and historical files cannot collide; rolling now and root-level recent products are fetched fresh because CHMI updates them in place. Local chmi_file_paths and chmi_station_catalog_path are useful for offline and fully reproducible runs. With station: nearest, Neptoon tries the nearest candidates in distance order until one returns usable data, subject to max_distance_km and station_candidate_limit.

ARSO / meteo.si automatic-station XML¶

The arso provider reads Slovenian Environment Agency (ARSO / meteo.si) automatic-station XML. With station: nearest, Neptoon reads the all-station latest XML catalog, orders stations by distance from the CRNS coordinates, and tries candidates until one provides usable observations. An explicit ARSO domain_meteosiId is also accepted; aliases meteosi, meteo.si and meteo_si normalise to arso.

ARSO's native observations are commonly sub-hourly, so Neptoon aggregates them to the configured hourly or daily product. ARSO validity timestamps are treated as interval ends when assigning sub-hourly observations to aggregation bins. Temperature, relative humidity, pressure, wind speed and global radiation prefer ARSO interval-average fields when present. Precipitation uses rr_val, the amount for the observation interval, and is summed during aggregation; rolling accumulations such as tp_1h_acc are deliberately not summed. For CRNS pressure filling, Neptoon uses the station-pressure fields p/pavg rather than mean-sea-level pressure msl/mslavg.

ARSO publishes per-field *_state values, but this adapter does not guess undocumented good/bad semantics. Set arso_allowed_state_values only when a project has adopted an explicit state-value policy. Public per-station history XML is a rolling recent product (approximately 48 hours), so use arso_file_paths for archived XML and reproducible or older runs. arso_station_catalog_path can pin station metadata offline; arso_station_catalog_url and arso_base_url are available for endpoint overrides.

external_meteo:
  - enabled: true
    provider: arso
    station: nearest
    product: hourly
    max_distance_km: 100
    fill_pressure: true
    fill_temperature: true
    fill_relative_humidity: true
    include_precipitation: true
    include_solar_radiation: true
    include_wind_speed: true
    prefer_external_values: false
    required: false

Local provider files and reproducibility¶

Some providers can use explicit local input files for reproducible offline runs, for example E-OBS, MeteoSwiss, KNMI, Météo-France, CHMI, ARSO, FMI, IPMA, ECCC GeoMet, BoM, GeoSphere Austria, Frost, DMI and selected NOAA catalog files:

external_meteo:
  - enabled: true
    provider: eobs
    product: daily
    station: nearest
    max_nearest_timedelta: 12h
    eobs_data_dir: ./external/eobs
    fill_temperature: true
    include_precipitation: true

Relative local paths in YAML are resolved relative to the config-file directory. This includes cache_dir, station-catalog files and provider data files.

Provider capabilities and source columns¶

Not every provider exposes every variable. Neptoon will only attach the requested variables that are available in the selected provider product. For example, vmm_waterinfo provides pressure, temperature, relative humidity and precipitation from VMM station time series; noaa_ghcn_daily is useful for daily precipitation and temperature but does not provide pressure in this adapter; meteostat, noaa_isd and met_office_datahub do not provide a true global-radiation product here; noaa_uscrn, Open-Meteo, E-OBS, MeteoSwiss, KNMI, Météo-France, CHMI, ARSO, FMI, IPMA, ECCC GeoMet, BoM, GeoSphere Austria and DMI can provide solar/global-radiation fields when present in the selected product. Frost deliberately does not advertise solar radiation in this adapter. The Open-Meteo adapters additionally expose optional canonical wind_speed and reference_et0 columns; BoM, IPMA, GeoSphere Austria, Frost, DMI, CHMI and ARSO expose canonical wind_speed when available. Pure era5_land_open_meteo retains reference ET0 but does not request unavailable wind, precipitation or solar-radiation fields; use open_meteo/ERA5 where those atmospheric drivers are required.

The canonical Open-Meteo/ERA5 wind field is a 10 m wind product. If that column is used to calculate soil-profile Penman-Monteith ET0 locally rather than attaching the provider's direct reference_et0, configure ProfileModelConfig(wind_speed_measurement_height_m=10.0) so Neptoon converts the wind to the FAO 2 m reference height. Missing wind remains harmless because the ET0 hierarchy falls back per day when Penman-Monteith inputs are incomplete.

Provider attachment also records provenance columns where possible. The exact names depend on the provider and variable, but source/provenance columns are intended to show whether values came from local data, DWD, or a specific external provider product. Use these columns to diagnose why a meteorological value was used in corrections or shown in a report.

ERA5-Land soil moisture and snow¶

The Open-Meteo adapters also carry ERA5-Land soil moisture and snow depth as reference series. These are reanalysis of the land surface: not measurements at your site, and not remote sensing either, which is why they live in external_meteo rather than under remote_sensing:. Like every gridded reference series in Neptoon they are written, scaled, plotted, reported and audited, and they enter no neutron correction, no N0 calibration and no soil-moisture product.

external_meteo:
  - enabled: true
    provider: era5_land
    include_precipitation: false
    include_soil_moisture: true
    soil_moisture_layers:
      - 7_28cm
    soil_moisture_scaling:
      method: offset
      offset: -0.045
    include_snow_depth: true

Option	Default	Description
`include_soil_moisture`	`false`	Attach ERA5-Land soil moisture in m³/m³, one column per requested layer.
`soil_moisture_layers`	`[7_28cm]`	Which of the four native layers to attach: `0_7cm`, `7_28cm`, `28_100cm`, `100_255cm`. The provider spellings (`0_to_7cm` and so on) are accepted.
`soil_moisture_scaling`	`method: none`	Optional explicit adjustment. Same schema and same rules as `remote_sensing.scaling`.
`include_snow_depth`	`false`	Attach ERA5-Land snow depth on the ground, in metres.
`include_snow_water_equivalent`	`false`	Declared, but not served by this route, see below.

Columns are named for their origin: era5_land_soil_moisture_7_28cm, era5_land_snow_depth. A scaled series adds era5_land_soil_moisture_7_28cm_scaled beside the raw column rather than replacing it, so the adjustment stays auditable and can be undone without re-fetching. Provenance columns record the product, the provenance class, the native resolution, the retrieval time and the grid cell that actually answered, the distance from your station to that cell centre is the difference between "the reanalysis at this site" and "the reanalysis somewhere within 9 km of it".

Why the default layer is 7–28 cm and not the topmost one¶

ERA5-Land has four native soil layers, and Neptoon defaults to the second one. The reason is physical rather than empirical:

a CRNS integrates roughly 15–40 cm of soil, depending on water content;
ERA5-Land's top layer is the uppermost 7 cm, which dries and rewets far faster than the depth the neutron signal represents.

Comparing a CRNS series against the 0–7 cm layer therefore shows a disagreement produced by the comparison rather than by either dataset: the shallow layer swings through a drying event while the CRNS footprint, weighted over a deeper column, does not. The 7–28 cm layer overlaps the CRNS integration depth and is the honest default.

You can request any of the four layers, and several at once, but only those four. Interpolating to some other depth would mean inventing a soil profile, so a request for one is refused rather than approximated.

Two things this route cannot do¶

Both were measured against the live endpoint, and both are stated here so they do not have to be rediscovered.

Snow water equivalent is not available. The Open-Meteo Historical Weather API accepts snow_depth_water_equivalent and then returns null for it under every archive model, era5_land, era5, era5_seamless and best_match alike, with the unit reported as undefined. Measured on 2026-08-20 for 2021-02-10 at 52.09 N, 11.226 E, a date with 0.21 m of modelled snow: snow depth came back, water equivalent did not. The same variable is served by the forecast API in mm, so the name is right and the archive coverage is not. ERA5-Land itself publishes snow depth water equivalent, so the gap is in this route rather than in the reanalysis; reaching the value needs the Copernicus CDS API, which requires a personal access token. Enabling include_snow_water_equivalent reports the gap instead of attaching a column of nulls, and deriving it from snow depth is not offered because that needs a snow density this route does not supply either.

The provider must really be ERA5-Land. Soil and snow variables are refused unless the effective Open-Meteo archive model is era5_land, and the refusal happens when the configuration is loaded rather than when the fetch runs. That is deliberate: the columns are named era5_land_*, so filling them from ERA5 or from Open-Meteo's best-match blend would mislabel the data in the one place a later reader looks. Use provider: era5_land, or any Open-Meteo provider together with open_meteo_model: era5_land.

A station whose coordinates fall on open water fails loudly rather than producing an empty column. ERA5-Land is a land-surface reanalysis and returns null over sea at every timestamp, so the same coverage check that reads pixels for satellite products detects the land boundary here with no special case. A single missing hour is still just a gap.

Failure handling¶

Use required: true for production configurations where external meteorology is mandatory. Leave it as false when external data are useful fallbacks but processing should continue if a provider is temporarily unavailable.

When you combine several providers, put the most trusted or most local provider first and set prefer_external_values: false for fallback behaviour. Use prefer_external_values: true only when the provider is deliberately the authoritative source.

Independently logged soil moisture¶

Soil-moisture reference sensors stored in separate CSV files use a distinct input path because they are not meteorological fallback providers. Neptoon can map files to sensor IDs and depths, normalise them to m³/m³, aggregate each sensor independently and join the result to the final CRNS time index. See External soil-moisture time series.