Your first search

Install SuperSTAC first. This example searches Sentinel-2 imagery in Earth Search and Microsoft Planetary Computer.

You can also run the Python notebook in Colab or Jupyter to see the results on a map and download them.

1. Register your catalogsCopy Anchor Link

For the CLI, save this file as superstac.yml in your working directory, or download it. The Python example below defines its catalogs directly, so you can skip the file unless you want to share a configuration.

providers: []

catalogs:
  - id: earth-search
    url: https://earth-search.aws.element84.com/v1
  - id: microsoft
    url: https://planetarycomputer.microsoft.com/api/stac/v1

settings:
  health_check_strategy: hourly
  healthy_status_code_range: [200, 299]
  auto_fix_duplicate_catalog_id: true
  auto_fix_duplicate_provider_id: true
  log_level: info
  logging_enabled: true
  search_healthy_catalogs_only: true
  deduplicate_items: true
  unify_response: true
  max_concurrent_catalogs: 8
  per_catalog_timeout_seconds: 30
  max_retry_attempts: 2
  retry_initial_backoff_ms: 100
  retry_max_backoff_ms: 2000
  max_items_per_catalog: 1000

Use the complete YAML

Keep catalogs, providers, and the required fields in settings, even if you leave providers empty. Python dictionaries can omit settings that YAML requires; see configuration for details.

2. Search an area and time rangeCopy Anchor Link

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 first search also checks whether catalogs are reachable and which collections they offer. It can take longer than later searches.

3. Understand the responseCopy Anchor Link

limit=5 asks for up to five items from each catalog. With two catalogs, you can get up to ten items before duplicate IDs are removed. More matching scenes may exist.

Check search.metadata as well as the items. catalogs_queried tells you how many catalogs were searched; catalogs_failed and failures tell you what went wrong. If no items come back, these fields help you distinguish an empty search from an unavailable catalog.

4. Export the itemsCopy Anchor Link

import json
from superstac import Client

client = Client.open("https://earth-search.aws.element84.com/v1")
try:
    search = client.search(collections=["sentinel-2-l2a"], limit=5)
    with open("items.geojson", "w") as output:
        json.dump(search.to_geojson(), output)
finally:
    client.shutdown()

This writes item metadata, not satellite image pixels. Accessing an asset URL may require provider-specific authentication or signing.

Continue with Python, Rust, or configuration.