Get Started with the Python API

Prerequisites

• An Earthscale account. Please reach out to [email protected] in case you do not have one.

• Permissions to access the data you want to visualize. Please refer to the Set up data access section.

Install the Earthscale Package

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

uv

uv add earthscale

poetry

poetry add earthscale

pip

pip install earthscale

We recommend using a virtual environment to install the earthscale package as it will help you manage dependencies and avoid conflicts with other packages.

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

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:

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 "Sign in 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

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

Output

{
  "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
}

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 on how to best configure and use suitable visualization parameters for these URLs.

Listing datasets

from earthscale import EarthscaleClient

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

Output

[
  {
    "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"
  }
]

You can use the dataset id in the list response to query details of a dataset using get_dataset()