Skip to main content

Tilebox Logo

Documentation | Console | Example Gallery

Tilebox Datasets

Access satellite data using the Tilebox datasets python client powered by gRPC and Protobuf.

Quickstart

Install using pip:

pip install tilebox-datasets

Instantiate a client:

from tilebox.datasets import Client

# create your API key at https://console.tilebox.com
client = Client(token="YOUR_TILEBOX_API_KEY")

Explore datasets and collections:

datasets = client.datasets()
print(datasets)

sentinel2_msi = client.dataset("open_data.copernicus.sentinel2_msi")
collections = sentinel2_msi.collections()
print(collections)

Query data:

s2a_l1c = sentinel2_msi.collection("S2A_S2MSI1C")
results = s2a_l1c.query(temporal_extent=("2025-03-01", "2025-06-01"), show_progress=True)
print(f"Found {results.sizes['time']} datapoints")  # Found 220542 datapoints

Spatio-temporal queries:

from shapely.geometry import shape

area_of_interest = shape(
    {
        "type": "Polygon",  # coords in lon, lat
        "coordinates": [[[-5, 50], [-5, 56], [-11, 56], [-11, 50], [-5, 50]]],
    }
)
s2a_l1c = sentinel2_msi.collection("S2A_S2MSI1C")
results = s2a_l1c.query(
    temporal_extent=("2025-03-01", "2025-06-01"), spatial_extent=area_of_interest, show_progress=True
)
print(f"Found {results.sizes['time']} datapoints")  # Found 979 datapoints

Lazy metadata fields

Queries and find() return LazyMessage wrappers for fields of type Assets, Links, Storage, and Authentication, including elements of repeated fields. Other fields keep their existing xarray representation. Wrappers display counts such as Assets(23), Links(8), or Storage(1 scheme). Displaying a wrapper decodes and caches its message; xarray's default display formats only a sample of rows, not the entire result.

For a result with an assets field:

from tilebox.datasets.assets import AssetCollection

row = results.isel(time=0)
message = row.assets.item().get()  # Decode to the generated Assets message.
assets = AssetCollection.from_datapoint(row)  # Unwraps assets and their storage/authentication context.

get() caches the mutable message in that wrapper and releases its encoded bytes. Subsequent calls return the same message. Different datapoints do not share decoded messages, but an xarray shallow copy shares its wrappers with the original. Missing fields remain missing; a present empty message still has a wrapper. Malformed nested messages raise when decoded, rather than during the query. Display catches ValueError from decoding or formatting and falls back to Assets(…) (or the corresponding type name); other errors propagate. Explicit get() still raises decoding errors. Custom wrappers can supply repr_formatter= with a function that takes the decoded message and returns a string. Without a formatter, display uses the placeholder without decoding. Equality comparisons, including xarray merges, decode compatible messages and use protobuf equality, including its treatment of NaN values as unequal between independently decoded messages.

Ingestion accepts wrappers alongside ordinary generated messages in records, columns, DataFrames, and xarray Datasets. Untouched wrappers forward their protobuf bytes without decoding; decoded wrappers serialize the current message, including any edits. Lazy payload validation is deferred to decoding or the ingestion server. Use get() first if you need to check that a payload can be decoded before sending it.

Enum fields

Define a scalar enum with an ordered list of public strings:

from datetime import UTC, datetime

from tilebox.datasets import field
from tilebox.datasets.data.datasets import DatasetKind

dataset = client.create_or_update_dataset(
    DatasetKind.TEMPORAL,
    "scenes",
    fields=[
        {"name": "processing_level", "type": "enum", "enum_values": ["L1", "L2-SP", "雪"], "queryable": True},
    ],
)
collection = dataset.get_or_create_collection("example")
collection.ingest(
    [
        {"time": datetime(2026, 10, 28, 12, tzinfo=UTC), "processing_level": "L2-SP"},
        {"time": datetime(2026, 10, 28, 13, tzinfo=UTC)},
    ]
)

results = collection.query(
    temporal_extent=("2026-10-28", "2026-10-29"),
    filter=field("processing_level") == "L2-SP",
)
assert results.processing_level.to_numpy().tolist() == ["L2-SP"]

Ingestion accepts public strings in records, columns, pandas DataFrames, and xarray Datasets. Query results contain public strings in object arrays. Missing values remain missing; use xarray's isnull() to identify them. You do not need a Python enum class to create or read a dataset. Numbers and generated protobuf symbols are not accepted as substitutes for public values.

Scalar enum filters support == and !=. Combine equality expressions with | to match several values. The server validates values case-sensitively. Comparisons exclude missing values, including !=; include them explicitly with (field("processing_level") != "L1") | field("processing_level").is_null().

Vocabularies contain 1–100 unique, nonempty strings. Empty datasets allow replacing, removing, renaming, or reordering values. Once a dataset contains data, updates may only append values. Supply the full field schema when updating a dataset, and re-fetch the dataset after another client updates its vocabulary. The asynchronous client provides the same enum behavior.

Repeated enums

Add "repeated": True to define lists of enum values, including queryable tags:

fields = [
    {
        "name": "use_cases",
        "type": "enum",
        "enum_values": ["agriculture", "defense", "wind-power"],
        "repeated": True,
        "queryable": True,
    },
]
dataset = client.create_or_update_dataset(DatasetKind.TEMPORAL, "tagged_scenes", fields)
collection = dataset.get_or_create_collection("example")
collection.ingest(
    [
        {"time": datetime(2026, 10, 28, 12, tzinfo=UTC), "use_cases": ["defense", "agriculture", "defense"]},
    ]
)
results = collection.query(
    temporal_extent=("2026-10-28", "2026-10-29"),
    filter=field("use_cases").contains("defense"),
)

# Alternative membership filters:
all_tags = field("use_cases").contains_all(["defense", "agriculture"])
any_tag = field("use_cases").contains_any(["defense", "wind-power"])
without_defense = ~field("use_cases").contains("defense")

The backend removes duplicates during ingestion, preserving first-occurrence order. The example stores ["defense", "agriculture"]. Ingest lists of public strings through records, columns, or pandas; xarray results contain one list[str] per row in an object column, use_cases(time), without an extra array dimension. Empty values are [], including when every returned value is empty. Lists preserve the returned order and can be ingested again without changing enum ordering. Other repeated fields retain their existing padded array layout.

Repeated enums use membership filters, not ==, !=, or null checks. Combine predicates with &, |, and ~. Membership treats omitted and empty lists as the empty set and never returns null. Consequently, without_defense includes untagged rows. contains_all([]) matches every row; contains_any([]) matches none. Each predicate accepts up to 100 nonempty public strings, counting duplicates toward that limit. The server checks vocabulary membership and whether the field is queryable.

Documentation

Check out the Tilebox Datasets documentation for more information.

License

Distributed under the MIT License (The MIT License).

Metadata

Release files for tilebox-datasets 0.69.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tilebox-datasets 0.69.0
File Size Uploaded Provenance Actions
tilebox_datasets-0.69.0.tar.gz 106.3 kB With provenance Details for tilebox_datasets-0.69.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tilebox-datasets 0.69.0
File Interpreter ABI Platform Actions
tilebox_datasets-0.69.0-py3-none-any.whl Python 3 none any Details for tilebox_datasets-0.69.0-py3-none-any.whl

Total release size: 244.4 kB

Release files / tilebox_datasets-0.69.0.tar.gz

Download URL tilebox_datasets-0.69.0.tar.gz
Size 106.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f0bc3e8c14cbfa683e5f003897c5f262b4eefba6f4f6ffa15b7f688accd6760a
BLAKE2b-256 checksum
How to use checksums
2a3533f447302e3c73df00b68b97205919c84eb35e0130d25584b901346cd825
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 9, 2026.

Transparency log

Release files / tilebox_datasets-0.69.0-py3-none-any.whl

Download URL tilebox_datasets-0.69.0-py3-none-any.whl
Size 138.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1f5add6792a21934c71fece609f93336af5b36abc05f8740fa2f89551c6e1e29
BLAKE2b-256 checksum
How to use checksums
12469f315f00c8ff496b010136349101021476ec9edebc0771f18e2810734b75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 9, 2026.

Transparency log

Security for tilebox-datasets 0.69.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tilebox_datasets-0.69.0.tar.gz

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 Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.69.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page