Configure and use storage clients in the Tilebox Python SDK to access satellite data products from public providers and local file systems.
Tilebox does not host the actual open data satellite products but instead relies on publicly accessible storage providers for data access.
Tilebox ingests available metadata as datasets to enable high performance querying and structured access of the data as xarray.Dataset.In addition to public provider clients, Tilebox also supports a local file system storage client. This is useful when your data is already available on a local disk, a mounted network share, or a synced folder such as Dropbox or Google Drive.Below is a list of the storage providers currently supported by Tilebox.
Local File System (including Dropbox-synced folders)
Use LocalFileSystemStorageClient when your dataset datapoints already reference files on a local or mounted path.This client does not download remote data. Instead, it resolves and validates local paths using each datapoint’s location field.
Python
from pathlib import Pathfrom tilebox.datasets import Clientfrom tilebox.storage import LocalFileSystemStorageClient# Creating clientsclient = Client()storage_client = LocalFileSystemStorageClient(root=Path("/Volumes/data"))# Querying a dataset that stores file locationsdataset = client.dataset("my_org.local.imagery")collection = dataset.collection("ORTHO")data = collection.query(temporal_extent=("2025-01-01", "2025-01-02"), show_progress=True)# Selecting a single datapointselected = data.isel(time=0)# Returns the local path where data already existslocal_path = storage_client.download(selected)print(local_path)# List files relative to the datapoint locationobjects = storage_client.list_objects(selected)print(objects)
The Copernicus Data Space is an open ecosystem that provides free instant access to data and services from the Copernicus Sentinel missions. Check out the ASF Open Data datasets that are available in Tilebox.
To download data products from the Copernicus Data Space after querying them via the Tilebox API, you need to create an account and then generate S3 credentials here.The following code snippet demonstrates how to query and download Copernicus data using the Tilebox Python SDK.
Python
from pathlib import Pathfrom tilebox.datasets import Clientfrom tilebox.storage import CopernicusStorageClient# Creating clientsclient = Client()storage_client = CopernicusStorageClient( access_key="YOUR_ACCESS_KEY", secret_access_key="YOUR_SECRET_ACCESS_KEY", cache_directory=Path("./data"))# Choosing the dataset and collections2_dataset = client.dataset("open_data.copernicus.sentinel2_msi")collection = s2_dataset.collection("S2A_S2MSI2A")# Loading metadatas2_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)# Selecting a data point to downloadselected = s2_data.isel(time=0) # index 0 selected# Downloading the datadownloaded_data = storage_client.download(selected)print(f"Downloaded granule: {downloaded_data.name} to {downloaded_data}")print("Contents: ")for content in downloaded_data.iterdir(): print(f" - {content.relative_to(downloaded_data)}")
For cases where only a subset of the available file objects for a product is needed, you may restrict your download to just that subset. First, list available objects using list_objects, filter them, and then download using download_objects.For example, a Sentinel-2 L2A product includes many files such as metadata, different bands in multiple resolutions, masks, and quicklook images. The following example shows how to download only specific files from a Sentinel-2 L2A product.
Python
s2_dataset = client.dataset("open_data.copernicus.sentinel2_msi")collection = s2_dataset.collection("S2A_S2MSI2A")s2_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)selected = s2_data.isel(time=0) # download the first granule in the given time rangeobjects = storage_client.list_objects(selected)print(f"Granule {selected.granule_name.item()} consists of {len(objects)} individual objects.")# only select specific objects to downloadwant_products = ["B02_10m", "B03_10m", "B08_10m"]objects = [obj for obj in objects if any(prod in obj for prod in want_products)] # remove all other objectsprint(f"Downloading {len(objects)} objects.")for obj in objects: print(f" - {obj}")# Finally, download the selected datadownloaded_data = storage_client.download_objects(selected, objects)
Many Copernicus products include a quicklook image. The Tilebox storage client includes support for displaying these quicklook images directly when running in an interactive environment such as a Jupyter notebook.
Python
s2_dataset = client.dataset("open_data.copernicus.sentinel2_msi")collection = s2_dataset.collection("S2A_S2MSI2A")s2_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)selected = s2_data.isel(time=0) # download the first granule in the given time rangestorage_client.quicklook(selected)
The United States Geological Survey (USGS) provides a wide range of Earth observation data, including Landsat data, which are also available as open data through Tilebox.
Landsat data is available in a S3 bucket. The following code snippet demonstrates how to query and download Landsat data using the Tilebox Python SDK.
The USGS Landsat S3 bucket is a requester-pays bucket.
This means that you will need to have an AWS account to access the data, and then have your AWS credentials configured in your environment.
Check out the boto3 documentation for more information on how to configure your credentials.
Python
from pathlib import Pathfrom tilebox.datasets import Clientfrom tilebox.storage import USGSLandsatStorageClient# Creating clientsclient = Client()storage_client = USGSLandsatStorageClient()# Choosing the dataset and collectionl9_dataset = client.dataset("open_data.usgs.landsat9_oli_tirs")collection = l9_dataset.collection("L2_SR")# Loading metadatal9_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)# Selecting a data point to downloadselected = l9_data.isel(time=0) # index 0 selected# Downloading the datadownloaded_data = storage_client.download(selected)print(f"Downloaded granule: {downloaded_data.name} to {downloaded_data}")print("Contents: ")for content in downloaded_data.iterdir(): print(f" - {content.relative_to(downloaded_data)}")
For cases where only a subset of the available file objects for a product is needed, you may restrict your download to just that subset. First, list available objects using list_objects, filter them, and then download using download_objects.For example, a Landsat 9 L2 SR product includes many files such as metadata, different bands in multiple resolutions, masks, and quicklook images. The following example shows how to download only specific files from a Landsat 9 L2 SR product.
l9_dataset = client.dataset("open_data.usgs.landsat9_oli_tirs")collection = l9_dataset.collection("L2_SR")l9_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)selected = l9_data.isel(time=0)objects = storage_client.list_objects(selected)print(f"Granule {selected.granule_name.item()} consists of {len(objects)} individual objects.")rgb_bands = ["B4", "B3", "B2"]objects = [obj for obj in objects if any(obj.endswith(band + ".TIF") for band in rgb_bands)]print(f"Downloading {len(objects)} objects.")for obj in objects: print(f" - {obj}")# Finally, download the selected datadownloaded_data = storage_client.download_objects(selected, objects)
Many USGS products include a quicklook image. The Tilebox storage client includes support for displaying these quicklook images directly when running in an interactive environment such as a Jupyter notebook.
Python
# Loading metadatal9_dataset = client.dataset("open_data.usgs.landsat9_oli_tirs")collection = l9_dataset.collection("L2_SR")l9_data = collection.query(temporal_extent=("2024-08-01", "2024-08-02"), show_progress=True)# Selecting a data point to downloadselected = l9_data.isel(time=0) # index 0 selected# Displaying a quicklook imagestorage_client.quicklook(selected)
You can query ASF metadata without needing an account, as Tilebox has indexed and ingested the relevant metadata. To access and download the actual satellite products, you will need an ASF account.You can create an ASF account in the ASF Vertex Search Tool.The following code snippet demonstrates how to query and download ASF data using the Tilebox Python SDK.
Python
from pathlib import Pathfrom tilebox.datasets import Clientfrom tilebox.storage import ASFStorageClient# Creating clientsclient = Client()storage_client = ASFStorageClient( user="YOUR_ASF_USER", password="YOUR_ASF_PASSWORD", cache_directory=Path("./data"))# Choosing the dataset and collectioners_dataset = client.dataset("open_data.asf.ers_sar")collection = ers_dataset.collection("ERS-2")# Loading metadataers_data = collection.query(temporal_extent=("2009-01-01", "2009-01-02"), show_progress=True)# Selecting a data point to downloadselected = ers_data.isel(time=0) # index 0 selected# Downloading the datadownloaded_data = storage_client.download(selected, extract=True)print(f"Downloaded granule: {downloaded_data.name} to {downloaded_data}")print("Contents: ")for content in downloaded_data.iterdir(): print(f" - {content.relative_to(downloaded_data)}")
Many ASF products include a quicklook image. The Tilebox storage client includes support for displaying these quicklook images directly when running in an interactive environment such as a Jupyter notebook.
Python
# Loading metadataers_dataset = client.dataset("open_data.asf.ers_sar")collection = ers_dataset.collection("ERS-2")ers_data = collection.query(temporal_extent=("2009-01-01", "2009-01-02"), show_progress=True)# Selecting a data point to downloadselected = ers_data.isel(time=0) # index 0 selected# Displaying a quicklook imagestorage_client.quicklook(selected)
Umbra satellites provide high resolution Synthetic Aperture Radar (SAR) imagery from space. Check out the Umbra datasets that are available in Tilebox.
No account is needed to access Umbra data. All data is under a Creative Commons License (CC BY 4.0), allowing you to use it freely.The following code snippet demonstrates how to query and download Umbra data using the Tilebox Python SDK.
Python
from pathlib import Pathfrom tilebox.datasets import Clientfrom tilebox.storage import UmbraStorageClient# Creating clientsclient = Client()datasets = client.datasets()storage_client = UmbraStorageClient(cache_directory=Path("./data"))# Choosing the dataset and collectionumbra_dataset = datasets.open_data.umbra.sarcollections = umbra_dataset.collections()collection = collections["SAR"]# Loading metadataumbra_data = collection.query(temporal_extent=("2024-01-05", "2024-01-06"), show_progress=True)# Selecting a data point to downloadselected = umbra_data.isel(time=0) # index 0 selected# Downloading the datadownloaded_data = storage_client.download(selected)print(f"Downloaded granule: {downloaded_data.name} to {downloaded_data}")print("Contents: ")for content in downloaded_data.iterdir(): print(f" - {content.relative_to(downloaded_data)}")
For cases where only a subset of the available file objects for a given Umbra data point is necessary, you can limit your download to just that subset. First, list available objects using list_objects, filter the list, and then use download_objects.The below example shows how to download only the metadata file for a given data point.
Python
collection = datasets.open_data.umbra.sar.collections()["SAR"]umbra_data = collection.query(temporal_extent=("2024-01-05", "2024-01-06"), show_progress=True)# Selecting a data point to downloadselected = umbra_data.isel(time=0) # index 0 selectedobjects = storage_client.list_objects(selected)print(f"Data point {selected.granule_name.item()} consists of {len(objects)} individual objects.")# only select specific objects to downloadobjects = [obj for obj in objects if "METADATA" in obj] # remove all other objectsprint(f"Downloading {len(objects)} object.")print(objects)# Finally, download the selected datadownloaded_data = storage_client.download_objects(selected, objects)
Output
Data point 2024-01-05-01-53-37_UMBRA-07 consists of 6 individual objects.Downloading 1 object.['2024-01-05-01-53-37_UMBRA-07_METADATA.json']
