energy_data_retrieval.discovery#

Discover nearby station candidates and gridded products for one location.

class energy_data_retrieval.discovery.DiscoveryResult(query, stations, grids, source_status, created_at_utc, status)[source]#

Bases: object

A point-in-time catalogue search, with explicit limits on availability claims.

Parameters:
  • query (dict[str, JSONValue])

  • stations (DataFrame)

  • grids (list[dict[str, JSONValue]])

  • source_status (list[dict[str, JSONValue]])

  • created_at_utc (str)

  • status (str)

query: dict[str, JSONValue]#
stations: DataFrame#
grids: list[dict[str, JSONValue]]#
source_status: list[dict[str, JSONValue]]#
created_at_utc: str#
status: str#
as_dict()[source]#

Return JSON-safe rows, provenance, references and a content checksum.

Return type:

dict[str, JSONValue]

energy_data_retrieval.discovery.find_sources(latitude, longitude, *, radius_km=100.0, limit=20, station_sources=('noaa', 'aemet', 'dwd', 'surfrad', 'bsrn'), catalogues=None, http=None, probe_date=None, cmip6_plan=None)[source]#

Find station candidates and existing grid products for a geographic point.

limit applies across all station providers, ordered by spherical distance. Source catalogues are acquired once without bounding-box prefilters, so the search also works across the antimeridian and near the poles. A supplied catalogues mapping reuses verified source snapshots with their original geographic scope. Missing credentials and provider errors remain explicit source statuses; one unavailable provider does not discard successful ones.

Pass an allowlisted HTTPClient to enable catalogue requests. With http=None, only local catalogues and documented grid metadata are read. probe_date optionally verifies a small Open-Meteo sample for that date; the native ERA5 snapshot and CMIP6 coordinates are not implicitly downloaded. A verified CMIP6 retrieval plan adds its exact datasets as candidates while retaining the requirement to inspect their native coordinate grids.

Parameters:
  • latitude (float)

  • longitude (float)

  • radius_km (float)

  • limit (int)

  • station_sources (Sequence[str])

  • catalogues (Mapping[str, Path] | None)

  • http (HTTPClient | None)

  • probe_date (date | None)

  • cmip6_plan (CMIP6Plan | None)

Return type:

DiscoveryResult

energy_data_retrieval.discovery.save_discovery(result, path)[source]#

Save a new JSON snapshot without overwriting an earlier discovery result.

Parameters:
Return type:

None