> For the complete documentation index, see [llms.txt](https://docs.earthscale.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.earthscale.ai/python-api/python-api-reference/models.md).

# Models

## Requests

### AddImageDatasetRequest <a href="#earthscale.addimagedatasetrequest" id="earthscale.addimagedatasetrequest"></a>

Request to add an image dataset

#### type: Literal\['image'] <a href="#earthscale.addimagedatasetrequest.type" id="earthscale.addimagedatasetrequest.type"></a>

#### urls: list\[str] <a href="#earthscale.addimagedatasetrequest.urls" id="earthscale.addimagedatasetrequest.urls"></a>

#### bands: list\[str] | None <a href="#earthscale.addimagedatasetrequest.bands" id="earthscale.addimagedatasetrequest.bands"></a>

#### groupby: str | None <a href="#earthscale.addimagedatasetrequest.groupby" id="earthscale.addimagedatasetrequest.groupby"></a>

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

**Variables**

* **msg** – The deprecation message to be emitted.
* **wrapped\_property** – The property instance if the deprecated field is a computed field, or None.
* **field\_name** – The name of the field being deprecated.

#### filename\_date\_pattern: str | None <a href="#earthscale.addimagedatasetrequest.filename_date_pattern" id="earthscale.addimagedatasetrequest.filename_date_pattern"></a>

#### filename\_band\_pattern: list\[FilenameBandPattern] | None <a href="#earthscale.addimagedatasetrequest.filename_band_pattern" id="earthscale.addimagedatasetrequest.filename_band_pattern"></a>

#### labels: list\[DatasetLabel] | None <a href="#earthscale.addimagedatasetrequest.labels" id="earthscale.addimagedatasetrequest.labels"></a>

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

**Variables**

* **msg** – The deprecation message to be emitted.
* **wrapped\_property** – The property instance if the deprecated field is a computed field, or None.
* **field\_name** – The name of the field being deprecated.

### AddVectorDatasetRequest <a href="#earthscale.addvectordatasetrequest" id="earthscale.addvectordatasetrequest"></a>

Request to add a vector dataset

#### type: Literal\['vector'] <a href="#earthscale.addvectordatasetrequest.type" id="earthscale.addvectordatasetrequest.type"></a>

#### url: str <a href="#earthscale.addvectordatasetrequest.url" id="earthscale.addvectordatasetrequest.url"></a>

#### coordinate\_precision: Literal\['auto', '1250m', '600m', '300m', '150m', '80m', '40m', '20m', '10m', '5m', '2m', '1m', '50cm', '25cm', '15cm', '8cm'] <a href="#earthscale.addvectordatasetrequest.coordinate_precision" id="earthscale.addvectordatasetrequest.coordinate_precision"></a>

#### labels: list\[DatasetLabel] | None <a href="#earthscale.addvectordatasetrequest.labels" id="earthscale.addvectordatasetrequest.labels"></a>

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

**Variables**

* **msg** – The deprecation message to be emitted.
* **wrapped\_property** – The property instance if the deprecated field is a computed field, or None.
* **field\_name** – The name of the field being deprecated.

### AddZarrDatasetRequest <a href="#earthscale.addzarrdatasetrequest" id="earthscale.addzarrdatasetrequest"></a>

Request to add a Zarr dataset

#### type: Literal\['zarr'] <a href="#earthscale.addzarrdatasetrequest.type" id="earthscale.addzarrdatasetrequest.type"></a>

#### urls: list\[str] <a href="#earthscale.addzarrdatasetrequest.urls" id="earthscale.addzarrdatasetrequest.urls"></a>

#### rename: dict\[str, str] | None <a href="#earthscale.addzarrdatasetrequest.rename" id="earthscale.addzarrdatasetrequest.rename"></a>

#### check\_only\_one\_url\_for\_now <a href="#earthscale.addzarrdatasetrequest.check_only_one_url_for_now" id="earthscale.addzarrdatasetrequest.check_only_one_url_for_now"></a>

```python
check_only_one_url_for_now() → AddZarrDatasetRequest
```

**Return type**

[`AddZarrDatasetRequest`](#earthscale.AddZarrDatasetRequest)

#### labels: list\[DatasetLabel] | None <a href="#earthscale.addzarrdatasetrequest.labels" id="earthscale.addzarrdatasetrequest.labels"></a>

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

**Variables**

* **msg** – The deprecation message to be emitted.
* **wrapped\_property** – The property instance if the deprecated field is a computed field, or None.
* **field\_name** – The name of the field being deprecated.

### AddTileServerDatasetRequest <a href="#earthscale.addtileserverdatasetrequest" id="earthscale.addtileserverdatasetrequest"></a>

#### type: Literal\['tileserver'] <a href="#earthscale.addtileserverdatasetrequest.type" id="earthscale.addtileserverdatasetrequest.type"></a>

#### url: str <a href="#earthscale.addtileserverdatasetrequest.url" id="earthscale.addtileserverdatasetrequest.url"></a>

#### labels: list\[DatasetLabel] | None <a href="#earthscale.addtileserverdatasetrequest.labels" id="earthscale.addtileserverdatasetrequest.labels"></a>

Read-only data descriptor used to emit a runtime deprecation warning before accessing a deprecated field.

**Variables**

* **msg** – The deprecation message to be emitted.
* **wrapped\_property** – The property instance if the deprecated field is a computed field, or None.
* **field\_name** – The name of the field being deprecated.

### AddDatasetRequest <a href="#earthscale.adddatasetrequest" id="earthscale.adddatasetrequest"></a>

alias of [`AddImageDatasetRequest`](#earthscale.AddImageDatasetRequest) | [`AddZarrDatasetRequest`](#earthscale.AddZarrDatasetRequest) | [`AddVectorDatasetRequest`](#earthscale.AddVectorDatasetRequest) | [`AddTileServerDatasetRequest`](#earthscale.AddTileServerDatasetRequest)

## Responses

### AddDatasetResponse <a href="#earthscale.adddatasetresponse" id="earthscale.adddatasetresponse"></a>

#### dataset\_id: UUID <a href="#earthscale.adddatasetresponse.dataset_id" id="earthscale.adddatasetresponse.dataset_id"></a>

Dataset ID of the newly created dataset version

#### dataset\_version\_id: UUID <a href="#earthscale.adddatasetresponse.dataset_version_id" id="earthscale.adddatasetresponse.dataset_version_id"></a>

Dataset Version ID of the newly created dataset version

### DeleteDatasetResponse <a href="#earthscale.deletedatasetresponse" id="earthscale.deletedatasetresponse"></a>

#### dataset\_id: UUID <a href="#earthscale.deletedatasetresponse.dataset_id" id="earthscale.deletedatasetresponse.dataset_id"></a>

Dataset ID of the deleted dataset

#### dataset\_version\_id: UUID <a href="#earthscale.deletedatasetresponse.dataset_version_id" id="earthscale.deletedatasetresponse.dataset_version_id"></a>

Dataset Version ID of the deletion marker version

### DatasetResponse <a href="#earthscale.datasetresponse" id="earthscale.datasetresponse"></a>

#### dataset\_id: UUID <a href="#earthscale.datasetresponse.dataset_id" id="earthscale.datasetresponse.dataset_id"></a>

Dataset ID of the dataset

#### dataset\_version\_id: UUID <a href="#earthscale.datasetresponse.dataset_version_id" id="earthscale.datasetresponse.dataset_version_id"></a>

ID for the current version of the dataset

#### name: str <a href="#earthscale.datasetresponse.name" id="earthscale.datasetresponse.name"></a>

Name of the dataset

#### type: DatasetType <a href="#earthscale.datasetresponse.type" id="earthscale.datasetresponse.type"></a>

Type of the dataset, either raster or vector

#### labels: list\[DatasetLabel] <a href="#earthscale.datasetresponse.labels" id="earthscale.datasetresponse.labels"></a>

User-defined labels for the dataset. Superseded by tags.

**Type**

Deprecated

#### tags: dict\[str, str] <a href="#earthscale.datasetresponse.tags" id="earthscale.datasetresponse.tags"></a>

User-defined tags for the dataset

#### variables: dict\[str, Variable] <a href="#earthscale.datasetresponse.variables" id="earthscale.datasetresponse.variables"></a>

Estimated statistics for each variable in the dataset, useful for visualization

#### created\_at: AwareDatetime <a href="#earthscale.datasetresponse.created_at" id="earthscale.datasetresponse.created_at"></a>

Timestamp of when the dataset was created

#### visualization\_optimization: Optimization <a href="#earthscale.datasetresponse.visualization_optimization" id="earthscale.datasetresponse.visualization_optimization"></a>

Status of the visualization optimization for faster visualization

#### pixel\_info\_optimizations: dict\[str, Optimization] <a href="#earthscale.datasetresponse.pixel_info_optimizations" id="earthscale.datasetresponse.pixel_info_optimizations"></a>

Status of the pixel info optimizations for faster pixel info retrieval

#### dynamic\_tile\_server: TileServer <a href="#earthscale.datasetresponse.dynamic_tile_server" id="earthscale.datasetresponse.dynamic_tile_server"></a>

Dynamic tile server for fast visualization

#### optimized\_tile\_server: TileServer | None <a href="#earthscale.datasetresponse.optimized_tile_server" id="earthscale.datasetresponse.optimized_tile_server"></a>

Optimized tile server for fast visualization

### ListDatasetResponse <a href="#earthscale.listdatasetresponse" id="earthscale.listdatasetresponse"></a>

Single entry in the list of datasets with a subset of information

#### dataset\_id: UUID <a href="#earthscale.listdatasetresponse.dataset_id" id="earthscale.listdatasetresponse.dataset_id"></a>

Dataset ID of the dataset

#### dataset\_version\_id: UUID <a href="#earthscale.listdatasetresponse.dataset_version_id" id="earthscale.listdatasetresponse.dataset_version_id"></a>

ID for the current version of the dataset

#### name: str <a href="#earthscale.listdatasetresponse.name" id="earthscale.listdatasetresponse.name"></a>

Name of the dataset

#### type: DatasetType <a href="#earthscale.listdatasetresponse.type" id="earthscale.listdatasetresponse.type"></a>

Type of the dataset, either raster or vector

#### labels: list\[DatasetLabel] <a href="#earthscale.listdatasetresponse.labels" id="earthscale.listdatasetresponse.labels"></a>

User-defined labels for the dataset. Superseded by tags.

**Type**

Deprecated

#### tags: dict\[str, str] <a href="#earthscale.listdatasetresponse.tags" id="earthscale.listdatasetresponse.tags"></a>

User-defined tags for the dataset

#### created\_at: AwareDatetime <a href="#earthscale.listdatasetresponse.created_at" id="earthscale.listdatasetresponse.created_at"></a>

Timestamp of when the dataset was created

#### updated\_at: AwareDatetime <a href="#earthscale.listdatasetresponse.updated_at" id="earthscale.listdatasetresponse.updated_at"></a>

Timestamp of when the dataset was last updated

### PaginatedListDatasetResponse <a href="#earthscale.paginatedlistdatasetresponse" id="earthscale.paginatedlistdatasetresponse"></a>

Paginated list of datasets with cursor-based pagination

#### data: list\[ListDatasetResponse] <a href="#earthscale.paginatedlistdatasetresponse.data" id="earthscale.paginatedlistdatasetresponse.data"></a>

List of datasets

#### next\_cursor: str | None <a href="#earthscale.paginatedlistdatasetresponse.next_cursor" id="earthscale.paginatedlistdatasetresponse.next_cursor"></a>

Opaque cursor token for fetching the next page

### VersionCheckResponse <a href="#earthscale.versioncheckresponse" id="earthscale.versioncheckresponse"></a>

#### is\_supported: bool <a href="#earthscale.versioncheckresponse.is_supported" id="earthscale.versioncheckresponse.is_supported"></a>

#### newest\_supported\_version: int <a href="#earthscale.versioncheckresponse.newest_supported_version" id="earthscale.versioncheckresponse.newest_supported_version"></a>

#### is\_deprecated: bool <a href="#earthscale.versioncheckresponse.is_deprecated" id="earthscale.versioncheckresponse.is_deprecated"></a>

#### will\_be\_removed\_after: date | None <a href="#earthscale.versioncheckresponse.will_be_removed_after" id="earthscale.versioncheckresponse.will_be_removed_after"></a>

#### deprecation\_message: str | None <a href="#earthscale.versioncheckresponse.deprecation_message" id="earthscale.versioncheckresponse.deprecation_message"></a>

## Other Models

### DatasetType <a href="#earthscale.datasettype" id="earthscale.datasettype"></a>

#### RASTER = 'raster' <a href="#earthscale.datasettype.raster" id="earthscale.datasettype.raster"></a>

#### VECTOR = 'vector' <a href="#earthscale.datasettype.vector" id="earthscale.datasettype.vector"></a>

### DatasetLabel <a href="#earthscale.datasetlabel" id="earthscale.datasetlabel"></a>

User-defined label for a dataset

#### name: str <a href="#earthscale.datasetlabel.name" id="earthscale.datasetlabel.name"></a>

Name of the label. Can be any string.

#### value: str <a href="#earthscale.datasetlabel.value" id="earthscale.datasetlabel.value"></a>

Value of the label. Can be any string.

### SimpleDatasetMetadata <a href="#earthscale.simpledatasetmetadata" id="earthscale.simpledatasetmetadata"></a>

Simplified metadata with only essential fields

#### description: str | None <a href="#earthscale.simpledatasetmetadata.description" id="earthscale.simpledatasetmetadata.description"></a>

#### thumbnail\_url: str | None <a href="#earthscale.simpledatasetmetadata.thumbnail_url" id="earthscale.simpledatasetmetadata.thumbnail_url"></a>

#### attributes: list\[DatasetLabel] <a href="#earthscale.simpledatasetmetadata.attributes" id="earthscale.simpledatasetmetadata.attributes"></a>

#### license: str | None <a href="#earthscale.simpledatasetmetadata.license" id="earthscale.simpledatasetmetadata.license"></a>

### FilenameBandPattern <a href="#earthscale.filenamebandpattern" id="earthscale.filenamebandpattern"></a>

Pattern for mapping filename patterns to band names

#### pattern: str <a href="#earthscale.filenamebandpattern.pattern" id="earthscale.filenamebandpattern.pattern"></a>

#### band: str | None <a href="#earthscale.filenamebandpattern.band" id="earthscale.filenamebandpattern.band"></a>

#### band\_mapping: dict\[int, str] | None <a href="#earthscale.filenamebandpattern.band_mapping" id="earthscale.filenamebandpattern.band_mapping"></a>

### DatasetOverviewsStatus <a href="#earthscale.datasetoverviewsstatus" id="earthscale.datasetoverviewsstatus"></a>

#### status: str <a href="#earthscale.datasetoverviewsstatus.status" id="earthscale.datasetoverviewsstatus.status"></a>

Status of the dataset overview generation. One of:

* “not\_started”: Overview generation has not started yet
* “pending”: Overview generation is pending
* “running”: Overview generation is running
* “success”: Overview generation has completed successfully
* “error”: Overview generation has failed

#### updated\_at: datetime | None <a href="#earthscale.datasetoverviewsstatus.updated_at" id="earthscale.datasetoverviewsstatus.updated_at"></a>

Timestamp of the last update to the status

### OptimizationStatus <a href="#earthscale.optimizationstatus" id="earthscale.optimizationstatus"></a>

alias of `Literal`\[‘not\_started’, ‘pending’, ‘running’, ‘success’, ‘error’]

### Optimization <a href="#earthscale.optimization" id="earthscale.optimization"></a>

#### status: Literal\['not\_started', 'pending', 'running', 'success', 'error'] <a href="#earthscale.optimization.status" id="earthscale.optimization.status"></a>

Status of the optimization. One of:

* “not\_started”: Optimization has not started yet
* “pending”: Optimization is pending
* “running”: Optimization is running
* “success”: Optimization has completed successfully
* “error”: Optimization has failed

#### updated\_at: datetime | None <a href="#earthscale.optimization.updated_at" id="earthscale.optimization.updated_at"></a>

Timestamp of the last update to the status

### TileServer <a href="#earthscale.tileserver" id="earthscale.tileserver"></a>

#### tile\_url: str <a href="#earthscale.tileserver.tile_url" id="earthscale.tileserver.tile_url"></a>

Tileserver URL to be used in an application

#### pixel\_url: str <a href="#earthscale.tileserver.pixel_url" id="earthscale.tileserver.pixel_url"></a>

Pixel info URL to be used in an application

#### min\_zoom: int <a href="#earthscale.tileserver.min_zoom" id="earthscale.tileserver.min_zoom"></a>

Minimum zoom level supported by the tile server

#### max\_zoom: int <a href="#earthscale.tileserver.max_zoom" id="earthscale.tileserver.max_zoom"></a>

Maximum zoom level supported by the tile server

### Variable <a href="#earthscale.variable" id="earthscale.variable"></a>

Estimated statistics for a variable in the dataset, useful for visualization

#### sampled\_min: float <a href="#earthscale.variable.sampled_min" id="earthscale.variable.sampled_min"></a>

Estimated minimum value in the dataset

#### sampled\_max: float <a href="#earthscale.variable.sampled_max" id="earthscale.variable.sampled_max"></a>

Estimated maximum value in the dataset


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.earthscale.ai/python-api/python-api-reference/models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.