Access USGS Landsat data

Use this guide when you already have a Landsat datapoint from a Tilebox metadata query and want to access the product files behind it. The example uses Landsat 8 Collection 2 Level-2 surface reflectance data. Tilebox indexes Landsat metadata as datasets. Product files remain in the USGS public cloud archive, so file access uses the USGSLandsatStorageClient and your AWS requester-pays setup.

Prerequisites

You have a Tilebox API key.
You have installed the Python SDK.
You have AWS credentials configured in your environment.
Your AWS account can access requester-pays S3 buckets.

uv add tilebox shapely

USGS Landsat data is stored in a requester-pays S3 bucket. AWS charges for requests and data transfer according to your AWS account settings.

Select a Landsat 8 datapoint

Start with a small metadata query and select one datapoint to access. For a deeper guide to open data discovery and metadata filtering, see Query open data metadata.

Python

from shapely import Polygon
from tilebox.datasets import Client

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

client = Client()
collection = client.dataset("open_data.usgs.landsat8_oli_tirs").collection("L2_SR")

scenes = collection.query(
    temporal_extent=("2024-08-01", "2024-08-15"),
    spatial_extent=area,
    show_progress=True,
)

selected = scenes.where(scenes.cloud_cover < 10, drop=True).isel(time=0)
print(selected.granule_name.item())

Create the Landsat storage client

Create a USGSLandsatStorageClient. The client uses AWS credentials from your environment, such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN when needed.

Python

from tilebox.storage import USGSLandsatStorageClient

storage = USGSLandsatStorageClient()

Download the complete product

Use download when you need the complete Landsat product directory. The storage client resolves the product location from the Tilebox datapoint metadata and downloads the matching files into the local cache.

Python

product_path = storage.download(selected)

print(f"Downloaded {product_path.name} to {product_path}")
print("Contents:")
for path in product_path.iterdir():
    print(f"- {path.relative_to(product_path)}")

Output

Downloaded LC08_L2SP_033033_20240808_20240814_02_T1 to ~/.cache/tilebox/collection02/level-2/standard/oli-tirs/2024/033/033/LC08_L2SP_033033_20240808_20240814_02_T1
Contents:
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B1.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B2.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B3.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B4.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B5.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B6.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_SR_B7.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_QA_PIXEL.TIF
- LC08_L2SP_033033_20240808_20240814_02_T1_MTL.json
- LC08_L2SP_033033_20240808_20240814_02_T1_thumb_small.jpeg

Download selected product files

Landsat products contain surface reflectance bands, quality masks, thermal bands, metadata, and preview images. Use list_objects and download_objects when you only need specific files.

Python

objects = storage.list_objects(selected)

rgb_bands = ["B4", "B3", "B2"]
rgb_objects = [
    obj for obj in objects
    if any(obj.endswith(f"_{band}.TIF") for band in rgb_bands)
]

for obj in rgb_objects:
    print(obj)

downloaded_files = storage.download_objects(selected, rgb_objects)
print(downloaded_files)

Use this pattern when a workflow only needs a few bands, masks, or metadata files. It reduces transfer time and local storage compared with downloading the full product.

Preview the product

Many Landsat products include a thumbnail image. In a notebook, use quicklook to display the product preview without downloading the full product first.

Python

storage.quicklook(selected)

USGS Landsat quicklook image — Landsat quicklook image © USGS

Tilebox Guides

Datasets

Workflows

Operations

Access USGS Landsat data

Prerequisites

Select a Landsat 8 datapoint

Create the Landsat storage client

Download the complete product

Download selected product files

Preview the product

Next steps

Query open data metadata

Storage clients

​Prerequisites

​Select a Landsat 8 datapoint

​Create the Landsat storage client

​Download the complete product

​Download selected product files

​Preview the product

​Next steps

Query open data metadata

Storage clients

Prerequisites

Select a Landsat 8 datapoint

Create the Landsat storage client

Download the complete product

Download selected product files

Preview the product

Next steps