TerraCatalogue: Product Download

Finding product links

The responses from the STAC API can be used for downloading the products in the TerraCatalogue. Authentication is required for the product download.

In STAC, the purpose of each asset can be derived from the ‘roles’ assigned to it. The following roles are often present in the different assets of a STAC Item:

thumbnail or overview provides a link to the preview image of the product.
metadata provides a link to an additional product metadata file (eg. INSPIRE).
data provide links to the actual data assets (e.g. RED, BLUE, B08, FAPAR, ….) of the product.

The default .href of each asset is the HTTP download link. Additionally, the local file path on the Terrascope platform is provided in the .alternate.local.href field.

Tip

It is not necessary to download the products on the Terrascope platform. The data is locally available on the user VM’s and Notebooks.

The responses from the STAC API also contain the links to the local files in your Terrascope environment. This makes local data discovery easier, and allows for easy transfer of processing logic between your own environment and the Terrascope platform. The local file path is provided in the .alternate.local.href field of each asset.

{
  "href": "https://services.terrascope.be/download/Sentinel2/TOC_V2/2026/11/05/S2C_20261105T105221_31UER_TOC_V220/S2C_20261105T105221_31UER_TOC-B04_10M_V220.tif",
  "type": "image/tiff; application=geotiff; profile=cloud-optimized",
  "title": "B04",
  "bands": [
    {
      "name": "B04",
      "eo:common_name": "red",
      "eo:center_wavelength": 0.665,
      "eo:full_width_half_max": 0.038
    }
  ],
  "alternate": {
    "local": {
      "href": "file:///data/MTDA/TERRASCOPE_Sentinel2/TOC_V2/2026/11/05/S2C_20261105T105221_31UER_TOC_V220/S2C_20261105T105221_31UER_TOC-B04_10M_V220.tif"
    }
  },
  "roles": [
    "data"
  ]
}

Authentication

Once you’ve found the neccessary products you need to authenticate your requests to download the files. Terrascope supports several authentication methods, which can be useful in different circumstances.

Interactive authentication

This is the easiest method and can be handy when you need to download individual files directly. When you visit a download link in your browser to download a file manually you will be prompted to authenticate your download. Terrascope supports multiple ways of authentication:

Via the Terrascope platform. Read more about creating a Terrascope account here.
Via an EGI account.

Once you’ve followed the steps of the login flow the file download should begin.

STAC tools

You can use the tools from the STAC ecosystem to discover and download data. For querying the STAC API, we recommend using tools like pystac-client. For downloading, we recommend the stac-asset library. This library has support for authorizing HTTP downloads with OAuth2 access tokens. We provide an example notebook on how to interact with the STAC API and the download service using these tools on GitHub.

Here is a short summary of the steps required:

Install the required Python packages: pystac-client and stac-asset.

pip install pystac-client stac-asset

Query the STAC API using pystac-client to find the products you are interested in.

from pystac_client import Client

client = Client.open("https://stac.terrascope.be")
item_collection = client.search(...)

Use stac-asset to download the assets of the selected products, handling authentication as needed.

import stac_asset

# authentication configuration for OAuth2 device code flow
config = stac_asset.Config(
  oauth2_grant="device_code",
  oauth2_token_url="https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token",
  oauth2_device_authorization_url="https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/auth/device",
  oauth2_client_id="public",
)
# download the item collection using the configured authentication
await stac_asset.download_item_collection(
  item_collection,
  directory="./Downloads",
  config=config,
)

Machine authentication

If you do not use Python or want to build your own processing logic it is also possbile to authenticate by setting the Authorization header of your HTTP requests. Terrascope supports both the Basic and Bearer credentials.

An example notebook has been made available which walks you through the usage of both authentication methods. It can be viewed on GitHub or directly in the Terrascope JupyterLab envrionment.

Basic auth

Basic authentication uses a Base64 encoded combination of your Terrascope username and password to complete the Authorization header of your request. An example of a basic authentication header can be found here.

Bearer auth

Authenticating using bearer tokens requires an access token. This token is requested using your terrascope credentials and is valid for a limited time (300 seconds). When the token expires you can either request a new token using your credentials or by using the refresh token which was included in the initial token request response. Please consult the documentation for additional information on token-based authentication.

When you need to download many products it can be useful to handle token refreshes automatically. Most languages offer ways to handle this process. An example implementation has been made in python and can be found in the sample notebook linked above.

Rate limiting

Downloads are rate limited based on IP address:

80 requests per 10 seconds
200 requests per 60 seconds

GDAL support

With basic authentication, the products can also be accessed via the GDAL network based file system. For example reading a WorldCover product:

export GDAL_HTTP_AUTH=BASIC
export GDAL_HTTP_USERPWD=${USERNAME}:${PASSWORD}
gdalinfo /vsicurl/https://services.terrascope.be/download/WORLDCOVER/ESA_WORLDCOVER_10M_2020_V100/MAP/ESA_WorldCover_10m_2020_v100_N00E006_Map/ESA_WorldCover_10m_2020_v100_N00E006_Map.tif

Or directly in-line:

gdalinfo /vsicurl/https://${USERNAME}:${PASSWORD}@services.terrascope.be/download/WORLDCOVER/ESA_WORLDCOVER_10M_2020_V100/MAP/ESA_WorldCover_10m_2020_v100_N00E006_Map/ESA_WorldCover_10m_2020_v100_N00E006_Map.tif