Overview
Once you have access to a dataset (either your own or shared with you), you can query it programmatically using the Rasteret library. Rasteret provides efficient access to Cloud-Optimized GeoTIFFs (COGs) with minimal HTTP requests.
Installation
Install the Rasteret library using pip:
Authentication
Rasteret uses your Terrafloww API token for authentication. You can set this in your environment:
export TERRAFLOWW_API_TOKEN="your_api_token_here"
import rasteret
rasteret.configure(api_token="your_api_token_here")
Basic Usage
Query a Dataset
Use rasteret.get_xarray() to fetch data for your area of interest:
import rasteret
from shapely.geometry import box
# Define your area of interest
bbox = box(77.55, 13.01, 77.58, 13.08)
# Query the dataset
ds = rasteret.get_xarray(
geometries=[bbox],
bands=["B04", "B08"],
date_range=("2025-01-01", "2025-01-31"),
dataset="org-slug/dataset-slug",
cloud_cover_lt=20,
)
Parameters
| Parameter | Type | Description |
|---|
geometries | list | List of Shapely geometries defining your AOI |
bands | list | Band names to retrieve (e.g., ["B04", "B08"]) |
date_range | tuple | Start and end dates as strings |
dataset | string | Dataset identifier (org_slug/dataset_slug) |
cloud_cover_lt | int | Maximum cloud cover percentage |
Working with Results
The result is an xarray Dataset that you can process and analyze:
# Calculate NDVI
ndvi = (ds.B08 - ds.B04) / (ds.B08 + ds.B04)
# Plot the result
ndvi.isel(time=0).plot()
Save Results
Export your analysis results to GeoTIFF:
from rasteret.core.utils import save_per_geometry
output_files = save_per_geometry(
ndvi_ds,
output_dir="./results",
file_prefix="ndvi",
data_var="NDVI"
)
Multiple Geometries
Process multiple areas of interest in a single query:
from shapely.geometry import Polygon
aoi1 = Polygon([
(77.55, 13.01), (77.58, 13.01),
(77.58, 13.08), (77.55, 13.08),
(77.55, 13.01)
])
aoi2 = Polygon([
(77.56, 13.02), (77.59, 13.02),
(77.59, 13.09), (77.56, 13.09),
(77.56, 13.02)
])
ds = rasteret.get_xarray(
geometries=[aoi1, aoi2],
bands=["B04", "B08"],
date_range=("2025-01-01", "2025-01-31"),
dataset="org-slug/dataset-slug",
)
Rasteret caches COG headers locally, making subsequent queries much faster. On a 4-core machine, expect around 0.1 seconds per tile after the initial cache is built.
Optimize Your Queries
- Use specific date ranges - Avoid overly broad date ranges
- Request only needed bands - Don’t fetch bands you won’t use
- Apply cloud filtering - Reduce processing by filtering cloudy scenes
Error Handling
try:
ds = rasteret.get_xarray(
geometries=[bbox],
bands=["B04"],
dataset="org-slug/dataset-slug",
)
except rasteret.AuthenticationError:
print("Invalid or expired API token")
except rasteret.DatasetNotFoundError:
print("Dataset not found or no access")
Next Steps
