First Steps/Workflow

# installation with pip optional with dependencies
# !pip install terragon-downloader[pc]

import geopandas as gpd
import terragon

First you need to initialize the module and specify which data provider should be used. Most APIs also require some authentification, they are provided as dictonary. We will use planetary-computer here.

tg = terragon.init("pc")
# for other data sources you may need to provide credentials, for example:
# credentials = {'username': <your_username>, 'password': <your_password>}
# tg = terragon.init('pc', credentials=credentials)

The idea is to specify all of your parameters in the create function and receive a xarray Dataset.

gdf = gpd.read_file("data/TUM_OTN.geojson")
args = dict(
    shp=gdf,  # the geodataframe including the geometry and CRS (required)
    collection="sentinel-2-l2a",  # the name of the collection (required)
    bands=["B02"],  # a list of bands of the collection to download
    start_date="2021-01-01",  # the start date of the time range as string
    end_date="2021-01-05",  # the end date of the time range as string
    resolution=10,  # the resolution in meters
    clip_to_shp=True,  # clip the data to the shapefile extent or receive the bounding box (default: True)
    download_folder="eo_download",  # the folder to save the downloaded and temporary data (default: 'eo_download')
    num_workers=1,  # number of workers to use for downloading, currently only for gee (default: 1)
    create_minicube=True,  # create a minicube, otherwise save the data as .tif files (default: True)
)
tg.create(**args)

The ‘create’ function is a shortcut for the ‘search’ and ‘download’ function. Search takes the same parameters as the create function and returns the items which should be downloaded. If needed one can manually filter the items. The download function takes the items, downloads and merges them into a minicube as xarray Dataset.

items = tg.search(**args)
print(items)
# here we will filter by taking the first item only
items = item[:1]
tg.download(items)

Saving meta data as coordinates

# this parameter allows you to save metadata as coordinates in the minicube, this can be useful for saving ids, orbit directions, etc.
args["save_metadata"] = ["id", ...]  # list of metadata fields to save in the minicube
tg.create(**args)