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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.