STAC search internals
How the STAC search tab talks to APIs, static catalogs and the federation, why it uses no STAC client library, and what a stac-geoparquet reader would add
The STAC search tab (components/TerrainControlPanel/stac-search-panel.tsx, presets in lib/stac-presets.ts) is plain fetch code. Three kinds of catalog, one UI:
- API (
kind: "api"):POST {root}/searchwithbbox,datetime,collections,limit, paged through thenextlink. Cloud cover goes to the server through the query extension and the plain search is retried if the server refuses it. Collections come from/collections, paged, handed to the list as each page lands. - Static (
kind: "static"): no server to search, so the catalog is crawled breadth first from its root (or the chosen collection): sixteen nodes fetched at a time, four levels deep,childanditemlinks resolved against their document (absolute links to other hosts included, if those hosts allow CORS). A collection whose spatial extent misses the view or whose temporal extent misses the date window is skipped whole. Item links are collected up to four times the result cap, then the items are fetched sixteen at a time and kept when their bbox, datetime and cloud cover pass. Catalog and collection documents are cached for the session; items are not. Fetching every item JSON is where the time goes on a large catalog, by design: there is no index to read instead. - Discovery (
kind: "discovery", the MAAP federation): a collection search only; items come from the chosen collection's ownitemslink withbboxanddatetimeas query parameters.
Auth: a preset's auth names a scheme; Planet's /x/data takes an OpenID access token as a Bearer (see the preset note).
Copernicus Data Space Ecosystem (CDSE)
Two presets point at https://stac.dataspace.copernicus.eu/v1: CDSE (basemap dialog, Sentinel-2 L2A preselected) and Copernicus DEM GLO-30 / GLO-90 (CDSE) (terrain dialog). The API is a pgstac deployment: CORS-open (*, preflight allows Content-Type and Authorization), item search with query, filter (CQL2) and sort, POST next links carrying a token (followed by the pager as is), about 430 collections in one /collections?limit=200 page. It rate-limits: a burst of a dozen searches gets 429.
The catalog is open; the data is not open to a browser. Checked with anonymous requests on 2026-11-14:
| Collection | Assets | Browser-readable | Why |
|---|---|---|---|
sentinel-2-l2a, sentinel-2-l1c | JPEG 2000 bands in a SAFE product, TCI included | No | s3://eodata/… (S3 keys); the alternate.https copies on download.dataspace.copernicus.eu answer 401 without a login token (auth:refs: ["oidc"]); and JPEG 2000 has no in-browser reader here anyway |
sentinel-1-grd | COGs (VV, VH) in a SAFE folder | No | same two hosts, same login; the COGs are also in radar geometry (no CRS, GCPs only) |
cop-dem-glo-30-dged-cog, cop-dem-glo-90-dged-cog | One COG per 1° tile, EPSG:4326 | Yes, via the AWS copy | s3://eodata/auxdata/CopDEM_COG/… only, no https alternate; the same tile names are on AWS Open Data (copernicus-dem-30m / -90m buckets, keyless, Range-capable, no CORS), so the panel rewrites the href and pins it to titiler. The AWS release may lag CDSE's |
cop-dem-eea-10-laea-tif | Plain GeoTIFF + zip | No | s3:// and a login; the 10 m EEA DEM is restricted (Copernicus services only) |
landsat-c2-l1-* | COG bands | No | s3:// and the login-only download service; the thumbnail is s3:// too |
sentinel-3-*, sentinel-5p-*, sentinel-6-* | netCDF (inside a SAFE for Sentinel-3) | No | format, plus the same two hosts |
modis-* | HDF4 | No | format, plus the same two hosts |
sentinel-2-global-mosaics, sentinel-1-global-mosaics, opengeohub-landsat-…, clms_*_cog | COGs | No | s3:// and the login-only download service (some alternate.https hrefs are the literal string zipper) |
Quicklooks (thumbnail asset) | JPEG/PNG | Yes | datahub.creodias.eu redirects to zipper.creodias.eu, 200 with CORS, served as application/octet-stream (fine in an <img>, a download if opened) |
Thumbnails on thumbnails.dataspace.copernicus.eu | PNG from a WMS | Partly | public, but only at a fixed list of sizes per product: the Landsat mosaic items ask for 500×500 and get 403 |
So the panel lists every CDSE item with nothing addable as a "catalog only" row (catalogOnly in stac-search-panel.tsx, reasons from blockedReason in lib/cdse.ts): quicklook when public, a footprint glyph against the searched view (the dialog hides the map), the reason in one sentence, and a link to the Copernicus Browser at the item's place and day, on its dataset (datasetId / layerId from the Browser's own public/datasets.txt; a collection without a known id links to the place and date only, because an unknown id makes the Browser switch to Sentinel-2 with an error). The same row appears for any catalog whose data assets are all credentialed (NASA CSDA's DEMs). s3:// COGs are no longer offered as buttons that would fail. CDSE is left out of the historical timeline's catalogs: its ticks would draw nothing.
With an account (built 2026-11-14): the Sentinel Hub OGC services on sh.dataspace.copernicus.eu/ogc/wmts/{instance id} answer with CORS for the calling origin and authenticate by the configuration id alone. The visitor pastes it in Settings, API Keys (sentinelHubInstanceIdAtom, localStorage; a local VITE_SENTINEL_HUB_INSTANCE_ID seeds it on the dev server and vite.config.ts empties it in builds, like the Planet key). Sentinel-2 rows then get a True colour via your Sentinel Hub button: the configuration's TRUE_COLOR layer as WMTS (PopularWebMercator256, a standard Google grid), TIME=<day>/<day> and MAXCC=100, without which a scene over the configuration's cloud limit comes back as an empty 334-byte tile. The layer starts at z10: Sentinel Hub refuses Sentinel-2 coarser than 200 m a pixel and returns a "pixel size exceeds limit" warning image instead (layers saved from the WMTS picker on that host get the same floor). The WMTS picker has a button listing the configuration's layers. Every saved URL carries {shInstance} instead of the id (maskKeys / fillKeyPlaceholders in lib/key-placeholders.ts), filled when tiles are requested, so links and exports never hold it. Both CDSE presets are requiresCollection: the API answers 400 CollectionInQuerryIsMissingError to a search without one, and the panel now says so before asking. How a user gets the id: API keys.
Browse from the Library
A Library entry in lib/custom-sources.json can carry a catalog search for its data (LibraryStacLink in lib/settings-atoms.ts):
"stac": { "preset": "pgc", "collection": "arcticdem-strips-s2s041-2m" }preset is an id in STAC_PRESETS. collection is the collection id for an API catalog; for a static catalog it is the absolute URL of the child collection.json (that is how the panel identifies a static collection), for instance https://nz-elevation.s3.ap-southeast-2.amazonaws.com/new-zealand/new-zealand/dem_1m/2193/collection.json. Leave it out to search the whole catalog. An entry with the field gets a Browse button beside its +.
Datasets with no mosaic, only a collection, go in their own list, SAMPLE_TERRAIN_BROWSE_ONLY, with id, name, stac and optionally description, infoUrl, resolutionM, bounds and loadWithSamples (LibraryBrowseEntry). They are kept out of SAMPLE_TERRAIN_SOURCES because everything else that reads that list (coverage footprints, Load all, ?sourceA= ids, the docs tables, the STAC export) expects a URL to load. The Library merges them into its sections, where only the name (Global - ), bounds and loadWithSamples: false place them, since they are not in the file's order. Check a new collection id against the live endpoint before adding it.
The click reuses the Catalogs section's handoff: seedStacPreset(target, preset, { collection, search: true }) seeds the panel's remembered state, the section closes the Library, and the Add dialog opens on the catalog tab 220 ms later. On mount the panel keeps the seeded collection through the catalog's first collection listing (which used to reset it to all collections, so a preset's own collection never reached the picker either) and, with search, runs one search over the current view.
Why no client library
What this tab needs is the union of API search, a bounded static crawl with bbox and time pruning, pagination, a collection listing that streams, CORS-aware error messages and per-catalog auth. No npm package bundles that: stac-js and stac-ts are typings and model helpers over documents you fetched yourself, pystac-client has no browser port, and stac-map (Development Seed) also fetches with its own code, plus DuckDB-wasm for stac-geoparquet. A wrapper would have added weight without removing any of the code above.
stac-geoparquet, later
Some catalogs ship their items as one stac-geoparquet file (Source Cooperative repositories often do; stac-map reads them with DuckDB-wasm). Reading it in the browser with hyparquet (pure JS, small) and pruning row groups on the bbox column would replace the item-by-item crawl for those catalogs. What is missing is a convention for finding the file from a catalog: STAC has no standard link for it yet, so each catalog would need its own pointer. Not built; noted here so the next person does not start from zero.