currentlab-python

The Current Lab Python library provides convenient access to the Current Lab API from Python applications. Load gridded forecast files as xarray datasets with a single function call.

Installation

pip install currentlab

Authentication

Set your API key as an environment variable:

export CURRENT_LAB_API_KEY="your-api-key"

Or use a .env file (see .env.example) and load it with python-dotenv.

You can also pass the key directly to any function call via the api_key= argument.

Quick start

import currentlab

ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="currents_surface",
)
print(ds)

API Reference

load_dataset(...)

currentlab.load_dataset(
    region,
    dataset_type,
    dataset_source="auto",
    file_format="netcdf",
    run_date="latest",
    *,
    save_dir=None,
    save_path=None,
    api_key=None,
    base_url="https://api.current-lab.com",
)

Parameter	Type	Description
region	str	Region identifier, e.g. "oahu"
dataset_type	str	Dataset type, e.g. "currents_surface", "wave", "wind_10m", "ocean_3d"
dataset_source	str	Model/source selection. Default "auto" lets the server pick the best available source
file_format	str	File format to request. Default "netcdf"
run_date	str	Forecast run date as "YYYY-MM-DD", or "latest". Default "latest"
save_dir	str | Path	Directory to save the downloaded file. Filename is derived from the API response. File is reused on subsequent calls if it already exists
save_path	str | Path	Exact path to save the file to. Reused on subsequent calls if it already exists. Mutually exclusive with save_dir
api_key	str	API key override. Falls back to CURRENT_LAB_API_KEY env var
base_url	str	API base URL override (useful for testing)

Returns an xr.Dataset.

Usage patterns

Stream into memory (no file saved)

A temporary file is created and streamed into memory. The file is deleted after the dataset is closed.

ds = currentlab.load_dataset(region="oahu", dataset_type="wave")

Save to a directory (cached)

File name is derived from the API response.

ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="wave",
    run_date="2025-03-01",
    save_dir="./data",
)

Save to a specific file path (cached)

ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="currents_surface",
    save_path="./data/oahu_currents_latest.nc",
)

Request a specific run date

ds = currentlab.load_dataset(
    region="oahu",
    dataset_type="wind_10m",
    run_date="2026-03-09",
)

Working with the dataset

The returned object is a standard xarray Dataset, so the full xarray API is available:

import numpy as np
import currentlab

ds = currentlab.load_dataset(region="oahu", dataset_type="currents_surface")

# Compute current speed from u/v components
ds["speed"] = np.hypot(ds["u"], ds["v"])
ds["speed"].attrs["long_name"] = "Current Speed"
ds["speed"].attrs["units"] = "m/s"

print(ds["speed"].max().item())

Error handling

from currentlab import CurrentLabAuthError, CurrentLabAPIError, CurrentLabDownloadError

try:
    ds = currentlab.load_dataset(region="oahu", dataset_type="currents_surface")
except CurrentLabAuthError:
    print("Check your CURRENT_LAB_API_KEY.")
except CurrentLabAPIError as e:
    print(f"API error: {e}")
except CurrentLabDownloadError as e:
    print(f"Download failed: {e}")

All exceptions inherit from currentlab.CurrentLabError.

Development

git clone https://github.com/current-lab/currentlab-python
cd currentlab-python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest