---
title: "Tilebox Datasets"
description: "A high-performance platform for structuring and querying satellite metadata, with curated open data catalogs and support for custom dataset collections."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tilebox Datasets

import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@docs/components/ui/collapsible";

import { CodeGroup } from "@docs/components/ui/code-group";

import { CardGrid } from "@docs/components/ui/card-grid";
import { LinkCard } from "@docs/components/ui/link-card";

Tilebox Datasets ingests and structures metadata for efficient querying, reducing data transfer and storage costs.

Create your own [Custom Datasets](/docs/datasets/concepts/datasets) and easily set up a private, custom, strongly typed and highly available catalogue, or 
explore any of the wide range of [available public open data datasets](/docs/datasets/open-data) available on Tilebox.

Learn more about datasets by exploring the following sections:

    Learn what dataset types are available on Tilebox and how to create, list and access them.

    Learn what collections are and how to access them.

    Find out how to access data from a collection for specific time intervals.

    Learn how to ingest data into a collection.

    Connect dataset metadata to files in object storage.

:::note
  For a quick reference to API methods or specific parameter meanings, [check out the complete datasets API Reference](/docs/api-reference/python/tilebox.datasets/Client).
:::

## Terminology

Get familiar with some key terms when working with time series datasets.

<div>

  <CollapsibleTrigger>Data points</CollapsibleTrigger>
  <CollapsibleContent>

    Data points are the individual entities that form a dataset. Each data point has a set of required [fields](/docs/datasets/types/timeseries) determined by the dataset type, and can have custom user-defined fields.
  </CollapsibleContent>

  <CollapsibleTrigger>Datasets</CollapsibleTrigger>
  <CollapsibleContent>

    Datasets act as containers for data points. All data points in a dataset share the same type and fields. Tilebox supports different types of datasets, currently those are [Timeseries](/docs/datasets/types/timeseries) and [Spatio-temporal](/docs/datasets/types/spatiotemporal) datasets.
  </CollapsibleContent>

  <CollapsibleTrigger>Collections</CollapsibleTrigger>
  <CollapsibleContent>

    Collections group data points within a dataset. They help represent logical groupings of data points that are often queried together.
  </CollapsibleContent>

</div>

## Creating a datasets client

Prerequisites

- You have installed the [python](/docs/sdks/python/install) `tilebox-datasets` package or [go](/docs/sdks/go/install) library.
- You have [created](/docs/authentication) a Tilebox API key.

After meeting these prerequisites, you can create a client instance to interact with Tilebox Datasets.

```python title="Python"
from tilebox.datasets import Client

client = Client(token="YOUR_TILEBOX_API_KEY")
```

```go title="Go"
import (
	"github.com/tilebox/tilebox-go/datasets/v1"
)

client := datasets.NewClient(
	datasets.WithAPIKey("YOUR_TILEBOX_API_KEY"),
)
```

You can also set the `TILEBOX_API_KEY` environment variable to your API key. You can then instantiate the client without passing the `token` argument. Python will automatically use this environment variable for authentication.

```python title="Python"
from tilebox.datasets import Client

# requires a TILEBOX_API_KEY environment variable
client = Client()
```

```go title="Go"
import (
	"github.com/tilebox/tilebox-go/datasets/v1"
)

// requires a TILEBOX_API_KEY environment variable
client := datasets.NewClient()
```

:::tip
  Tilebox datasets provide a standard synchronous API by default but also offers an [asynchronous client](/docs/sdks/python/async) if needed.
:::

### Exploring datasets

After creating a client instance, you can start exploring available datasets. A straightforward way to do this in an interactive environment is to [list all datasets](/docs/api-reference/python/tilebox.datasets/Client.datasets) and use the autocomplete feature in your Jupyter notebook.

```python title="Python"
datasets = client.datasets()
datasets. # trigger autocomplete here to view available datasets
```

```go title="Go"
package main

import (
	"context"
	"github.com/tilebox/tilebox-go/datasets/v1"
	"log"
)

func main() {
	client := datasets.NewClient()

	ctx := context.Background()
	allDatasets, err := client.Datasets.List(ctx)
	if err != nil {
		log.Fatalf("Failed to list datasets: %v", err)
	}

	for _, dataset := range allDatasets {
		log.Printf("Dataset: %s", dataset.Name)
	}
}
```

:::tip
  The Console also provides an [overview](https://console.tilebox.com/datasets/explorer) of all available datasets.
:::

### Errors you might encounter

#### AuthenticationError

`AuthenticationError` occurs when the client fails to authenticate with the Tilebox API. This may happen if the provided API key is invalid or expired. A client instantiated with an invalid API key won't raise an error immediately, but an error will occur when making a request to the API.

```python title="Python"
client = Client(token="invalid-key") # runs without error
datasets = client.datasets() # raises AuthenticationError
```

```go title="Go"
package main

import (
	"context"
	"github.com/tilebox/tilebox-go/datasets/v1"
	"log"
)

func main() {
	// runs without error
	client := datasets.NewClient(datasets.WithAPIKey("invalid-key"))

	// returns an error
	_, err := client.Datasets.List(context.Background())
	if err != nil {
		log.Fatalf("Failed to list datasets: %v", err)
	}
}
```

## Next steps

- [Accessing datasets](/docs/datasets/concepts/datasets)
- [Async support](/docs/sdks/python/async)
- [Working with Xarray](/docs/sdks/python/xarray)

Source: https://tilebox.com/docs/datasets/introduction/index.mdx