omnilab/cds API reference

Omnilab\Cds

CdsSource class

final class CdsSource extends HttpSource implements JobSourceInterface CdsSource.php:42

An ECMWF data store (the software behind the Copernicus Climate Data Store, cds.climate.copernicus.eu, and the Atmosphere Data Store, ads.atmosphere.copernicus.eu - one API, two catalogues): its datasets (ERA5, ERA5-Land, CAMS's forecasts and reanalyses...) as products, and the requests that make a file of one of them.

Read without an account: the catalogue (products(), datasets(), dataset() with its variables) and what a request would cost (cost()). With a personal access token (the key option, sent as PRIVATE-TOKEN): submit() a request, follow it (job(), jobs()) until its Product holds the file to download as its "data" asset - a NetCDF, GRIB or zip the application reads with its own tools: this source decodes nothing.

A request is asynchronous on the service's side: accepted, queued, running, then successful (or failed, rejected, dismissed); the source never waits - the application asks job() again.

const CDS_URI = 'https://cds.climate.copernicus.eu/api/'

const ADS_URI = 'https://ads.atmosphere.copernicus.eu/api/'

const ACCEPTED = Job::ACCEPTED

A request's states: queued, running, done, and the ends without a file (the core's Job's).

const RUNNING = Job::RUNNING

const SUCCESSFUL = Job::SUCCESSFUL

const FAILED = Job::FAILED

const REJECTED = Job::REJECTED

const DISMISSED = Job::DISMISSED

const MAX_PER_PAGE = 100

The most datasets a page of the catalogue's search answers.

CdsSource::__construct()

public function __construct(HttpClientInterface $http, readonly string $name = 'cds', string $baseUri = self::CDS_URI, readonly ?string $key = null, array $headers = [], float $throttle = 0.0)

$name

what the source is configured as: "cds", "cams" (the Atmosphere Data Store)...

$baseUri

the store's API, ending in /api/

$key

an account's personal access token, for submit(), job() and jobs()

CdsSource::getName()

public function getName(): string

CdsSource::capabilities()

public function capabilities(): array

CdsSource::products()

public function products(ProductQuery $query): Page

The store's datasets that cover the place and overlap the period (every one when the query says neither), each a Product: its footprint, its period, its catalogue's properties, its thumbnail.

The most recently updated first (oldest first with ProductQuery::OLDEST).

CdsSource::datasets()

public function datasets(Query $query): Page

The catalogue's datasets that match a text, the best match first (its own search: titles, descriptions, keywords), a page at a time: the contract's datasets().

CdsSource::dataset()

public function dataset(string $id): ?Product

One dataset by its id, with what a request of it takes: its inputs ("inputs", by name: their title and their values, when the form lists them) and its variables ("variables"). Null when unknown.

CdsSource::cost()

public function cost(string $dataset, array $request): array

What a request would cost against the store's limit, before it is submitted - no account needed: ["cost" => 6.0, "limit" => 121000.0, "valid" => true, "reason" => null]. A request over its limit, or that the store finds invalid, would be refused.

$request

the dataset's inputs: ["variable" => ["2m_temperature"], "year" => ["2025"], ...]

CdsSource::submit()

public function submit(string $dataset, array $request): Job

Submits a request for a file of a dataset; the store queues it. Its Product: the job's id, the dataset as its collection, its status (accepted, mostly) in properties. Needs the key, and the dataset's licence accepted by the account on the store's site (a 403 before).

$request

the dataset's inputs (dataset() lists them)

CdsSource::job()

public function job(string $id): ?Job

A submitted request, as the store has it now; once successful, its file is the Product's "data" asset (its address, type, size; the checksum in properties). Null when the store does not know it (or no longer: results are kept for a while, then deleted).

CdsSource::jobs()

public function jobs(ProductQuery $query = new ProductQuery()): Page

The account's requests, the newest first (oldest first with ProductQuery::OLDEST), a page at a time; without their files (job() reads one's). The store lists them all together: a query that names datasets, a place or a period is refused.

CdsSource::open()

public function open(Asset|string $file): ResponseInterface

A job's file (its "data" asset, or its address) read with the key when there is one: the response, streamed. Nothing is decoded (a NetCDF, a GRIB, a zip).

CdsSourceFactory class

final class CdsSourceFactory extends SourceFactory CdsSourceFactory.php:21

The Copernicus Climate Data Store: its datasets (ERA5, ERA5-Land, the seasonal forecasts, the climate projections...) as products, read without an account; with an account's key, the requests for their files.

options: key: ~ # the personal access token of a CDS account (its profile page), for submit(), job() and jobs() mailto: 'support@glitchr.io' # in the User-Agent throttle: 0 # seconds between two calls base_uri: 'https://cds.climate.copernicus.eu/api/' # another ECMWF data store: its /api/ address

Options