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

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.68.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.68.0
File Size Uploaded Provenance Actions
tilebox_datasets-0.68.0.tar.gz 103.1 kB With provenance Details for tilebox_datasets-0.68.0.tar.gz

Built distribution (wheel)

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

Total release size: 237.4 kB

Release files / tilebox_datasets-0.68.0.tar.gz

Download URL tilebox_datasets-0.68.0.tar.gz
Size 103.1 kB
Tags Source
SHA-256 checksum
How to use checksums
499d850ba199d768c0dcb5236411fb436867e21400e2a1e032a84a182e84bb67
BLAKE2b-256 checksum
How to use checksums
0fb77fc3edccaa843cf4cb92ba2de28da2b7255c350a97d91214fc6fb26f8489
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 Oct 30, 2026.

Transparency log

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

Download URL tilebox_datasets-0.68.0-py3-none-any.whl
Size 134.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
385e91ec997dce546f0cb695c1821bcbd5aa7b057afc61f1c93774d4eaf906ed
BLAKE2b-256 checksum
How to use checksums
ba0d8f267fe22d9b6bba1168343969293c4db95db1afc85ab64aee6039348e69
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 Oct 30, 2026.

Transparency log

Security for tilebox-datasets 0.68.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.68.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 Oct 30, 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.68.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