SuperSTAC (Python)

Many catalogs. One search.

Search across STAC catalogs through one interface, with Python, Rust, or the command line.

This package provides the Python bindings for SuperSTAC.

Status: alpha. APIs are not yet stable. Pre-1.0; expect breaking changes.

superstac provides a synchronous Client and an AsyncClient for asyncio. Results are Python dictionaries. Some method names resemble pystac-client, but this is not a drop-in replacement.

Documentation

Read the SuperSTAC documentation for installation, tutorials, and API guides.

• Quickstart
• Python guide
• Rust guide
• Command-line guide
• Configuration reference

Try the Python quickstart notebook for a two-catalog search, footprint map, and GeoJSON export in Colab or Jupyter.

Upgrading from 0.1.0a2

Version 0.2.0 replaces the old Python implementation with a Rust engine. Use from superstac import Client, AsyncClient and follow the Python guide to migrate. Results are dictionaries, matched() counts returned items, and to_geojson() exports a FeatureCollection. Custom authentication hooks and the full pystac-client API are not supported. CPython 3.9 or newer is required.

Install

pip install superstac

Or from source:

git clone https://github.com/spatialnode/superstac
cd superstac/crates/python
pip install maturin
maturin develop

Quickstart

Search a single catalog

from superstac import Client

client = Client.open("https://earth-search.aws.element84.com/v1")

search = client.search(
    collections=["sentinel-2-l2a"],
    bbox=[6.0, 49.0, 7.0, 50.0],
    datetime="2024-01-01/2024-01-31",
    limit=50,
)

for item in search.items():
    print(item["id"], item["properties"]["datetime"])

print(search.matched(), "items")
fc = search.to_geojson()    # GeoJSON FeatureCollection dict

Federated across multiple catalogs

Pass a YAML-shaped dict in one call:

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"},
    ],
    "settings": {"deduplicate_items": True, "max_concurrent_catalogs": 8},
})
client.start()

search = client.search(collections=["sentinel-2-l2a"], limit=50)
items = list(search.items())
print(search.metadata)   # per-catalog stats: queried, succeeded, failed, dedupes

Or build it up incrementally (any combination is fine):

client = Client()
client.add_catalogs([
    {"id": "earth-search", "url": "https://earth-search.aws.element84.com/v1"},
    {"id": "microsoft",    "url": "https://planetarycomputer.microsoft.com/api/stac/v1"},
])
client.update_settings({"deduplicate_items": True})
client.start()

Async

import asyncio
from superstac import AsyncClient

async def main():
    client = await AsyncClient.open("https://earth-search.aws.element84.com/v1")
    search = await client.search(collections=["sentinel-2-l2a"], limit=50)
    for item in search.items():
        print(item["id"])
    await client.shutdown()

asyncio.run(main())

Load from YAML

client = Client.from_yaml("superstac.yml")          # sync
client = AsyncClient.from_yaml("superstac.yml")     # async

License

MIT.