Documentation | Console | Example Gallery
Tilebox Storage
Download satellite payload data for your Tilebox datasets.
Quickstart
Install using pip:
pip install tilebox-storage tilebox-datasets
Fetch a datapoint to download the payload data for:
from tilebox.datasets import Client
# Creating clients
client = Client(token="YOUR_TILEBOX_API_KEY")
datasets = client.datasets()
# Choosing the dataset and collection
s2_dataset = datasets.open_data.copernicus.sentinel2_msi
collections = s2_dataset.collections()
collection = collections["S2A_S2MSI2A"]
# Loading metadata
s2_data = collection.load(("2024-08-01", "2024-08-02"), show_progress=True)
# Let's download the first granule
s2_granule = s2_data.isel(time=0)
Then download the payload data using a storage client:
from pathlib import Path
from tilebox.storage import CopernicusStorageClient
# Check out the Copernicus Dataspace S3 documentation at
# https://documentation.dataspace.copernicus.eu/APIs/S3.html
# to learn how to get your access key and secret access key
storage_client = CopernicusStorageClient(
access_key="YOUR_ACCESS_KEY", secret_access_key="YOUR_SECRET_ACCESS_KEY", cache_directory=Path("./data")
)
downloaded_data = storage_client.download(s2_granule)
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)}")
Planetary Computer assets
The asynchronous asset client reads Planetary Computer assets through the same API as public assets:
from tilebox.datasets.assets import AssetCollection
from tilebox.storage.aio import Client
assets = AssetCollection.from_datapoint(datapoint)
storage = Client()
resolved = storage.resolve(assets["red"]) # Local metadata validation only; no network requests.
geotiff = await storage.open_geotiff(assets["red"])
metadata = await storage.read_bytes(assets["mtl.json"], max_bytes=1_000_000)
await storage.download(assets["red"], "data/red.tif")
The asset must declare the Planetary Computer signedUrl flow for
https://planetarycomputer.microsoft.com/api/sas/v1/sign (GET, an href query parameter,
and an href response field). HTTPS locations also need Microsoft Azure storage metadata.
The client checks the account and container against any supplied storage metadata.
Planetary Computer is the only built-in signing service; unknown APIs are rejected.
The first read fetches a container-scoped SAS token automatically. Assets with the same account,
container, and credential binding share an object store. Descriptions and unused flows do not
split the cache. Obstore caches credentials and
refreshes them on demand near expiry. resolved.href stays unsigned; callers do not need to manage
tokens or close a session. Token requests use niquests and bounded async Tenacity retries.
Use async obstore operations if accessing resolved.store directly. Download NetCDF and HDF assets
with download() before opening them locally; open_geotiff() only supports GeoTIFF assets.
Asset locations and credentials
The asset client supports local paths and file, s3, gs/gcs, az/azure, abfs/abfss,
and HTTP(S) locations. Azure forms are:
az://account/container/key(alsoazure)abfs://container@account.dfs.core.windows.net/key(alsoabfss)abfs://container/keywith the account in storage metadata (alsoabfss)https://account.blob.core.windows.net/container/keywith Azure storage metadata
These Azure forms share stores and signing credentials. A resolved path can be an object key
or dataset prefix; it is never a full URL. This permits multi-key readers such as a future
open_zarr() without putting the prefix into the store cache key. No Zarr reader is included yet.
Locations without authentication metadata use unsigned cloud requests, even when credentials
are present in the environment. Obstore still reads environment configuration when constructing
stores; skip_signature disables request authentication, not environment configuration parsing.
Declared but unsupported authentication fails resolution rather than falling back to anonymous
access. The client tries supported alternate locations during resolution, not after read failures.
S3 authentication requires an explicitly supplied provider, keyed by the location's authentication scheme name. For example, this opts into boto3's credential discovery on the first read:
import asyncio
from obstore.auth.boto3 import Boto3CredentialProvider
from tilebox.storage.aio import Client
async def aws_credentials():
def fetch():
return Boto3CredentialProvider()()
return await asyncio.to_thread(fetch)
storage = Client(s3_credentials={"aws": aws_credentials})
HTTP query parameters remain part of the request URL and store identity, rather than being
encoded into the object key. They cannot be discarded: a parameter such as versionId may
select different data. Prefer normalized native locations in datapoints for cloud-specific
authentication; the client does not infer S3 or GCS bucket layouts from arbitrary HTTPS URLs.
Resolution uses an internal registry of supported backends and authentication flows; there is no public plugin registration API. Unsupported combinations are filtered before ambiguity is checked. Two supported combinations or signing flows require the caller to disambiguate the metadata.
License
Distributed under the MIT License (The MIT License).
2 maintainers
Metadata
2 maintainers
Release files for tilebox-storage 0.66.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tilebox_storage-0.66.0.tar.gz | 24.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tilebox_storage-0.66.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 53.6 kB
Release files / tilebox_storage-0.66.0.tar.gz
| Download URL | tilebox_storage-0.66.0.tar.gz |
|---|---|
| Size | 24.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1d7dba89134518fd1bc01c8c6df2cf66fa123a113feaca3488542bf6f572668b
|
|
BLAKE2b-256 checksum How to use checksums |
a2f33cb5af1e336681934dd5e25884be678438512f5a830a9e029250acae8e10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency logRelease files / tilebox_storage-0.66.0-py3-none-any.whl
| Download URL | tilebox_storage-0.66.0-py3-none-any.whl |
|---|---|
| Size | 29.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd8efe1c48ba848be70ff6d71ff51124fe934a879b1a19930cae2a5faa3e03ca
|
|
BLAKE2b-256 checksum How to use checksums |
fa921a9259dac39e8d2b16c88b33531755be786d545bf4385d28382b57b49cd9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.
Transparency log
