eomatch.query.query

Contents

eomatch.query.query#

eomatch.query.query(api_url: str, output_path: str, collections: List[str] | None = None, start_time: datetime | None = None, end_time: datetime | None = None, bbox: List[float] | None = None, filter_expr: str | None = None, filter_lang: str = 'cql2-text', config=None) → Catalog[source]#

Pull items from a STAC API and write them to a local pystac catalogue.

Searches the STAC API at api_url using the supplied filters and writes matching items to output_path in the same on-disk layout that MatchupCatalogue produces, so the result can be opened immediately with MatchupCatalogue.open().

Items referenced via related or derived_from links (matchup items and source product items) are fetched automatically even if they are not in the requested collections, so that get_events() works on the result without requiring network access.

If a catalogue already exists at output_path (from a previous run or from find_and_catalogue()), new items are merged in and the catalogue is resaved. Existing items are replaced with the API version (upsert semantics).

Requires the pystac_client package (pip install eomatch[query]).

Example usage:

from eomatch.query import query

query(
    api_url="http://my-server:8000/external/",
    output_path="/data/my_matchups",
    collections=["LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A"],
    start_time=datetime(2022, 1, 1),
    end_time=datetime(2022, 12, 31),
    filter_expr="time_diff_s < 900 AND land_fraction < 0.2",
)
Parameters:

  • api_url – base URL of the STAC API to query (e.g. http://server:8000/external/).

  • output_path – directory to write the local catalogue into.

  • collections – restrict results to these collection IDs. Queries all collections if None.

  • start_time – include only items whose datetime is at or after this value.

  • end_time – include only items whose datetime is at or before this value.

  • bbox – spatial filter as [min_lon, min_lat, max_lon, max_lat].

  • filter_expr – CQL2 filter expression applied server-side, e.g. "time_diff_s < 900 AND land_fraction < 0.2". Requires the STAC API to support the filter extension (pgSTAC does).

  • filter_lang – filter language identifier; "cql2-text" (default) or "cql2-json".

  • config – path to a eomatch YAML config file, or a dict of overrides. Loaded for default settings but all parameters above take precedence.

Returns:

the resulting pystac.Catalog (also saved to disk).

Contents