Cloudnet API client

Official Python client for the Cloudnet data portal API.

Installation

bash python3 -m pip install cloudnet-api-client

Quickstart

```python from cloudnetapiclient import APIClient

client = APIClient()

sites = client.sites() site = client.site("hyytiala")

products = client.products() product = client.products("classification")

models = client.models() model = client.model("ecmwf-open")

instruments = client.instruments() instrument = client.instrument("d6bf209b-c48b-48a4-bbfb-fed713b27832")

file = client.file("405cc410-1f24-4ea9-bae8-da7f22be26cb")

files = client.files(siteid="hyytiala", date="2021-01-01", productid=["mwr", "radar"]) file_paths = client.download(files, "data/")

rawfiles = client.rawfiles(siteid="granada", date="2024-01", instrumentid="parsivel") filepaths = client.download(rawfiles, "data_raw/") ```

When downloading files inside Jupyter notebook (or similar environment), you have to use the asynchronous version:

python file_paths = await client.adownload(metadata)

Documentation

APIClient().files() and raw_files() → list[Metadata]

Fetch product and raw file metadata from the Cloudnet data portal.

Parameters:

| name | type | default | example | | ------------------- | --------------------------- | ------- | ---------------------------------------------------- | | siteid | str or list[str] | None | "hyytiala" | | date | str or date | None | "2024-01-01" | | datefrom | str or date | None | "2025-01-01" | | dateto | str or date | None | "2025-01-01" | | updatedat | str, date or datetime | None | "2025-01-01T12:00:00" | | updatedatfrom | str, date or datetime | None | "2025-01-01T12:00:00" | | updatedatto | str, date or datetime | None | "2025-01-01T12:00:00" | | instrumentid | str or list[str] | None | "rpg-fmcw-94" | | instrumentpid | str or list[str] | None | "https://hdl.handle.net/21.12132/3.191564170f8a4686" | | modelid | str or list[str] | None | "gdas1" | | productid* | str or list[str] | None | "classification" | | showlegacy* | bool | False | | | filenameprefix** | str or list[str] | None | "stare" | | filename_suffix** | str or list[str] | None | ".lv1" | | status** | str or list[str] | None | "created", "uploaded", "processed" or "invalid" |

* = only in files()

** = only in raw_files()

Date Handling

The date, date_from and date_to parameters support:

• "YYYY-MM-DD" — a specific date
• "YYYY-MM" — the entire month
• "YYYY" — the entire year
• Or directly as datetime.date object

In addition to these, the updated_at, updated_at_from and updated_at_to parameters support:

• "YYYY-MM-DDTHH" — a specific hour
• "YYYY-MM-DDTHH:MM" — a specific minute
• "YYYY-MM-DDTHH:MM:SS" — a specific second
• "YYYY-MM-DDTHH:MM:SS.FFFFFF" — a specific microsecond
• Or directly as datetime.datetime object

Return value

Both methods return a list of dataclass instances, ProductMetadata and RawMetadata, respectively.

APIClient().filter(list[Metadata]) → list[Metadata]

Additional filtering of fetched metadata.

Parameters:

| name | type | default | | -------------------- | ---------------------------------------------- | ------- | | metadata | list[RawMetadata] or list[ProductMetadata] | | | includepattern | str | None | | excludepattern | str | None | | includetagsubset* | set[str] | None | | excludetagsubset* | set[str] | None |

* = only with RawMetadata

APIClient().file() → ProductMetadata

Fetch metadata of a single file.

Parameters:

| name | type | | ---- | -------------------- | | uuid | str or uuid.UUID |

APIClient().sites() → list[Site]

Fetch all sites.

Parameters:

| name | type | choices | default | | ---- | ----- | ----------------------------------------- | ------- | | type | str | "cloudnet", "campaign", "model", "hidden" | None |

APIClient().site() → Site

Fetch a single site.

Parameters:

| name | type | | ------- | ----- | | site_id | str |

APIClient().products() → list[Product]

Fetch all products.

Parameters:

| name | type | choices | default | | ---- | -------------------- | ----------------------------------------- | ------- | | type | str or list[str] | "instrument", "geophysical", "evaluation" | None |

APIClient().product() → ExtendedProduct

Fetch a single product.

Parameters:

| name | type | | ---------- | ----- | | product_id | str |

APIClient().instruments() → list[Instrument]

Fetch all instruments.

APIClient().instrument_ids() → frozenset[str]

Fetch all instrument identifiers.

APIClient().instrument() → ExtendedInstrument

Fetch a single instruments.

Parameters:

| name | type | | ---- | -------------------- | | uuid | str or uuid.UUID |

APIClient().models() → list[Model]

Fetch all models.

APIClient().model() → Model

Fetch a single model.

Parameters:

| name | type | | -------- | ----- | | model_id | str |

APIClient().versions() → list[VersionMetadata]

Fetch information of all versions of a file.

Parameters:

| name | type | | ---- | -------------------- | | uuid | str or uuid.UUID |

APIClient().download(list[Metadata]) → list[Path]

Download files from the fetched metadata.

Parameters:

| name | type | default | | ----------------- | ---------------------------------------------- | ----------------- | | metadata | list[RawMetadata] or list[ProductMetadata] | | | outputdirectory | PathLike or str | Current directory | | concurrencylimit | int | 5 | | progress | bool or None | None | | validate_checksum | bool | False |

There's also an asynchronous version of this function: cloudnet_api_client.adownload. It's useful for usage inside Jupyter notebook.

License

MIT