earthkit-data

0.19.4 verified Fri May 01 auth: no python

A format-agnostic Python interface for geospatial data, providing unified access to GRIB, NetCDF, ODB, and other formats. Current version is 0.19.4, with a release cadence of approximately monthly. A release candidate for 1.0.0 (1.0.0rc1) is available.

pip install earthkit-data

Common errors

error ModuleNotFoundError: No module named 'eccodes' ↓

cause Missing backend library for GRIB support.

fix

pip install eccodes

error AttributeError: 'Reader' object has no attribute 'metadata' ↓

cause Using a method not available in the current source type (e.g., ODB objects do not have a single metadata concept).

fix

First check the type of data: print(type(ds[0])) and use appropriate methods like ds[0].keys() for ODB.

error earthkit.data.core.DataError: Unable to open resource ↓

cause URL not accessible or file does not exist.

fix

Verify the URL or file path. For URLs, ensure network access and correct URL syntax.

Warnings

breaking Version 1.0.0rc1 introduces breaking changes: the API for metadata access and data conversion has been restructured. The old `.metadata()` method may not work as before. ↓

fix Refer to the upgrade guide at https://earthkit-data.readthedocs.io/en/latest/release-notes/version_1.0.0rc_updates.html

deprecated Using `from_source` with positional arguments for source type is deprecated; use keyword arguments or switch to the new URL-based API. ↓

fix Use `ekd.from_source('url', url)` or `ekd.from_source(url=url)` (preferred).

gotcha The library expects specific backends for different formats; missing eccodes will cause GRIB loading to fail silently or raise confusing errors. ↓

fix Install required backend: `pip install eccodes` (or `cfgrib`) for GRIB, `netcdf4` for NetCDF.

gotcha `ds.to_xarray()` can be memory-intensive for large datasets; prefer lazy loading with `ds.to_xarray(chunks={})` or iterate in chunks. ↓

fix Use `ds.to_xarray(chunks={'time': 1})` to control chunking.

Install

conda install -c conda-forge earthkit-data

Imports

earthkit.data
wrong
```
from earthkit import data
```
correct
```
import earthkit.data as ekd
```
Most examples use 'import earthkit.data as ekd'; 'from earthkit import data' also works but can cause confusion.
realize
wrong
```
from earthkit.data.core import Base
```
correct
```
from earthkit.data import from_source
```
Low-level core classes are not part of the public API; use from_source instead.

Quickstart

Load a GRIB file from a URL and convert to xarray.

import earthkit.data as ekd

# Load GRIB data from a URL
ds = ekd.from_source("url", "https://get.ecmwf.int/repository/test-data/earthkit-data/example.grib")

# Inspect metadata
print(ds[0].metadata("param"))

# Convert to xarray
xr_ds = ds.to_xarray()
print(xr_ds)