# Get Started with the Python API

### Prerequisites

* An Earthscale account. Please reach out to <support@earthscale.ai> in case you do not have one.
* Permissions to access the data you want to visualize. Please refer to the [Set up data access](https://docs.earthscale.ai/earthscale-documentation/access-your-own-data) section.

### Install the Earthscale Package

To use the Python API, first install the `earthscale` package:

{% tabs %}
{% tab title="uv" %}

```
uv add earthscale
```

{% endtab %}

{% tab title="poetry" %}

```
poetry add earthscale
```

{% endtab %}

{% tab title="pip" %}

```
pip install earthscale
```

{% hint style="info" %}
We recommend using a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) to install the `earthscale` package as it will help you manage dependencies and avoid conflicts with other packages.
{% endhint %}
{% endtab %}

{% tab title="conda" %}
We currently do not provide a conda package. However, you can install earthscale within a conda environment using pip.

```
conda install pip
pip install earthscale
```

{% endtab %}
{% endtabs %}

We currently require a minimum Python version of 3.10 and try to keep dependencies minimal to avoid conflicts with your environments.

### Authenticating

To use the Python client, you'll need to authenticate. There are two options:

#### 1. Using environment variables

For accounts with a username and password, set the following environment variables:

```shell
export EARTHSCALE_EMAIL=<your-email>
export EARTHSCALE_PASSWORD=<your-password>
```

This is helpful for using Earthscale in automated pipelines. You can inject the credentials into your pipelines using a secret manager like Vault.

#### 2. Login via Browser

If you use **"Continue with Google"** to log into Earthscale, you can use the `earthscale authenticate` CLI command or let the client handle authentication automatically.

### Adding a GeoTIFF Dataset

```python
from earthscale import EarthscaleClient

with EarthscaleClient() as client:
    response = client.add_image_dataset(
        name="Tanzania Landsat Sample",
        url="gs://earthscale-public/samples/hls_tanzania.tif",
    )
    dataset = client.get_dataset(response.dataset_id)
dataset
```

<details>

<summary>Output</summary>

```json
{
    "dataset_id": "27db659e-4fa3-42db-ab29-c435abce92df",
    "dataset_version_id": "0a67ace6-b48b-4749-8170-79dcca0782cb",
    "name": "HLS Tanzania",
    "type": "raster",
    "labels": [],
    "variables": {
        "B1": {
            "sampled_min": 0.0003,
            "sampled_max": 0.08
        },
        "B2": {
            "sampled_min": 0.0118,
            "sampled_max": 0.1006
        },
        "B3": {
            "sampled_min": 0.0353,
            "sampled_max": 0.1585
        }
    },
    "created_at": "2025-06-25T15:17:37.995957Z",
    "visualization_optimization": {
        "status": "pending",
        "updated_at": "2025-06-25T16:14:54.357705Z"
    },
    "pixel_info_optimizations": {},
    "dynamic_tile_server": {
        "tile_url": "https://dynamic.gcp.earthscale.ai/us-central1/v1/raster/0a67ace6-b48b-4749-8170-79dcca0782cb/tiles/{z}/{x}/{y}.webp",
        "pixel_url": "https://dynamic.gcp.earthscale.ai/us-central1/v1/raster/0a67ace6-b48b-4749-8170-79dcca0782cb/pixels/{lat}/{lon}",
        "min_zoom": 7,
        "max_zoom": 14
    },
    "optimized_tile_server": null
}
```

</details>

You can use the URL returned by the `dataset.dynamic_tile_server.tile_url` to integrate the tile server into your own application. Make sure you set the min and max zoom range as returned from this response in your map rendering library.

See [use-earthscale-in-your-products](https://docs.earthscale.ai/earthscale-documentation/use-earthscale-in-your-products "mention") on how to best configure and use suitable visualization parameters for these URLs.

### Listing datasets

```python
from earthscale import EarthscaleClient

with EarthscaleClient() as client:
    response = client.list_datasets()
response
```

<details>

<summary>Output</summary>

```json
[
    {
        "dataset_id": "27db659e-4fa3-42db-ab29-c435abce92df",
        "dataset_version_id": "0a67ace6-b48b-4749-8170-79dcca0782cb",
        "name": "HLS Tanzania",
        "type": "raster",
        "labels": [],
        "created_at": "2025-06-25T15:17:37.995957Z"
    }
]
```

</details>

You can use the dataset id in the list response to query details of a dataset using [get\_dataset()](https://docs.earthscale.ai/python-api-reference/client#earthscale.earthscaleclient.get_dataset)