superstac 0.1.0a2

High-availability satellite imagery retrieval across multiple STAC catalogs.

SuperSTAC

SuperSTAC is a Python library (with planned Rust backend) for high-availability satellite imagery retrieval.
Instead of relying on a single STAC endpoint (e.g., Sentinel from Element84), SuperSTAC can query multiple catalogs and automatically fall back to alternatives when a source is missing data or unavailable.

⚠️ Note: This is an early work-in-progress. The initial release is to start iterating in public. Expect breaking changes.

---

Features (planned)

• Query multiple STAC catalogs through a single unified API.
• Automatic fallback when a catalog has no data or is down.
• Configurable authentication for protected catalogs.
• Resolution & band matching across heterogeneous catalogs.
• CLI and Python API for flexible workflows.
• Optional LLM-assisted natural language queries.
• Rust backend (planned)

---

Installation

pip install superstac

Configuration

SuperSTAC loads its catalog configuration from a YAML file, typically referenced via the environment variable SUPERSTAC_CATALOG_CONFIG.

Example .superstac.yml:

catalogs:
  Element84 Sentinel:
    url: https://earth-search.aws.element84.com/v0
  Planet:
    url: https://api.planet.com/stac/v1
    auth:
      type: basic
      username: youruser
      password: yourpass
  Microsoft PC:
    url: https://planetarycomputer.microsoft.com/api/stac/v1
    auth:
      type: bearer
      token: "YOUR_MICROSOFT_PC_TOKEN"

See superstac/.superstac.yml for an example config file.

Usage (very early draft)

  from superstac import get_catalog_registry, federated_search_async

  cr = get_catalog_registry()
  cr.load_catalogs_from_config()

  print("\nRunning asynchronous federated_search_async...")
  start_async = time.perf_counter()
  results_async = asyncio.run(
      federated_search_async(
          registry=cr,
          collections=["sentinel-2-l2a"],
          bbox=[6.0, 49.0, 7.0, 50.0],
          datetime="2024-01-01/2024-01-31",
          query={"eo:cloud_cover": {"lt": 20}},
          sortby=[{"field": "properties.datetime", "direction": "desc"}],
      )
  )
  end_async = time.perf_counter()
  print(
      f"Asynchronous search found {len(results_async)} items in {end_async - start_async:.2f} seconds."
  )

  for x in results_async:
      print(x.self_href)

Also see main.py.

Development Status / Roadmap

Planned enhancements:

• Authentication configuration & documentation
• Retry logic
• Result modifiers
• Catalog refresh & health checks
• Latency tracking and fallback ranking
• Band matching across heterogeneous catalogs
• CLI tool
• Example notebooks (illegal mining detection, disaster response, LLM-assisted search)

License

MIT License. See LICENSE.

Feedback, issues, and contributions are welcome! This package is at a very early stage, so opening issues for missing features or edge cases will directly shape the roadmap.