EarthscaleClient

Client for the Earthscale API.

Can be used to add, list, and retrieve datasets.

There are two ways to authenticate with Earthscale:

1. Email and password environment variables: Set the EARTHSCALE_EMAIL and EARTHSCALE_PASSWORD environment variables

2. OAuth: If the environment variables are not set, a browser window will be opened to authenticate using OAuth. This only works if running in a graphical environment where a browser window can be opened.

Examples

Usage with environment variables:

import os
from earthscale import EarthscaleClient

os.environ["EARTHSCALE_EMAIL"] = "[email protected]"
os.environ["EARTHSCALE_PASSWORD"] = "service_password"

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

__init__

__init__(
    api_url: str | None = None,
    auth_url: str | None = None,
    anon_key: str | None = None,
    skip_version_check: bool = False,
    session: Session | None = None,
    use_proxy: bool = False
)

Initialize the Earthscale client.

Parameters

Name	Type	Description	Default
api_url	str | None	Custom URL of the Earthscale API. Defaults to https://api.earthscale.ai.	None
auth_url	str | None	Custom URL for the authentication service. Defaults to https://supabase.earthscale.ai.	None
anon_key	str | None	Custom anon key for the authentication service. If not set, the client will use the default anon key for https://supabase.earthscale.ai.	None
skip_version_check	bool	Whether to skip version compatibility check.	False
session	Session | None	Optional custom requests session to use.	None
use_proxy	bool	Whether to use the proxy server for authentication	False

login

login() → None

Login using service account credentials from environment variables, or OAuth authentication if no environment variables are set.

Raises

AuthenticationError – If authentication fails.

Return type

None

add_image_dataset

add_image_dataset(
    name: str,
    url: str | list[str],
    labels: list[DatasetLabel] | None = None,
    bands: list[str] | None = None,
    groupby: str | None = None,
    filename_date_pattern: str | None = None,
    filename_band_pattern: list[dict[str, str]] | None = None,
    visualization_optimization: bool | Literal['auto'] = 'auto',
    pixel_info_optimizations: list[str] | None = None
) → AddDatasetResponse

Add an image dataset. Images must be in a format that can be read by rasterio, e.g. GeoTIFFs.

This function supports creating a time dimension through the filename_date_pattern argument. This pattern uses strftime-style format codes to extract date information from the filenames.

Examples

For filenames like brasil_coverage_2011.tif:

from earthscale import EarthscaleClient

with EarthscaleClient() as client:
    client.add_image_dataset(
        name="my_dataset",
        url="gs://mybucket/my_dataset/brasil_coverage_*.tif",
        filename_date_pattern="%Y",
    )

Parameters

Name	Type	Description	Default
name	str	The name of the dataset. Creates a new version of an existing dataset if the latest version of a dataset has the same name.
url	str | list[str]	The URL or list of URLs of the dataset.
labels	list[DatasetLabel] | None	Optional attributes as key-value pairs.	None
bands	list[str] | None	Optional list of bands to include.	None
groupby	str | None	[DEPRECATED] Will be ignored. If filename_date_pattern or filename_band_pattern are provided, those will be used as group keys) for a time dimension and variables respectively. Otherwise, this defaults to putting all images onto the same plane.	None
filename_date_pattern	str | None	Optional date pattern for filenames.	None
filename_band_pattern	list[dict[str, str]] | None	Optional band patterns for filenames. E.g. {"*_B[0-9]": "band_1"} would map all bands starting with B and ending with a number to band_1. Uses Unix filename pattern rules.	None
visualization_optimization	Union[bool, Literal['auto']]	Whether to optimize for visualization. Use auto for automatic optimization based on size, True to force, or False to disable. Defaults to auto.	'auto'
pixel_info_optimizations	list[str] | None	List of dimensions to optimize for pixel info API. Defaults to None.	None

Return type

AddDatasetResponse

Returns

The dataset response.

add_zarr_dataset

add_zarr_dataset(
    name: str,
    url: str,
    labels: list[DatasetLabel] | None = None,
    rename: dict[str, str] | None = None,
    visualization_optimization: bool | Literal['auto'] = 'auto',
    pixel_info_optimizations: list[str] | None = None
) → AddDatasetResponse

Add a Zarr dataset.

When loading into xarray, this dataset type will automatically standardize the dimensions of the dataset to y, x and time if present. It will infer spatial dimensions, so if lon or longitude is present, it will be renamed to x.

This supports arbitrary multi-dimensional datasets, for example a dataset with time or level dimensions in addition to y, x.

Parameters

Name	Type	Description	Default
name	str	The name of the dataset. Creates a new version of an existing dataset if the latest version of a dataset has the same name.
url	str	The URL of the dataset. Can optionally contain a placeholder for the dimension name. If specified, this concatenates multiple Zarrs along either an existing or new dimension as named in the pattern. Example: gs://mybucket/my_dataset/{time}.zarr
labels	list[DatasetLabel] | None	Optional. User-defined labels as key-value pairs.	None
rename	dict[str, str] | None	Optional. Dictionary to rename dimensions.	None
visualization_optimization	Union[bool, Literal['auto']]	Whether to optimize for visualization. Use auto for automatic optimization based on size, True to force, or False to disable. Defaults to auto.	'auto'
pixel_info_optimizations	list[str] | None	List of dimensions to optimize for pixel info API. Defaults to None.	None

Return type

AddDatasetResponse

Returns

The dataset response.

add_vector_dataset

add_vector_dataset(
    name: str,
    url: str,
    labels: list[DatasetLabel] | None = None
) → AddDatasetResponse

Add a vector dataset.

This function supports adding vector datasets from a variety of sources, including GeoJSON, GeoParquet, FlatGeobuf, and more.

Parameters

Name	Type	Description	Default
name	str	The name of the dataset. Creates a new version of an existing dataset if the latest version of a dataset has the same name.
url	str	The URL of the dataset.
labels	list[DatasetLabel] | None	Optional attributes as key-value pairs.	None

Return type

AddDatasetResponse

Returns

The dataset response.

add_tile_server_dataset

add_tile_server_dataset(
    name: str,
    url: str,
    labels: list[DatasetLabel] | None = None
) → AddDatasetResponse

Add a tile server dataset.

The URL must be a template string with placeholders for the x, y, and z coordinates, e.g. https://server.com/tiles/{z}/{x}/{y}.png.

Parameters

Name	Type	Description	Default
name	str	The name of the dataset.
url	str	The URL of the dataset.
labels	list[DatasetLabel] | None	Optional attributes as key-value pairs.	None

Return type

AddDatasetResponse

Returns

The dataset response.

list_datasets

list_datasets() → list[ListDatasetResponse]

List all datasets.

Return type

list[ListDatasetResponse]

Returns

The dataset list response. Each element in the list contains basic metadata such as the ID, name, and labels.

get_dataset

get_dataset(
    dataset_id: str | UUID
) → DatasetResponse

Get the latest version of a dataset by dataset ID.

Parameters

Return type

DatasetResponse

Returns

The dataset response.

get_dataset_version_by_id

get_dataset_version_by_id(
    version_id: str | UUID
) → DatasetResponse

Get a dataset version by version ID.

Parameters

Return type

DatasetResponse

Returns

The dataset response.

check_api_support

check_api_support() → VersionCheckResponse

Check if the client’s API version is compatible with the server.

This method contacts the server to verify that the API version used by the client is supported by the server. It also provides information about the supported API versions and whether the current version is deprecated.

Return type

VersionCheckResponse

Returns

The version check response from the server.

Raises

VersionIncompatibleError – If the API version is not supported by the server.