Skip to main content
Use this guide when you know the area and time range you care about and want to find matching satellite products before downloading any files. Tilebox Datasets stores searchable metadata for open data catalogs. Querying metadata first lets you narrow a large catalog to the scenes that match your workflow, notebook, or agent task.

​
Prerequisites

uv add tilebox shapely

​
Define the search area

Create a polygon for the area you want to inspect. This example uses a bounding box around Colorado.
Python
from shapely import Polygon

area = Polygon(
    [
        (-109.05, 37.0),
        (-102.05, 37.0),
        (-102.05, 41.0),
        (-109.05, 41.0),
        (-109.05, 37.0),
    ]
)

​
Query Sentinel-2 metadata

Select the Sentinel-2 MSI open data catalog and query a collection by time and location.
Python
from tilebox.datasets import Client

client = Client()
sentinel2 = client.dataset("open_data.copernicus.sentinel2_msi")
collection = sentinel2.collection("S2A_S2MSI2A")

scenes = collection.query(
    temporal_extent=("2025-10-01", "2025-11-01"),
    spatial_extent=area,
    show_progress=True,
)

print(scenes[["granule_name", "processing_level", "product_type"]])
The result is an xarray.Dataset containing scene metadata. Use it to inspect candidate scenes, filter by metadata fields, or pass selected datapoints to a storage client.

​
Download matching products

Metadata queries do not download product files. Use a storage client when you want to read or download the files referenced by a datapoint.
Python
from pathlib import Path
from tilebox.storage import CopernicusStorageClient

storage = CopernicusStorageClient(
    cache_directory=Path("./data"),
    s3_access_key_id="YOUR_COPERNICUS_ACCESS_KEY",
    s3_secret_access_key="YOUR_COPERNICUS_SECRET_KEY",
)

first_scene = scenes.isel(time=0)
path = storage.download(first_scene)
print(path)

​
Next steps

Access Sentinel-2 data

Follow a longer Sentinel-2 example with output inspection.

Storage clients

Configure provider-specific clients for product access.