Skip to content

quickstart.mdx

Latest commit

 

History

History
137 lines (106 loc) · 5.52 KB

quickstart.mdx

File metadata and controls

137 lines (106 loc) · 5.52 KB
Raw
title Quickstart
description Start here as a developer to create an API key, query Earth data, and run a small workflow.
icon play

This quickstart is for developers using Tilebox directly from a terminal, notebook, or SDK. If you want an AI coding agent to work with Tilebox for you, start with Onboard your agent.

You will create an API key, query open Sentinel-2 metadata, and run a small workflow task using the Tilebox Python SDK.

Start in a Notebook

Explore the provided Sample Notebooks to begin your journey with Tilebox. These notebooks offer a step-by-step guide to using the API and showcase many features supported by Tilebox Python clients. You can also use these notebooks as a foundation for your own projects.

Start on Your Device

If you prefer to work locally, follow these steps to get started.

Create an API key by logging into the [Tilebox Console](https://console.tilebox.com), navigating to [Settings -> API Keys](https://console.tilebox.com/settings/api-keys), and clicking the "Create API Key" button. 
Then, add it to your environment

```bash
export TILEBOX_API_KEY=<your-api-key>
```
Tilebox can be used from the browser, terminal, or via our SDKs running locally or in interactive notebook environments. This quickstart guides you through setting up the Tilebox **Python SDK locally**. Alternatively, you can also check out any of the following ways of using Tilebox. 
<CardGroup cols={2}>
  <Card title="Console" icon="display" href="/console" horizontal/>

  <Card title="Command line" icon="terminal" href="/agents-and-ai-tools/tilebox-cli" horizontal/>

  <Card title="Go SDK" icon="golang" href="/sdks/go" horizontal/> 

  <Card title="Agents" icon="robot" href="/onboard-your-agent" horizontal/>

  <Card title="Notebooks" icon="book-open" href="/sdks/python/sample-notebooks" horizontal/>
</CardGroup>

To install the python SDK locally, run the following command.

```bash
uv add tilebox
```
Use the datasets client to query data from a dataset. 
```python Python
from tilebox.datasets import Client
from shapely import Polygon

# define a search area (optional)
new_york_city = Polygon(
    [(-74.40, 41.02), (-74.48, 40.27), (-73.37, 40.34),
    (-73.39, 41.05), (-74.40, 41.02)]
)

client = Client(token="YOUR_TILEBOX_API_KEY")

# select a dataset
dataset = client.dataset("open_data.copernicus.sentinel2_msi")
# and query data
scenes_new_york_january_2026 = dataset.query(
  collections=["S2A_S2MSI2A", "S2B_S2MSI2A", "S2C_S2MSI2A"],
  temporal_extent=("2026-01-01", "2026-02-01"),
  spatial_extent=new_york_city
)
print(scenes_new_york_january_2026.granule_name)
```
Use the workflows client to create a task and submit it as a job. 
```python Python
from tilebox.workflows import Client, Runner, Task
from tilebox.workflows.observability.logging import configure_console_logging

configure_console_logging()

# Replace with your actual token
client = Client(token="YOUR_TILEBOX_API_KEY")

class HelloWorldTask(Task):
    greeting: str = "Hello"
    name: str = "World"

    def execute(self, context):
        context.logger.info(f"{self.greeting} {self.name}, from the main task!")
        context.submit_subtask(HelloSubtask(name=self.name))

class HelloSubtask(Task):
    name: str

    def execute(self, context):
        context.logger.info(f"Hello from the subtask!", name=self.name)

# Initiate the job
jobs = client.jobs()
job = jobs.submit("parameterized-hello-world", HelloWorldTask(greeting="Greetings", name="Universe"))

# Run the tasks
runner = Runner(tasks=[HelloWorldTask, HelloSubtask])
runner.connect_to(client).run_all()

print("Explore the job you just submitted in the Tilebox Console.")
print("Check out tasks, log messages, and execution timining:")
print(f"https://console.tilebox.com/workflows/jobs/{job.id}")
```
Review the following guides to learn more about the modules that make up Tilebox: 
<Columns cols={1}>
  <Card title="Build a spatio-temporal catalog" icon="database" href="/guides/datasets/build-spatiotemporal-catalog" horizontal>
    Learn how to create a custom dataset catalog with the Python SDK.
  </Card>
  <Card title="Ingest into a spatio-temporal catalog" icon="up-from-bracket" href="/guides/datasets/ingest-into-spatiotemporal-catalog" horizontal>
    Learn how to ingest GeoParquet metadata into an existing spatio-temporal catalog.
  </Card>
  <Card title="Debug a failed workflow run" icon="bug" href="/guides/workflows/debug-failed-run" horizontal>
    Inspect task state, logs and traces when a workflow job fails.
  </Card>
  <Card title="Build and deploy a workflow project" icon="rocket" href="/guides/workflows/build-and-deploy-workflow" horizontal>
    Package a Python workflow project, publish a release, and deploy it to a cluster.
  </Card>
  <Card title="Agentic workflow iteration" icon="robot" href="/guides/workflows/agentic-workflow-iteration" horizontal>
    Use a coding agent with the Tilebox CLI to build, deploy, run, and debug workflow releases.
  </Card>
</Columns>