Find stations and gridded datasets from coordinates#

The discover command accepts one latitude/longitude point, searches the integrated station catalogues, ranks nearby candidates and describes the gridded products that can be considered for that location. It returns machine readable JSON with source identities, distance, coverage evidence, access requirements, retrieval parameters and citations.

One command#

uv run energy-retrieve discover \
  --latitude 28.4775 --longitude -16.3294 \
  --radius-km 100 --limit 20 \
  --output data/discovery/tenerife.json

Coordinates are decimal degrees, with latitude first. Latitude must be in [-90, 90] and longitude in [-180, 180]. The default search radius is 100 km and the default result limit is 20 stations across all selected providers. The command prints the full JSON when --output is omitted. A saved snapshot is never overwritten; choose a new filename to refresh the search.

Fresh station searches use the existing bounded HTTP transport. Public requests can use --cache-directory data/discovery/cache. AEMET requires AEMET_API_KEY for a fresh catalogue. Missing credentials and individual provider failures appear in source_status, while successful results remain available. The top-level partial status means at least one requested source could not be checked; it does not mean all stations were searched successfully.

Select sources or reuse local catalogues#

Repeat --station-source to choose specific providers:

uv run energy-retrieve discover \
  --latitude 28.4775 --longitude -16.3294 --radius-km 150 \
  --station-source noaa --station-source bsrn

Use an existing station catalogue and its manifest/required sidecars for an offline lookup:

uv run energy-retrieve discover \
  --latitude 28.4775 --longitude -16.3294 --radius-km 100 \
  --station-source aemet \
  --catalogue aemet=data/aemet/stations.parquet \
  --offline --output data/discovery/tenerife-offline.json

Local catalogues retain their original bounding box and country filter. A filtered Canary Islands catalogue is never described as a global inventory. The source scope remains visible even when it produces no matches. Checksums and required source artifacts are verified before a saved catalogue is reused. An invalid local snapshot is reported explicitly and does not silently trigger a replacement network acquisition.

The optional --grid-only mode skips station catalogues. With no data probe, grid discovery uses the documented product contracts and makes no requests:

uv run energy-retrieve discover \
  --latitude -23.65 --longitude -70.40 --grid-only

Station results#

Each returned station keeps its native identifier and catalogue fields and adds source, distance_km, a one-based rank, and retrieval hints. Catalogue coordinates that are missing, nonnumeric or outside valid ranges are excluded from ranking and counted. Source records are not merged based on similar names or coordinates.

Source

Geographic discovery

What the catalogue establishes

NOAA GHCNh

Current NCEI station inventory

Identity and location; station-specific date and variable availability need an observation request

AEMET

OpenData daily-climate station inventory

Identity and location; historical daily and recent-observation availability remain separate checks

DWD CDC

Hourly solar station catalogue

Identity, location and published date extent; the extent does not establish continuous observations

NOAA SURFRAD

Supported network catalogue

Current station metadata and installation information; historical file headers can contain different coordinates

BSRN

Official PANGAEA station catalogue

Event identity, coordinates and event time metadata; monthly data availability requires the existing DOI search and validation

The BSRN catalogue is linked from the official BSRN station overview. Catalogue codes that the current monthly adapter cannot retrieve are retained with an explicit unsupported-retrieval indicator. SURFRAD participates in BSRN, so the two sources can contain overlapping observations; discovery keeps both identities visible.

Distances use a haversine calculation on a sphere with mean radius 6371.0088 km. The method handles the antimeridian and poles and ignores altitude, terrain, exposure and microclimate. Equal-distance ties are resolved by source, station ID and original row order. Geographic proximity alone does not establish a suitable PV reference station. See the BSRN guidance on station representativeness.

Gridded dataset results#

The registry describes only the six integrated offerings. It does not add a new data provider or claim that a catalogue entry proves usable data at every date and grid cell.

Dataset

Geographic evidence

Retrieval behavior

Open-Meteo ERA5

Documented global coverage

Explicit ERA5 hourly output, nearest cell, elevation adjustment disabled

Open-Meteo archived IFS

Documented global model coverage

Explicit ecmwf_ifs archived forecast product; model vintage, start and resolution require product-specific evidence

Earthmover native ERA5

Documented global ERA5 grid

Uses the repository’s pinned Icechunk snapshot; that snapshot’s actual time bounds and cell data need inspection

GPCC Monthly v2025

Global land; native cell mask unverified

Monthly precipitation; 1891 onward; 0.25°, 0.5°, 1°, 2.5°; gpcc command

CRU TS v4.10

Global land excluding Antarctica; native cell mask unverified

Ten monthly variables; 1901–2025; 0.5°; cru-ts command

CMIP6

Depends on the explicitly selected dataset and native grid

Requires model, experiment, ensemble member, table, variable, grid and resolved version

CDS ERA5 hourly/monthly

Global documented coverage from 1940; availability not probed

Official CDS API, personal access token, accepted dataset terms and explicit area/variables; native files

Each row records supported source variables, normalized output variables, spatial/temporal descriptions, known coverage bounds, access requirements, retrieval hints, reference IDs and status. Unknown bounds stay unknown. Grid cell coordinates remain null until they are returned by an actual response; they are not fabricated by rounding the requested point.

Source documentation: Open-Meteo historical weather, Open-Meteo historical forecasts, and the Earthmover ERA5 registry. The CMIP6 source contract describes the supported ESGF selection and plan workflow.

Verify a small sample at the point#

uv run energy-retrieve discover \
  --latitude 28.4775 --longitude -16.3294 \
  --grid-only --probe-date 2025-01-01 \
  --output data/discovery/tenerife-grid-sample.json

This calls the two existing Open-Meteo clients for one requested UTC day. Their established interval-end convention also requests the following day for boundary samples, then normalizes only the requested day. The result records the actual selected cell, per-variable non-null and missing counts, sample completeness and the safe request record/hash. An all-missing sample and a provider failure remain distinguishable. A verified sample establishes evidence for that date only; it does not certify the full historical period. --probe-date cannot be combined with --offline.

CDS is also listed without credential reads or job submission. Use cds-era5 with an explicit north/west/south/east area, or cds-retrieve with a catalogue selection; see the CDS guide.

Native ERA5 and CMIP6 are not implicitly downloaded by this probe. Native ERA5 requires its optional dependencies and pinned-snapshot retrieval. For CMIP6, first create an explicit plan using cmip6-search, then attach it:

uv run energy-retrieve discover \
  --latitude -23.65 --longitude -70.40 --grid-only \
  --cmip6-plan data/cmip6/plan.json \
  --output data/discovery/chile-cmip6.json

The result contains the selected datasets and native file metadata, with point_coverage_unverified. Latitude and longitude are not silently passed as a CMIP6 catalogue filter or used to assume a regular grid. Inspect the native coordinates, masks, calendar, units and time bounds before selecting a point or converting output for a performance study.

Python API#

from energy_data_retrieval.discovery import DISCOVERY_HOSTS, find_sources
from energy_data_retrieval.transport import HTTPClient, HTTPConfig

with HTTPClient(
    DISCOVERY_HOSTS,
    config=HTTPConfig(minimum_interval_seconds=1.6),
) as http:
    result = find_sources(
        28.4775,
        -16.3294,
        radius_km=100,
        limit=20,
        http=http,
    )

print(result.stations[["source", "station_id", "distance_km", "rank"]])
print(result.grids)
snapshot = result.as_dict()

Passing http=None enables only local catalogue lookup and documented grid metadata. catalogues={"aemet": Path("data/aemet/stations.parquet")} supplies a saved catalogue. station_sources=() skips station sources.

For a user-supplied station inventory, call the pure distance method directly:

from energy_data_retrieval.spatial import nearby_stations

# stations is a DataFrame with station_id, latitude and longitude columns.
nearest = nearby_stations(stations, 28.4775, -16.3294, radius_km=100, limit=10)

This preserves all supplied columns and attributes and performs no I/O. Its spatial_search attributes record invalid-coordinate counts, the number within the radius, the returned count and whether the limit truncated the result.

Reproducibility and scientific attribution#

Discovery JSON includes its query, creation time, source-specific status and scope, safe request records, distance assumptions and references. Its discovery_sha256 hashes the complete JSON object before that checksum field is added, using Python’s json.dumps(..., sort_keys=True, allow_nan=False). Missing values are serialized as JSON nulls.

The project originated in work inspired by Julián Andrés Ascencio Vásquez’s doctoral thesis; location discovery is a later extension. Cite the provider references that accompany the discovery evidence and the repository revision. The complete bibliography is in references. Discovery does not change observations, infer station-to-plant mappings, apply quality filtering, resample data, or merge modeled and measured values.