omnilab/earthdata API reference

Omnilab\Earthdata

EarthdataSource class

final class EarthdataSource extends HttpSource EarthdataSource.php:37

NASA Earthdata's Common Metadata Repository (cmr.earthdata.nasa.gov/ search): the granules of NASA's Earth observation collections - MODIS, VIIRS, the Harmonized Landsat Sentinel-2 (HLS), GPM, SMAP, ICESat-2, the OPERA products... - as products, by collection, point or box, period and cloud cover, page by page; and the collections themselves, searched by text (datasets()). Searching needs no account.

A granule's assets are its files as the CMR lists them: an https:// address at its archive (a DAAC), its s3:// one in AWS as the alternate, its browse image (open, the product's preview). Downloading the files needs an Earthdata Login token (a free account): give it as the token option and open() sends it - the search never needs it, though the CMR shows an account the restricted collections it may see.

const BASE_URI = 'https://cmr.earthdata.nasa.gov/search/'

const MAX_PER_PAGE = 2000

The most granules or collections the CMR answers a page.

const STAC_PER_PAGE = 50

The most items asked of the CMR's STAC a page: 50 answered (12.7 s for a year of HLS over Strasbourg), 100 and 250 a 502 each time on 2026-10-15.

EarthdataSource::__construct()

public function __construct(HttpClientInterface $http, readonly array $collections = [], readonly ?string $token = null, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = 0.0, readonly ?string $stac = null)

$collections

what a query that names none searches

$token

an Earthdata Login token, sent with open() (and to the CMR, which then shows the account's restricted metadata)

$stac

an archive's id (LPCLOUD...): its granules read through the CMR's STAC catalogue, by the core's STAC reader, rather than the CMR's own search

EarthdataSource::getName()

public function getName(): string

EarthdataSource::capabilities()

public function capabilities(): array

EarthdataSource::products()

public function products(ProductQuery $query): Page

The granules of the collections named (CMR concept ids, C2021957295- LPCLOUD, or entry ids: the short name and version, HLSS30_2.0, MOD09GA_061 - the CMR STAC's collection ids too) over the place and the period, under the cloud cover, newest first.

EarthdataSource::datasets()

public function datasets(Query $query): Page

The collections that match a text (the CMR's keyword search: titles, abstracts, science keywords, platforms...), the best match first, a page at a time: the contract's datasets(), each collection a Product whose id is the entry id that products() takes.

EarthdataSource::open()

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

A file of a granule (an asset, or its address), opened with the Earthdata Login token (the contract's open()): the response, streamed, not read - the application reads it (getContent(), or stream()) or saves it. The archive redirects to the file's store; a refusal is the archive's (401, or a redirection to the login page).

EarthdataSourceFactory class

final class EarthdataSourceFactory extends SourceFactory EarthdataSourceFactory.php:23

NASA Earthdata's Common Metadata Repository: the granules of NASA's Earth observation collections by place, period and cloud cover, and the collections by text - no account needed to search.

options: collections: [] # what a query that names none searches: entry ids (HLSS30_2.0) or concept ids token: ~ # an Earthdata Login token (urs.earthdata.nasa.gov, a free account), for open(): downloading the files mailto: 'support@glitchr.io' # in the User-Agent stac: ~ # an archive's id (LPCLOUD, POCLOUD...): read its granules through the CMR's STAC catalogue rather than the CMR's own search (the default, faster, every archive at once) throttle: 0 # seconds between two calls base_uri: 'https://cmr.earthdata.nasa.gov/search/' # or the UAT's: https://cmr.uat.earthdata.nasa.gov/search/

Options