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