Datasets

List Datasets

get

List all datasets.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Query parameters

limitinteger · min: 1 · max: 1000OptionalDefault: 100

offsetintegerOptionalDefault: 0

bboxany ofOptional

Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates.

Example: 12.34,56.78,23.45,67.89

stringOptional

or

nullOptional

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/datasets

HTTPcURLJavaScriptPython

GET /v1/datasets HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
    "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "type": "raster",
    "labels": [
      {
        "name": "text",
        "value": "text"
      }
    ],
    "tags": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "created_at": "2026-02-03T14:50:22.673Z"
  }
]

Add Dataset

post

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Body

application/json

or

or

or

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/datasets

HTTPcURLJavaScriptPython

POST /v1/datasets HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "name": "my_dataset",
  "tags": {
    "key": "value"
  },
  "visualization_optimization": "auto",
  "pixel_info_optimizations": [
    "time"
  ],
  "type": "image",
  "urls": "gs://example-bucket/image_*.tif",
  "bands": [
    "band1",
    "band2"
  ],
  "filename_date_pattern": "%Y-%m-%d",
  "filename_band_pattern": {
    "band": "band1",
    "pattern": "image_*.tif"
  }
}

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000"
}

Get Latest Dataset Version

get

Get the latest version of a dataset by dataset ID.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

dataset_idstring · uuidRequired

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/datasets/{dataset_id}/latest

HTTPcURLJavaScriptPython

GET /v1/datasets/{dataset_id}/latest HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "raster",
  "labels": [
    {
      "name": "text",
      "value": "text"
    }
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": {
      "sampled_min": 1,
      "sampled_max": 1
    }
  },
  "created_at": "2026-02-03T14:50:22.673Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-02-03T14:50:22.673Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-02-03T14:50:22.673Z"
    }
  },
  "dynamic_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  },
  "optimized_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  }
}

Get Dataset Version By Id

get

Get a dataset version by version ID.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

version_idstring · uuidRequired

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/dataset-versions/{version_id}

HTTPcURLJavaScriptPython

GET /v1/dataset-versions/{version_id} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "raster",
  "labels": [
    {
      "name": "text",
      "value": "text"
    }
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": {
      "sampled_min": 1,
      "sampled_max": 1
    }
  },
  "created_at": "2026-02-03T14:50:22.673Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-02-03T14:50:22.673Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-02-03T14:50:22.673Z"
    }
  },
  "dynamic_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  },
  "optimized_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  }
}