# 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](/earthscale-documentation/access-your-own-data.md) 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](/earthscale-documentation/use-earthscale-in-your-products.md) 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/pages/q3OsFXO1jM6KzZZNsgKt#earthscale.earthscaleclient.get_dataset)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.earthscale.ai/python-api/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.