Metadata-Version: 2.4
Name: tilebox-datasets
Version: 0.39.0
Summary: Access Tilebox datasets from Python
Project-URL: Homepage, https://tilebox.com
Project-URL: Documentation, https://docs.tilebox.com/datasets/introduction
Author-email: "Tilebox, Inc." <support@tilebox.com>
License: MIT License
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: cftime>=1.6.4
Requires-Dist: loguru>=0.7
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.1
Requires-Dist: promise>=2.3
Requires-Dist: shapely>=2
Requires-Dist: tilebox-grpc>=0.28.0
Requires-Dist: tqdm>=4.65
Requires-Dist: xarray>=2023.11
Description-Content-Type: text/markdown

<h1 align="center">
  <img src="https://storage.googleapis.com/tbx-web-assets-2bad228/banners/tilebox-banner.svg" alt="Tilebox Logo">
  <br>
</h1>

<div align="center">
  <a href="https://pypi.org/project/tilebox-datasets/">
    <img src="https://img.shields.io/pypi/v/tilebox-datasets.svg?style=flat-square&label=version&color=f43f5e" alt="PyPi Latest Release badge"/>
  </a>
  <a href="https://pypi.org/project/tilebox-datasets/">
    <img src="https://img.shields.io/pypi/pyversions/tilebox-datasets.svg?style=flat-square&logo=python&color=f43f5e&logoColor=f43f5e" alt="Required Python Version badge"/>
  </a>
  <a href="https://github.com/tilebox/tilebox-python/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/tilebox/tilebox-python.svg?style=flat-square&color=f43f5e" alt="MIT License"/>
  </a>
  <a href="https://github.com/tilebox/tilebox-python/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/tilebox/tilebox-python/main.yml?style=flat-square&color=f43f5e" alt="Build Status"/>
  </a>
  <a href="https://tilebox.com/discord">
    <img src="https://img.shields.io/badge/Discord-%235865F2.svg?style=flat-square&logo=discord&logoColor=white" alt="Join us on Discord"/>
  </a>
</div>

<p align="center">
  <a href="https://docs.tilebox.com/datasets/introduction"><b>Documentation</b></a>
  |
  <a href="https://console.tilebox.com/"><b>Console</b></a>
  |
  <a href="https://examples.tilebox.com/"><b>Example Gallery</b></a>
</p>

# Tilebox Datasets

Access satellite data using the [Tilebox](https://tilebox.com) datasets python client powered by gRPC and Protobuf.

## Quickstart

Install using `pip`:

```bash
pip install tilebox-datasets
```

Instantiate a client:

```python
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:

```python
datasets = client.datasets()
print(datasets)

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

Query data:

```python
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:

```python
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
```

## Documentation

Check out the [Tilebox Datasets documentation](https://docs.tilebox.com/datasets/introduction) for more information.

## License

Distributed under the MIT License (`The MIT License`).
