SuperSTAC

Many catalogs. One search.

Search STAC catalogs from Python, Rust, or the command line. Query Earth Search, Microsoft Planetary Computer, and other catalogs together, then work with the results in one place.

SuperSTAC can use your preferred collection and band names, remove duplicate item IDs, and report failed catalogs. If you often search the same area, save its metadata to GeoParquet and search it locally. Imagery stays with the provider.

SuperSTAC is alpha software. APIs and configuration may change before v1.0.

Documentation · What’s new in v0.3 · Try a notebook

Start with Python

Use Python 3.9 or newer:

python -m pip install superstac

Search Sentinel-2 imagery in two catalogs:

from superstac import Client

client = Client(catalogs=[
    {"id": "earth-search", "url": "https://earth-search.aws.element84.com/v1"},
    {"id": "microsoft", "url": "https://planetarycomputer.microsoft.com/api/stac/v1"},
])
try:
    search = client.search(
        collections=["sentinel-2-l2a"],
        bbox=[6.0, 49.0, 7.0, 50.0],
        datetime="2024-01-01T00:00:00Z/2024-01-31T23:59:59Z",
        limit=5,
    )
    for item in search.items():
        print(item["id"], item["collection"])
    print(search.metadata)
finally:
    client.shutdown()

The limit applies to each catalog, so this can return up to ten items before duplicate IDs are removed. Check search.metadata["failures"] for any catalogs that failed. Results are Python dictionaries; search.to_geojson() returns a GeoJSON FeatureCollection.

See the Python guide for more examples, including asyncio.

Use the command line

Build with Rust 1.88 or newer:

git clone https://github.com/spatialnode/superstac
cd superstac
cargo install --path crates/cli --features geoparquet
cp docs/public/examples/superstac.yml ./superstac.yml

The sample configuration includes Earth Search and Microsoft Planetary Computer. Edit it to use your own catalogs, then run:

# List available collections
superstac collections

# Search both catalogs
superstac search -c sentinel-2-l2a -b 6.0,49.0,7.0,50.0 -l 5

# Read search metadata as JSON
superstac --json search -c sentinel-2-l2a -l 5 | jq '.metadata'

Run superstac --help for commands and options. The configuration reference explains aliases, timeouts, and retries.

Save metadata for repeated searches

GeoParquet inventories let you reuse metadata for an area and date range. Search saved data only, or use automatic mode to query live catalogs when the saved data is too old or does not cover your query. Python wheels include GeoParquet support.

Try the GeoParquet notebook · Read the guide · See the benchmark

Use Rust

cargo add superstac-core superstac-config superstac-search superstac-engine
cargo add tokio --features macros,rt-multi-thread

The Rust guide has a complete search example. Use superstac-engine to manage catalogs and run searches; superstac-core, superstac-config, and superstac-search provide the types, configuration loading, and search queries.

Help and contributing

For unexpected results, start with troubleshooting. To report a bug, open an issue with your version, query, and failure metadata. Remove credentials from any configuration you share.

See ROADMAP.MD for planned work.

License

MIT.