Skip to main content

terrapi-client

The Python library terrapi-client offers functions to easily work with the terrabyte User data catalog (STAC API). It builds on top of the Python library terrapi for authentication with the terrabyte authentication service.

Installation​

Micromaba (conda) Environment on terrabyte​

Currently the conda packages are only available from local repository on terrabyte.

#add to existing Environment
micromamba install -n <existing Env> -c file:///dss/dsstbyfs01/pn56su/pn56su-dss-0020/opt/terrapi/terrapi-conda-repo terrapi-client 

#alternatively directly install during creation
micromamba create -n <new Env> -c conda-forge -c file:///dss/dsstbyfs01/pn56su/pn56su-dss-0020/opt/terrapi/terrapi-conda-repo terrapi-client dask odc-stac jupyter <... all your other pacakges>

Installation via pip​

It is not recommended to install packages via pip if you created your Environment via conda/micromamba. In this case please use option above

# install dependency terrapi as well 
pip install git+https://github.com/DLR-terrabyte/terrapi.git@latest-release git+https://github.com/DLR-terrabyte/terrapi-client.git@latest-release

Usage​

Create new private/shared STAC Collection​

import pystac
from terrapi.client.stac import open_private_catalog, create_private_collection

# Connect to the terrabyte private STAC API
catalog = open_private_catalog()
#Click on the printed 2FA link and allow access to terrapi in browser Window 

# All private collections are prefixed with your terrabyte/LRZ username
# All shared collections are prefixed with the DSS container id (e.g., pn56su-dss-0001)
prefix = '<your username>'

collection_id = f"{prefix}.testcollection"

collection = pystac.Collection(
    collection_id,
    "description",
    pystac.Extent(
        pystac.SpatialExtent([[-180, -90.180, 90]]),
        pystac.TemporalExtent([[None, None]]),
    ),
)
create_private_collection(catalog, collection)

Create new STAC item in private/shared STAC collection​

from terrapi.client.stac import open_private_catalog, create_private_item
from datetime import datetime

# Connect to the terrabyte private STAC API
catalog = open_private_catalog()

# Create STAC item
geom = {"type": "Point", "coordinates": [0, 0]}
item = pystac.Item("test_item", geom, None, datetime=datetime.now(), properties={})

# Add STAC item within STAC collection
create_private_item(catalog, item, collection_id)

Explore the STAC catalog​

from terrapi.client.stac import open_private_catalog

# Connect to the terrabyte private STAC API
catalog = open_private_catalog()

# list the IDs of all STAC catalog collections
for collection in catalog.get_all_collections():
    print(collection.id)

# Now query a STAC collection
start = datetime.now().replace(hour=0, minute=0, second=0)
end = datetime.now().replace(hour=23, minute=59, second=59)

query = {
    
}

results = catalog.search(
    collections=[f"{prefix}.testcollection"],
    datetime=[start, end],
    query=query,
)
items = results.item_collection_as_dict()
print("%s items found" % len(items['features']))

Delete STAC item​

from terrapi.client.stac import open_private_catalog, delete_private_item

# Connect to the terrabyte private STAC API
catalog = open_private_catalog()

# Delete STAC item within STAC collection
delete_private_item(catalog, item, collection_id)

Delete STAC collection​

from terrapi.client.stac import open_private_catalog, delete_private_collection

# Connect to the terrabyte private STAC API
catalog = open_private_catalog()

# Delete STAC collection
delete_private_collection(catalog, collection_id)