Catalogs and discovery
Register STAC APIs, group them with providers, and discover which collections they serve.
Register a catalog
Give each endpoint a distinct ID and an explicit URL. Use simple ASCII identifiers such as earth-search or my-catalog.
from superstac import Client
client = Client()
client.add_catalog({
"id": "earth-search",
"title": "Earth Search",
"url": "https://earth-search.aws.element84.com/v1",
})
try:
client.start()
print(client.list_collections())
finally:
client.shutdown()Always provide the root url of a compatible STAC API. A link to a static catalog JSON file will not work.
Group catalogs by provider
Use providers to group catalogs by organization. Provider records hold names and descriptions, not login credentials.
from superstac import Client
client = Client()
client.add_provider({"id": "element84", "name": "Element 84"})
client.add_catalog(
{"id": "earth-search", "url": "https://earth-search.aws.element84.com/v1"},
provider="element84",
)
print(client.list_catalogs())Add the provider first, then pass its ID as provider when adding a catalog. The provider’s catalog_ids field is currently ignored when loading configuration.
Discover collection availability
from superstac import Client
client = Client.open("https://earth-search.aws.element84.com/v1")
try:
print(client.list_collections())
print(client.collections_by_catalog())
print(client.catalogs_supporting("sentinel-2-l2a"))
collection = client.describe_collection("earth-search", "sentinel-2-l2a")
if collection is not None:
print(collection["id"])
finally:
client.shutdown()list_collections() returns {"id": ..., "catalogs": [...]} records showing where each collection is available. Use get_collections() when you need full collection documents; it can make a separate request for each collection.
Add, update, or remove catalogs
add_catalogs(), get_catalog(), list_catalogs(), update_catalog(), and delete_catalog() operate on the in-memory registry. Register catalogs before starting the client so the initial health checks and discovery cover them.
If you add catalogs after startup, call shutdown() and then start() to run startup discovery again. Calling start() while already started is a no-op.
Include the existing title and description when updating a catalog if you want to keep them; leaving them out can clear them. Changes are held in memory and disappear when you discard the client. Update your configuration file separately to keep them for the next run.
