# Tilebox Datasets

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:

[Datasets](/docs/datasets/concepts/datasets)

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

[Collections](/docs/datasets/concepts/collections)

Learn what collections are and how to access them.

[Querying Data](/docs/datasets/query/querying-data)

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

[Ingesting Data](/docs/datasets/ingest)

Learn how to ingest data into a collection.

[Assets and storage](/docs/datasets/assets-and-storage/overview)

Connect dataset metadata to files in object storage.

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.

**Data points**

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.

**Datasets**

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.

**Collections**

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

## 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**

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

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

**Go**

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

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

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

**Go**

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

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

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**

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

**Go**

```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)
	}
}
```

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**

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

**Go**

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