# Welcome Welcome to the Earthscale documentation. Here you will find guides and reference documentation to the [Earthscale web app](https://app.earthscale.ai) as well as the [Python](/python-api/getting-started) and [HTTP](/http-api/earthscale-http-api) APIs we offer. {% hint style="info" %} To try a free version of Earthscale, you can sign up at . {% endhint %} ### Starting Points
Cover image
Get started with the Earthscale web apphttps://cdn.earthscale.ai/docs/assets/title.webplinkQuickstart
Access your own dataearthscale-connections-dark.webplinkAccess Your Own Data
Use Earthscale tile servers in your productsearthscale-use.webplinkUse Earthscale in Your Products
Get started with our Python APIpreview-python.webplinkGet Started with the Python API
Read detailed docs of our Python APIpreview-python-ref.webplinkEarthscaleClient
Read detailed docs of our HTTP APIpreview-http.webplinkEarthscale HTTP API
### Onboarding We are happy to schedule a short onboarding call to help solve your specific use case. You can book a time with us [here](https://calendly.com/d/cwp3-mtj-z6x/earthscale-onboarding-call). Also, feel free to reach out to us directly via Slack or [email](mailto:support@earthscale.ai) if you have any clarifying questions. # Quickstart The fastest way to get started is to add some example data and explore the user interface. This lets you try out all the features without having to set up credentials. ## Add an example dataset When you open [Earthscale](https://app.earthscale.ai/), there is a sidebar on the left-hand side that shows your current map and allows you to add new data. Click on **"Add new dataset"**
To test things out, we're going to register a public cloud dataset. To do so, switch to the **Cloud Source** tab, and use the following URL as an example `Dataset URL`: ``` gs://earthscale-public/samples/era5-10-timesteps.zarr/ ```
Click `Continue` to proceed. Earthscale will now read the metadata (location on the map, resolution, projection, etc.) from the dataset. Once this process is finished, the dataset should appear on the map. ## Editing the visualization Now, try switch the band and/or update the maximum value to update the visualization in real time. To do so, you can either use the three dots and then select `Edit Visualization` or
You can use the arrow at the top right of the editor to get back to the map or alternatively press `Esc`. ## Click on the map to get pixel info To get the exact value of a pixel, just click on it:
This places a marker at the exact location that was clicked. On the right-hand side, you can find the coordinates of the point as well as the pixel values for all bands at this location. All visible datasets at the clicked point are queried, but you can disable or enable specific ones by **clicking the table button** ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-8fa418ffd732ee9c5a79373c1cc4f57705b1a843%2Fimage%20\(3\)%20\(1\).png?alt=media) on the right-hand side. ## Working with multidimensional data The ERA5 weather dataset that we have added in the first step has a `time` dimension. The Dataset Card allows you to step through the different timesteps After adding one of these, you can see the all dimensions as well as their currently displayed value below the dataset in the sidebar:
**Click a pixel** to see additional options for multidimensional datasets. Then **Click the chart icon** ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-df045ef993bbd3fe24b14b381746130fa8a49838%2Fimage.png?alt=media) to query the history of the pixel value at the current location:
## Next steps
Access Your Own Dataearthscale-connections-dark.webpAccess Your Own Data
Use Earthscale Tile Servers in Your Productsearthscale-use.webpUse Earthscale in Your Products
Get Started with the Python APIpreview-python.webpGet Started with the Python API
# Access Your Own Data Earthscale currently supports connecting to these data sources:
Amazon (AWS S3)AWS S3aws-card.webp
Microsoft Azure Blob StorageAzure Blob Storageazure-card.webp
Google Cloud (GCP)Google Cloud (GCP)google-cloud-card.webp
Google DriveGoogle Drivegdrive gray.png
Local File UploadLocal File Uploadupload cloud white with black bg and border.png
Click on a data source to see details on how to connect to it. # AWS S3 ### Supported URL formats Earthscale supports S3 URLs formatted like: ``` s3://{bucket_name}/{path_to_files_that_can_contain_glob_patterns} ``` Values in curly brackets are placeholders. ### Security Earthscale uses OpenID Connect (OIDC) to securely access your cloud data using dedicated per-customer service accounts. This eliminates the need to share credentials while providing fine-grained access control over your cloud resources. It also lets you revoke access at any time if necessary. ### Granting Access To grant Earthscale read-only access to an S3 bucket: * Open [Earthscale](https://app.earthscale.ai/) * Click on the user icon in the top-right corner of the left sidebar * Click **"Cloud Access"**
* Enter the bucket name you want to share and click the **"Copy"** ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-94cc62aee7a57ea81562d7d330275450eaee1fc8%2Fcopy-icon.png?alt=media) button at the top-right corner. ![](https://cdn.earthscale.ai/docs/assets/aws_access.webp) * Execute the command in your CLI or send the instructions to the responsible administrator in your organization. ### Use the AWS Console If you do not have access to the CLI or want more control, you can use the AWS Console to grant us access to a bucket. * Open [Earthscale](https://app.earthscale.ai/) * Click on the user icon in the top-right corner of the left sidebar * Click **"Cloud Access"** * On the **"Amazon Web Services (AWS)"** tab you can see the principal id we use to access data for your organization (there is one per customer) * Click the copy button next to it or copy it manually
* Navigate to the bucket you want to share on the AWS Console * Click the **"Permissions"** tab * Locate the **"Bucket policy"** section * Click the **"Edit"** button in this section
* This opens the policy editor. Copy this JSON and paste it into a local text editor (Visual Studio Code or Notepad, for example): ```json { "Sid": "AllowEarthscaleAccess", "Effect": "Allow", "Principal": { "AWS": "{YOUR_PRINCIPAL}" }, "Resource": [ "arn:aws:s3:::{YOUR_BUCKET_NAME}", "arn:aws:s3:::{YOUR_BUCKET_NAME}/*" ], "Action": [ "s3:GetObject", "s3:GetBucketLocation", "s3:ListBucket" ] } ``` * Replace the text `{YOUR_PRINCIPAL}` with the principal copied from Earthscale * Replace the text `{YOUR_BUCKET_NAME}` with the bucket name you want to share (copy it from the AWS console to be safe from typos) * Careful, this occurs twice, once it is trailed by `/*` and once it is not * Copy the modified entry from your text editor * Append it to the end of the statement list in the AWS Console policy editor {% hint style="warning" %} The policy likely contains other statements. Make sure to not delete or modify any existing ones. Just append to the end. If you are unsure at any point, do not edit the policy, and ask your administrator or contact us on Slack or [email](mailto:support@earthscale.ai) {% endhint %} {% hint style="info" %} You can also use the policy editor to see how appending a new statement would look, by using the **"Add new statement"** button at the bottom. This lets you see where to insert the new statement easily. You can also use the graphical editor on the right-hand side, but it is likely easier to just copy-paste it from above. {% endhint %} * Finally, do not forget to click **"Save changes":**
From now on, you should be able to add any datasets in this bucket to Earthscale using their `s3://` URLs! ## Creating a new bucket If you'd prefer to grant Earthscale access to a brand new bucket, you can follow the [AWS guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) to create one. Then, follow the instructions above to grant Earthscale access to that bucket. # Azure Blob Storage ### Supported URL formats Earthscale supports Azure URLs formatted like: {% code overflow="wrap" %} ``` https://{storageaccount}.blob.core.windows.net/{path_can_contain_glob_patterns} ``` {% endcode %} Values in curly brackets are placeholders. You can get URLs like this from Azure Storage Explorer:
Or from the Azure Portal:
### Security Earthscale uses OpenID Connect (OIDC) to securely access your cloud data using dedicated per-customer service accounts. This eliminates the need to share credentials while providing fine-grained access control over your cloud resources. It also lets you revoke access at any time if necessary. ### Granting Access To grant Earthscale read-only access to an Azure Storage Container: * Open [Earthscale](https://app.earthscale.ai/) * Click on the user icon in the top-right corner of the left sidebar * Click **"Cloud Access"**
* Select the **"Microsoft Azure"** tab
* Follow the instructions there, and make sure to notify us of your Azure Tenant ID so we can grant access on our side. You can send this information to [support@earthscale.ai](https://earthscale.ai/). # Google Cloud (GCP) ### Supported URL formats Earthscale supports GCP URLs formatted like: ``` gs://{bucket_name}/{path_to_files_can_contain_glob_patterns} ``` Values in curly brackets are placeholders. ### Security Earthscale uses OpenID Connect (OIDC) to securely access your cloud data using dedicated per-customer service accounts. This eliminates the need to share credentials while providing fine-grained access control over your cloud resources. It also lets you revoke access at any time if necessary. ### Granting Access \ To grant Earthscale access to a GCP bucket: * Open [Earthscale](https://app.earthscale.ai/) * Click on the user icon in the top-right corner of the left sidebar * Click **"Cloud Access"** Here you can see the GCP service account used to access your data, and copy a command to grant access to a bucket: ![](https://cdn.earthscale.ai/docs/assets/gcp_access.webp) Just enter your bucket name in the input box and click the **"Copy"** ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-94cc62aee7a57ea81562d7d330275450eaee1fc8%2Fcopy-icon.png?alt=media) button at the top-right corner. ### Use the Google Cloud Console If you do not have access to the CLI, you can also grant access in the [Google Cloud Console](https://console.cloud.google.com/storage/browser/). * Copy your Earthscale GCP service account email from the cloud access dialog (see above). It should look like: `earthscale-data-25adc84a@earthscale.iam.gserviceaccount.com` ![](https://cdn.earthscale.ai/docs/assets/gcp_access.webp) * Navigate to the bucket you want to share in the Google Cloud Console * Tab **"Permissions"** * Tab **"View by principals"** * Click **"Grant access"** ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-fc342288f011cdb0c18d7708d70c5f24c4ea217f%2Fcloud-access-gcp-console-permissions.webp?alt=media) * Enter the storage account email you copied before into the **"Principals"** field * Add the **"Storage Object Viewer"** role ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-bb16bbf5f7bd731d9fd1482a643f5b08c62011b5%2Fcloud-access-gcp-console-add-viewer.webp?alt=media) ## Creating a new bucket If you'd prefer to grant Earthscale access to a brand new bucket, you can follow the [GCP guide](https://cloud.google.com/storage/docs/creating-buckets) to create one. Then, follow the instructions above to grant Earthscale access to that bucket. # Local File Upload Earthscale allows you to upload folders or individual files from your machine to share and serve alongside other cloud-based datasets. To upload data, first click "**Add new dataset**" and expand the menu option "**Upload local files**".
Next, select the file or directory you'd like to upload. The data can be in any format readable by Earthscale, see [Supported Dataset Formats](/earthscale-documentation/supported-formats) for more information. As a shortcut to this, at any time you can also directly **drag and drop** data from your file explorer into Earthscale without opening the "**Add new dataset**" panel. Next, the dataset will begin uploading. The data is automatically copied to a private Google Cloud Storage bucket hosted by Earthscale. Once the upload finishes, it will be added to your catalog as well as your current map. You can also immediately serve the dataset in your own applications like any other Earthscale dataset. You can read more about that process in [Use Earthscale in Your Products](/earthscale-documentation/use-earthscale-in-your-products). # Google Drive ### Granting access To grant access to a Google Drive directory or file, you will first need to locate the dedicated GCP service account that we use to securely read your organization's data. You can find this under **Cloud Access** instructions in the user menu.
Copy this address for the next step. In Google Drive, right-click the file or directory, and under "**Share**" click "**Share**".
Finally, give the service account email "**Viewer**" permissions to read it.
If you've added a directory, from now on Earthscale should be able to read any files contained in that directory! ### Adding a dataset via shareable links To obtain the dataset URL, right-click the file, and under "**Share**" select "**Copy link**".

Click "Copy link" to obtain a shareable dataset link

Next, paste the URL into the "**Dataset URL**" field in the "**Add New Dataset**" menu to register the dataset.

Paste the shareable link into the "Dataset URL" field.

Then click "**Next**" to continue and add the dataset to Earthscale. {% hint style="info" %} Currently, in Google Drive, we only support adding one file at a time, such as a GeoJSON or GeoTIFF. For more complex datasets with multiple files, such as GeoTIFF directories or Zarr stores, please upload to another data provider listed in [Access Your Own Data](/earthscale-documentation/access-your-own-data). For .shp files, please export to another single-file format such as GeoJSON. {% endhint %} # Use Earthscale in Your Products You can easily use Earthscale's tile servers from any common map rendering library that supports [XYZ tiles](https://en.wikipedia.org/wiki/Tiled_web_map#Defining_a_tiled_web_map). These are URLs formatted using placeholders for WebMercator tile coordinates like `{x}, {y}, {z}`. A common workflow is to: * Add a dataset using the [Earthscale web app](https://app.earthscale.ai/) * Configure the visualization in the web app * Export the tile server URL or download an example that uses your data ## Steps * Open the **dataset details** window by clicking on the triple dots icon ![](https://2565285527-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FarN1JFGInZYYYNhA61wM%2Fuploads%2Fgit-blob-630a003bf49e6abf64be25c1bf324a03f22f0a34%2Fimage.png?alt=media) on a dataset in the sidebar and selecting **"View Details"** in the menu:
* Click **"Add to Application"** on the right-hand side:
* You can also get to this dialog using the **"Build"** button in the topbar. Here, select "Sample Code"
* And open the example in your browser:
## Use with AI Assistants Earthscale provides a "Use Map in AI" feature that generates instructions for AI assistants to work with your map data. This feature: * Generates a structured prompt with metadata about all datasets currently loaded in your map * Includes tile server URLs and point query endpoints for each dataset * Provides dimension information for raster datasets (e.g., time series data) * Formats everything with clear instructions for the AI to use the Earthscale API ### Steps 1\. Click the **Build** button in the top bar
2\. Copy the generated prompt snippet
3\. Paste it into your AI assistant (ChatGPT, Claude, etc.) 4\. The AI can then: * Generate code to visualize your data in frameworks like Leaflet, Folium, or MapLibre * Create point queries to fetch pixel values at specific coordinates * Handle multi-dimensional data by selecting appropriate dimension indices * Respect zoom level constraints for optimal tile loading ## Automate it You can use the [Python API](/python-api/getting-started) to add datasets and get their tile server URLs. For visualization parameters, we recommend configuring them once in the Earthscale web UI, and then reusing the parameters from the tile server URL displayed in the dataset details. You can also edit visualizations directly through the API parameters, see the [tile server URL specification](/http-api/dynamic-tiler-http-api). ## Security To ease integration into your products, our tile servers use per-user API keys for authentication. You can see your API key in the exported URLs, as they are passed as GET parameters. We can revoke access to API keys at any time. If you accidentally leaked an API key or have a need for more advanced authentication, just contact us on Slack or [email](mailto:support@earthscale.ai), and we will handle it quickly. You can also view your API key under the "**API Settings**" in the user menu. In that menu, you can also restrict which website domains can call the tile servers, so that only your applications can access them.
# Supported Dataset Formats Earthscale supports a wide range of geospatial data formats for both raster and vector datasets. This page provides a complete reference of supported formats, upload methods, and any constraints. ## Raster Formats Raster datasets represent gridded data such as satellite imagery, elevation models, and climate data. | Format | Extensions | Notes | | --------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | GeoTIFF | `.tif`, `.tiff`, `.gtif`, `.gtiff`, `.geotiff` | Standard georeferenced TIFF. Cloud Optimized GeoTIFFs (COGs) are fully supported and recommended for best performance. | | JPEG 2000 | `.jp2` | Wavelet-based compression format commonly used for satellite imagery. | | Zarr | `.zarr` (directory) | Chunked, compressed array format ideal for large multidimensional datasets. Supports Zarr v2 and v3. | ### Cloud Optimized GeoTIFFs (COGs) We recommend using [Cloud Optimized GeoTIFFs](https://www.cogeo.org/) when possible. COGs include internal tiling and overviews that enable efficient streaming directly from cloud storage, resulting in faster visualization and reduced data transfer. ### Multi-File Raster Datasets Earthscale natively supports multi-file raster datasets including: * **Raster mosaics**: Collections of GeoTIFFs covering different spatial tiles or UTM zones * **Time series**: Files representing different timestamps with dates encoded in filenames * **Multi-band collections**: Separate files for each spectral band Use wildcard patterns like `gs://bucket/path/*.tif` to register these collections as a single dataset. See [Raster Mosaic and Time Series Support](/earthscale-documentation/advanced-dataset-configuration) for configuration options. ## Vector Formats Vector datasets represent discrete geographic features such as points, lines, and polygons. | Format | Extensions | Notes | | ---------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | GeoJSON | `.geojson`, `.json` | Standard JSON-based format for vector features. Also supports newline-delimited variants (`.geojsonl`, `.geojsons`). | | FlatGeobuf | `.fgb` | Binary format optimized for streaming and cloud storage. Recommended for large vector datasets. | | GeoParquet | `.parquet`, `.geoparquet` | Column-oriented format with excellent compression. Ideal for large datasets with many attributes. | | Shapefile | `.shp` + `.shx` + `.dbf` (folder) or `.shp.zip` | Legacy format requiring multiple sidecar files. Upload as a folder or zipped archive. | | KML/KMZ | `.kml`, `.kmz` | Google Earth format. KMZ files are compressed KML archives. | | ZIP | `.zip` | Zipped shapefile archives are automatically extracted. | ### Shapefile Requirements Shapefiles consist of multiple files that must be uploaded together: * `.shp` - Feature geometry (required) * `.shx` - Shape index (required) * `.dbf` - Attribute data (required) * `.prj` - Projection definition (recommended) * `.cpg` - Character encoding (optional) Upload shapefiles either as: 1. A **folder** containing all component files 2. A **ZIP archive** with all files at the root level ## Zarr Stores Zarr is a format for chunked, compressed N-dimensional arrays. Earthscale automatically detects Zarr stores by looking for metadata files: * `zarr.json` (Zarr v3) * `.zmetadata` (consolidated metadata) * `.zgroup` or `.zarray` (Zarr v2) Zarr stores can include multiple variables with dimensions like time, x, y, and additional coordinates. Earthscale will automatically infer spatial dimensions and coordinate reference systems. ## Upload Limits Different limits apply depending on your upload method: ### Local File Upload | Constraint | Limit | | ---------------------------- | ----------- | | Maximum files per upload | 1,000 files | | Maximum size per upload | 10 GB | | Maximum individual file size | 10 GB | For larger datasets, use cloud storage and provide the URL directly. ### Cloud Storage | Constraint | Limit | | --------------------------------- | ------------ | | Maximum files for raster mosaics | 15,000 files | | Maximum files for vector datasets | 100 files | | Maximum vector dataset input size | 8 GB | Need to work with larger datasets? [Contact us](mailto:support@earthscale.ai) for enterprise options. ## Cloud Storage Sources Connect datasets directly from your cloud storage: | Provider | URL Format | Example | | -------------------- | -------------------------------------------------------- | -------------------------------------------------------- | | Google Cloud Storage | `gs://bucket/path` | `gs://my-bucket/data/*.tif` | | AWS S3 | `s3://bucket/path` | `s3://my-bucket/imagery/scene.tif` | | Azure Blob Storage | `https://{account}.blob.core.windows.net/container/path` | `https://myaccount.blob.core.windows.net/data/image.tif` | | Google Drive | Shareable link | Single files only | | HTTP/HTTPS | `https://example.com/path` | Public URLs | Wildcard patterns (`*`) are supported for registering multiple files as a single dataset. ## Unsupported Formats The following formats are not yet supported: | Format | Alternative | | ------------------------- | ------------------------------------------------------------------- | | NetCDF (`.nc`, `.nc4`) | Convert to Zarr using `xarray` or to GeoTIFF using `gdal_translate` | | HDF4/HDF5 (`.hdf`, `.h5`) | Convert to Zarr or GeoTIFF | | PMTiles (`.pmtiles`) | Use the source vector data format instead | | GRIB (`.grib`, `.grib2`) | Convert to Zarr or GeoTIFF | ### Converting NetCDF to Zarr ```python import xarray as xr ds = xr.open_dataset("input.nc") ds.to_zarr("output.zarr") ``` ### Converting to Cloud Optimized GeoTIFF This is not required, but may improve rendering speed. ```bash gdal_translate input.tif output.tif -of COG -co COMPRESS=ZSTD ``` ## Next Steps * [Access Your Own Data](/earthscale-documentation/access-your-own-data) - Connect your cloud storage * [Raster Mosaic and Time Series Support](/earthscale-documentation/advanced-dataset-configuration) - Configure multi-file datasets * [Local File Upload](/earthscale-documentation/access-your-own-data/local-file-upload) - Upload from your computer # Raster Mosaic and Time Series Support Earthscale provides native support for tiled, multi-file raster datasets. Some examples of these dataset types: * Each file has a different projection (e.g., UTM zone) * Each file represents a separate band * Each file has a datetime encoded in the filename By "native support", we mean that we can take a collection of these files and *represent them as a single dataset* with multiple bands, projections, and time steps. In our web app, you can then configure multi-band visualizations or toggle through time. And you can use our export functionality to download slices of this data in a single projection. ## ImageDataset Configuration For multi-file GeoTIFF datasets (using wildcard patterns like `gs://bucket/path/*.tif`), the following configuration options are available: ### Filename Date Pattern Extract timestamps from your filenames to enable temporal queries on your dataset. Use [Python strptime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). **Examples:** | Filename Example | Pattern | | ---------------------------------- | ------------------- | | `data_2024-01-15.tif` | `%Y-%m-%d` | | `tile_20240115_v2.tif` | `%Y%m%d` | | `2024/01/15/image.tif` | `%Y/%m/%d/` | | `sentinel_2024-01-15T10:30:00.tif` | `%Y-%m-%dT%H:%M:%S` | **Common format codes:** | Code | Meaning | Example | | ---- | -------------- | ------- | | `%Y` | 4-digit year | 2024 | | `%m` | 2-digit month | 01-12 | | `%d` | 2-digit day | 01-31 | | `%H` | Hour (24-hour) | 00-23 | | `%M` | Minute | 00-59 | | `%S` | Second | 00-59 | | `%j` | Day of year | 001-366 | ### Filename Band Patterns Map filename patterns to band names when your bands are stored in separate files. This is useful when you have files like: * `tile_B02.tif`, `tile_B03.tif`, `tile_B04.tif` * `scene_red.tif`, `scene_green.tif`, `scene_blue.tif` **Configuration format:** For each pattern, specify: 1. **Pattern**: A wildcard pattern including the substring that appears in filenames for that band 2. **Band Name**: The name to assign to that band **Examples:** | Filename Pattern | Band Name | | ---------------- | --------- | | `*_B02*` | `blue` | | `*_B03*` | `green` | | `*_B04*` | `red` | | `*_B08*` | `nir` | Or for descriptive filenames: | Filename Pattern | Band Name | | ---------------- | --------- | | `*_red*` | `red` | | `*_green*` | `green` | | `*_blue*` | `blue` | This can optionally be combined with the filename date pattern argument. # Integrate with Cecil [Cecil](https://cecil.earth) is a data platform that streamlines the process to acquire spatial datasets from leading providers with one contract, one integration, and no minimum usage requirements. Once connected, you can import and use all datasets available in the Cecil platform. ## Prerequisites You'll need a Cecil API key to connect. Follow the instructions in the [Cecil documentation](https://docs.cecil.earth/getting-started) to obtain an API key. ## Connecting to Cecil 1. Click the **user icon** in the top right corner of the Earthscale interface 2. Select **Integrations**
3. Click on **Cecil**
4. Enter an **API Key Name** (this will be visible to anyone in your organization) 5. Enter your **Cecil API Key** 6. Click **Connect to Cecil**
Once connected, Earthscale will automatically set up a webhook to receive notifications when your Cecil subscriptions are updated. ## Syncing Your Subscriptions After connecting, you can sync your existing Cecil subscriptions with Earthscale. This imports each subscription as a dataset in your catalog. 1. In the Cecil integration panel, you'll see the number of subscriptions available to sync 2. Click **Sync Existing Subscriptions** to begin the import process 3. A progress indicator shows how many subscriptions have been registered
You can monitor individual dataset registration progress by clicking **Go to Registrations** or navigating to the Registrations view from the sidebar. The entire process may take a few minutes or longer depending on how many subscriptiosn you have. This process does not copy any data.
{% hint style="info" %} Only raster datasets are currently supported. Vector datasets from Cecil will be skipped during sync. Additionally, some datasets contain variables not yet supported by Earthscale. {% endhint %} ## Automatic Updates Once connected, Earthscale automatically handles updates to your Cecil data: * **New subscriptions** are automatically registered as datasets when you subscribe to new data in Cecil * **Data updates** trigger updates in Earthscale when new data is delivered to existing subscriptions ## Finding Cecil Datasets in the Catalog Switch to the *Catalog* view in the topbar to see your datasets. ### Quick Filter When connected to Cecil, a Cecil icon appears in the catalog header. Click it to toggle filtering to show only Cecil datasets. ### Tag-Based Search
Each Cecil dataset is tagged with metadata that you can use to search and filter: | Tag | Description | | ----------------------- | ----------------------------- | | `cecil.dataset.name` | The name of the Cecil dataset | | `cecil.aoi.id` | Area of Interest ID | | `cecil.subscription.id` | Subscription ID | | `cecil.category` | Dataset category | | `cecil.provider.name` | Data provider name | You can search by these tags in the catalog search bar, or click on a tag displayed on a dataset card to filter by that value. ## Working with Cecil Data Once your Cecil datasets are in Earthscale, you can work with them like any other dataset: ### Adding to the Map Click the **Add to map** button on any Cecil dataset card in the catalog to add it to your current map. You can combine Cecil data with: * Other Cecil subscriptions * Your own uploaded geospatial data * Datasets from the Earthscale public catalog ### Inspecting Data Click anywhere on the map to inspect pixel values at that location. ### Editing Visualizations Customize how your data appears on the map: 1. Click the **three dots menu** on a dataset card and select **Edit Visualization**, or click directly on the visualization preview 2. Adjust settings like: * Band selection * Color ramp * Min/max values * Opacity 3. Changes are applied in real-time ### Choosing Data Variables to Display Many Cecil datasets contain multiple data variables (bands) that you can visualize. When editing visualizations, you can select which variable to display: * **Single-band visualization**: Choose one variable to display as a color-mapped layer * **RGB visualization**: Select three variables to combine into a true-color or false-color composite * **Categorical variables**: Some variables (like land cover classifications) use predefined color schemes based on their raster attribute tables The visualization editor shows all available variables for each dataset. ### Legend Toggle the legend visibility using the legend button in the top of the map sidebar to see color scales and value ranges for your visible datasets. ## Sharing Your Map Share maps containing Cecil data just like any other Earthscale map: 1. Click the **Share** button in the top bar 2. Choose your sharing options (public read-only link, or internal to your organization) 3. Recipients with appropriate permissions can view your map with all Cecil datasets included ## Managing Your Connection ### Replace API Key If you need to update your Cecil API key: 1. Open the Cecil integration panel 2. Click **Replace API Key** 3. Enter the new key name and API key 4. Click **Update API Key** ### Disconnect To remove the Cecil integration: 1. Open the Cecil integration panel 2. Click **Disconnect** 3. Confirm the disconnection {% hint style="warning" %} Disconnecting will remove Earthscale's access to your Cecil account. Existing datasets synced from Cecil will no longer be accessible in Earthscale. {% endhint %} # Creating Sentinel-2 Cloud-Free Composites This guide shows how to create cloud-free composites from Sentinel-2 exports using the Scene Classification Layer (SCL) band for cloud masking. > **Prerequisites**: First, make sure to export your Sentinel-2 data from the **Export** tab in Earthscale. Your export must include the **SCL** band. When exporting Sentinel-2 data from Earthscale, make sure to select SCL alongside your spectral bands (e.g., B02, B03, B04). ## Unzipping the Export After downloading your export, unzip it: ```bash unzip Export_Dec_18_2025_04_49_PM.zip cd Export_Dec_18_2025_04_49_PM ``` Inside, you'll find a directory named after your dataset and export timestamp, containing individual GeoTIFF files: ``` Sentinel-2_L2A_Dec_18_2025_04_47_PM/ time-20251122T105401_B02.tif time-20251122T105401_B03.tif time-20251122T105401_B04.tif time-20251122T105401_SCL.tif time-20251125T105259_B02.tif time-20251125T105259_B03.tif time-20251125T105259_B04.tif time-20251125T105259_SCL.tif ``` Files follow the naming pattern: `time-{datetime}_{band}.tif` ## Understanding the SCL Band The Scene Classification Layer (SCL) classifies each pixel. For cloud-free composites, we typically use pixels classified as: | Value | Classification | | ----- | -------------- | | 4 | Vegetation | | 5 | Bare Soil | | 6 | Water | These represent clear (non-cloudy) observations. Other values include clouds, cloud shadows, snow, etc. ## Option 1: Python with Rasterio This script auto-detects bands from your export directory and creates cloud-free median composites: ```python #!/usr/bin/env python3 """ Create cloud-free composites from Sentinel-2 exports using SCL band. Usage: python cloud_free_composite.py /path/to/export/directory """ import sys import re from pathlib import Path from collections import defaultdict import numpy as np import rasterio from rasterio.enums import Resampling def find_files(export_dir: Path) -> dict[str, dict[str, Path]]: """ Discover all timesteps and bands in the export directory. Returns: {timestamp: {band: filepath}} """ pattern = re.compile(r"time-([0-9T]+)_(.+)\.tif$") files = defaultdict(dict) for tif in export_dir.glob("*.tif"): match = pattern.match(tif.name) if match: timestamp, band = match.groups() files[timestamp][band] = tif return dict(files) def create_cloud_mask(scl_data: np.ndarray) -> np.ndarray: """ Create a boolean mask where True = clear pixel. Clear pixels are SCL values 4 (vegetation), 5 (bare soil), 6 (water). """ return np.isin(scl_data, [4, 5, 6]) def create_composite( export_dir: Path, output_dir: Path, method: str = "median" ) -> list[Path]: """ Create cloud-free composites for all bands found in the export. Args: export_dir: Path to the export directory containing TIF files output_dir: Path to save composite TIFs method: Compositing method - "median" or "first" (first clear pixel) Returns: List of created composite file paths """ output_dir.mkdir(parents=True, exist_ok=True) # Discover files files_by_time = find_files(export_dir) if not files_by_time: raise ValueError(f"No TIF files found in {export_dir}") timestamps = sorted(files_by_time.keys()) print(f"Found {len(timestamps)} timesteps") # Get all bands (excluding SCL) all_bands = set() for bands in files_by_time.values(): all_bands.update(b for b in bands.keys() if b != "SCL") all_bands = sorted(all_bands) print(f"Found bands: {all_bands}") # Check that SCL exists for all timesteps for ts in timestamps: if "SCL" not in files_by_time[ts]: raise ValueError(f"Missing SCL band for timestep {ts}") # Read reference file for metadata ref_file = next(iter(next(iter(files_by_time.values())).values())) with rasterio.open(ref_file) as src: profile = src.profile.copy() height, width = src.height, src.width created_files = [] # Process each band for band in all_bands: print(f"Processing {band}...") # Stack all timesteps for this band stack = [] masks = [] for ts in timestamps: if band not in files_by_time[ts]: print(f" Warning: {band} missing for {ts}, skipping") continue # Read band data with rasterio.open(files_by_time[ts][band]) as src: data = src.read(1) # Read corresponding SCL with rasterio.open(files_by_time[ts]["SCL"]) as src: scl = src.read(1) clear_mask = create_cloud_mask(scl) stack.append(data) masks.append(clear_mask) if not stack: print(f" No data found for {band}, skipping") continue # Stack arrays stack = np.array(stack) masks = np.array(masks) # Apply cloud mask - set cloudy pixels to NaN for median calculation masked_stack = stack.astype(np.float32) masked_stack[~masks] = np.nan # Compute composite if method == "median": with np.errstate(all='ignore'): composite = np.nanmedian(masked_stack, axis=0) elif method == "first": # First valid (clear) pixel composite = np.full((height, width), np.nan, dtype=np.float32) for i in range(len(stack)): valid = masks[i] & np.isnan(composite) composite[valid] = stack[i][valid] else: raise ValueError(f"Unknown method: {method}") # Handle remaining NaN (no clear observations) composite = np.nan_to_num(composite, nan=0).astype(profile['dtype']) # Write output output_path = output_dir / f"composite_{band}.tif" profile.update(count=1, compress='deflate') with rasterio.open(output_path, 'w', **profile) as dst: dst.write(composite, 1) created_files.append(output_path) print(f" Saved {output_path}") return created_files def create_rgb_composite( output_dir: Path, red_band: str = "B04", green_band: str = "B03", blue_band: str = "B02" ) -> Path | None: """ Create an RGB GeoTIFF from individual band composites. """ red_path = output_dir / f"composite_{red_band}.tif" green_path = output_dir / f"composite_{green_band}.tif" blue_path = output_dir / f"composite_{blue_band}.tif" if not all(p.exists() for p in [red_path, green_path, blue_path]): print("RGB bands not all present, skipping RGB composite") return None with rasterio.open(red_path) as src: red = src.read(1) profile = src.profile.copy() with rasterio.open(green_path) as src: green = src.read(1) with rasterio.open(blue_path) as src: blue = src.read(1) rgb_path = output_dir / "composite_RGB.tif" profile.update(count=3, compress='deflate') with rasterio.open(rgb_path, 'w', **profile) as dst: dst.write(red, 1) dst.write(green, 2) dst.write(blue, 3) print(f"Saved RGB composite: {rgb_path}") return rgb_path if __name__ == "__main__": if len(sys.argv) < 2: print("Usage: python cloud_free_composite.py [output_directory]") print("Example: python cloud_free_composite.py ./Sentinel-2_L2A_Dec_18_2025_04_47_PM") sys.exit(1) export_dir = Path(sys.argv[1]) output_dir = Path(sys.argv[2]) if len(sys.argv) > 2 else export_dir / "composites" if not export_dir.exists(): print(f"Error: Directory not found: {export_dir}") sys.exit(1) print(f"Creating cloud-free composites from: {export_dir}") print(f"Output directory: {output_dir}") print() created = create_composite(export_dir, output_dir, method="median") print() # Create RGB if we have the standard bands create_rgb_composite(output_dir) print() print(f"Done! Created {len(created)} composite files in {output_dir}") ``` ### Running the Script ```bash # Install dependencies pip install rasterio numpy # Run on your export python cloud_free_composite.py ./Sentinel-2_L2A_Dec_18_2025_04_47_PM # Or specify a custom output directory python cloud_free_composite.py ./Sentinel-2_L2A_Dec_18_2025_04_47_PM ./my_composites ``` ## Option 2: GDAL Command Line For a simpler approach using GDAL tools, here's a bash script: ```bash #!/bin/bash # Cloud-free composite using GDAL # Usage: ./gdal_composite.sh /path/to/export/directory set -e EXPORT_DIR="${1:-.}" OUTPUT_DIR="${2:-${EXPORT_DIR}/composites}" mkdir -p "$OUTPUT_DIR" echo "Processing files in: $EXPORT_DIR" echo "Output directory: $OUTPUT_DIR" # Find all unique bands (excluding SCL) BANDS=$(ls "$EXPORT_DIR"/time-*_*.tif 2>/dev/null | \ sed 's/.*_\([^_]*\)\.tif/\1/' | \ sort -u | \ grep -v SCL) echo "Found bands: $BANDS" # Find all timestamps TIMESTAMPS=$(ls "$EXPORT_DIR"/time-*_*.tif 2>/dev/null | \ sed 's/.*time-\([0-9T]*\)_.*/\1/' | \ sort -u) echo "Found $(echo "$TIMESTAMPS" | wc -w | tr -d ' ') timesteps" echo for BAND in $BANDS; do echo "Processing $BAND..." MASKED_FILES="" for TS in $TIMESTAMPS; do BAND_FILE="$EXPORT_DIR/time-${TS}_${BAND}.tif" SCL_FILE="$EXPORT_DIR/time-${TS}_SCL.tif" MASKED_FILE="$OUTPUT_DIR/masked_${TS}_${BAND}.tif" if [[ -f "$BAND_FILE" && -f "$SCL_FILE" ]]; then # Apply cloud mask: keep pixels where SCL is 4, 5, or 6 gdal_calc.py \ -A "$BAND_FILE" \ -B "$SCL_FILE" \ --outfile="$MASKED_FILE" \ --calc="numpy.where((B==4)|(B==5)|(B==6), A, 0)" \ --type=UInt16 \ --NoDataValue=0 \ --quiet MASKED_FILES="$MASKED_FILES $MASKED_FILE" fi done # Create VRT stack of all masked files VRT_FILE="$OUTPUT_DIR/stack_${BAND}.vrt" gdalbuildvrt -separate "$VRT_FILE" $MASKED_FILES # Compute median composite using gdal_calc with the stack # Note: For true median, we use a Python approach. # This creates a maximum composite (last clear pixel wins) COMPOSITE_FILE="$OUTPUT_DIR/composite_${BAND}.tif" # Simple approach: use gdal_merge to combine (uses last valid value) gdal_merge.py \ -o "$COMPOSITE_FILE" \ -n 0 \ -a_nodata 0 \ -co COMPRESS=DEFLATE \ $MASKED_FILES # Cleanup temp files rm -f $MASKED_FILES "$VRT_FILE" echo " Created: $COMPOSITE_FILE" done # Create RGB composite if we have B04, B03, B02 if [[ -f "$OUTPUT_DIR/composite_B04.tif" && \ -f "$OUTPUT_DIR/composite_B03.tif" && \ -f "$OUTPUT_DIR/composite_B02.tif" ]]; then echo echo "Creating RGB composite..." gdal_merge.py \ -o "$OUTPUT_DIR/composite_RGB.tif" \ -separate \ -co COMPRESS=DEFLATE \ "$OUTPUT_DIR/composite_B04.tif" \ "$OUTPUT_DIR/composite_B03.tif" \ "$OUTPUT_DIR/composite_B02.tif" echo " Created: $OUTPUT_DIR/composite_RGB.tif" fi echo echo "Done! Composites saved to: $OUTPUT_DIR" ``` ### Running the GDAL Script ```bash # Make it executable chmod +x gdal_composite.sh # Run on your export ./gdal_composite.sh ./Sentinel-2_L2A_Dec_18_2025_04_47_PM ``` > **Note**: The GDAL script creates a "last valid pixel" composite rather than a true median. For median composites, use the Python script above. ## Output Files Both methods create: * `composite_B02.tif` - Blue band composite * `composite_B03.tif` - Green band composite * `composite_B04.tif` - Red band composite * `composite_RGB.tif` - 3-band RGB GeoTIFF (if B02, B03, B04 are present) The output files maintain the same CRS, resolution, and extent as your input export. You can directly drag and drop to upload these files back into Earthscale for sharing or analysis. Or, you can pull them into software like QGIS and ArcGIS for further analysis. # Access Vantor (Maxar) Open Data Visualize and download imagery from Maxar Open Data program Earthscale makes it easy to access data from Vantor's (formerly Maxar) [Open Data Program](https://vantor.com/company/open-data-program/). This program provides high-resolution satellite imagery captured before and after humanitarian crises, with a focus on disaster response. With Earthscale you can: * Visualize this data alongside other datasets in your catalog * Reproject imagery to align with your desired coordinate system and pixel grid * Export only the data you need to your local machine ## Exploring available data You can browse available datasets through Maxar's [STAC catalog](https://radiantearth.github.io/stac-browser/#/external/maxar-opendata.s3.dualstack.us-west-2.amazonaws.com/events/catalog.json?.language=en). The data is hosted on the AWS [Registry of Open Data](https://registry.opendata.aws/maxar-open-data/). To explore what's available using the AWS CLI: ``` aws s3 ls --no-sign-request s3://maxar-opendata/ ``` ## Understanding the file structure Files are organized in this pattern: ``` s3://maxar-opendata/events/{EVENT}/ard/{ZOOM}/{TILE_COORDS}/{DATE}/{SCENE_ID}-{PRODUCT}.tif ``` For example: ``` s3://maxar-opendata/events/HurricaneHelene-Oct24/ard/17/031311010113/2024-10-06/104001009C0CE600-visual.tif ``` Where: * `HurricaneHelene-Oct24` - Event collection name * `ard` - Analysis-Ready Data (pre-processed) * `17` - Web Mercator zoom level (higher = more detail, smaller coverage) * `031311010113` - Slippy map tile coordinates at zoom 17 * `2024-10-06` - Image acquisition date * `104001009C0CE600-visual.tif` - Scene ID + product type **Available product types:** * `-visual.tif` - RGB composite (recommended for visualization) * `-ms.tif` - Multispectral imagery (RGB + NIR bands) * `-pan.tif` - Panchromatic (high-resolution grayscale) * `-cloud-mask.gpkg` - Cloud locations as vector polygons ## Adding the data to Earthscale This example shows how to add RGB imagery from Hurricane Helene (October 2024). The result will be a raster mosaic time series that stitches together tiles across multiple acquisitions. **Steps:** 1. In Earthscale, click **Add New Dataset** and select the **Cloud Source** tab 2. Paste a URL pattern using wildcards to match all files: ``` s3://maxar-opendata/events/HurricaneHelene-Oct24/ard/17/*/*/*-visual.tif ``` 3. Wait a few seconds while Earthscale scans the files 4. Rename the dataset to something meaningful (e.g., "Hurricane Helene") 5. Expand the **Filename Date Pattern** option and set it to: `%Y-%m-%d` This tells Earthscale that dates in the file path follow the pattern `YYYY-MM-DD` 6. Click to register the dataset. It may take a minute to parse through the files. The dataset will appear on your map. Zoom in to view the imagery. Note that coverage varies by location and date. {% hint style="info" %} For multispectral data (`-ms.tif`), before and after imagery may come from different sensors. If sensor consistency matters for your analysis, load acquisitions as separate datasets. {% endhint %} Once it finishes, the dataset should appear on your map. Zoom in to view the data. Note that not all areas have data for all times. ## Exporting the data 1. Select the **Export** tab in the top bar 2. Define your area of interest (AOI) by either: * Drawing a bounding box on the map * Selecting bounds from an uploaded vector dataset (e.g., administrative boundaries) 3. Adjust the bounding box size or resolution if needed to meet your account tier's export size limits 4. Configure export settings: * Spatial resolution * Coordinate reference system (CRS) * Optional: Align to match an existing dataset in your catalog (simplifies downstream analysis) 5. Click the export button and wait for processing to complete 6. Download your cloud-optimized GeoTIFFs as a zip file ## License This data is provided under **Creative Commons Attribution-NonCommercial 4.0 (CC BY-NC 4.0)**. **You must:** * Provide attribution to Maxar with a link to their license * Use the data only for non-commercial purposes **You cannot:** * Use this data for commercial purposes * Redistribute it through commercial platforms or services For commercial use cases, contact Maxar directly about licensing options. # Get Started with the Python API ### Prerequisites * An Earthscale account. Please reach out to 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) 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= export EARTHSCALE_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 ```
Output ```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 } ```
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) 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 ```
Output ```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" } ] ```
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) # Python API Reference ## Earthscale Python API Documentation This file is not currently published. It just exists to silence the Sphinx warning about documents not being included in any toctree. ## Contents: * [`EarthscaleClient`](/python-api/python-api-reference/client) * [Models](/python-api/python-api-reference/models) * [Exceptions](/python-api/python-api-reference/exceptions) # EarthscaleClient Client for the Earthscale API. Can be used to add, list, and retrieve datasets. {% hint style="info" %} 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. {% endhint %} ### Examples Usage with environment variables: ```python import os from earthscale import EarthscaleClient os.environ["EARTHSCALE_EMAIL"] = "service@example.com" os.environ["EARTHSCALE_PASSWORD"] = "service_password" with EarthscaleClient() as client: client.list_datasets() ``` ## \_\_init\_\_ ```python __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 . | None | | auth\_url | str \| None | Custom URL for the authentication service. Defaults to . | None | | anon\_key | str \| None | Custom anon key for the authentication service. If not set, the client will use the default anon key for . | 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 ```python login() → None ``` Login using service account credentials from environment variables, or OAuth authentication if no environment variables are set. ### Raises [**AuthenticationError**](https://docs.earthscale.ai/python-api/python-api-reference/pages/oRfJmdUCZKQG9jfBzy8T#earthscale.authenticationerror) – If authentication fails. ### Return type `None` ## add\_image\_dataset ```python add_image_dataset( name: str, url: str | list[str], labels: list[DatasetLabel] | None = None, tags: dict[str, str] | 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: ```python 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. User-defined labels as key-value pairs. Deprecated, use tags instead. If only labels are provided, a warning will be logged and the labels will be converted to tags. If both labels and tags are provided, tags will take precedence. | None | | tags | dict\[str, str] \| None | Optional. User-defined tags 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. \[{"pattern": "\*\_B\[0-9]", "band": "band\_1"}] would map all files matching the pattern \*\_B\[0-9] to the band name band\_1. Uses Unix filename pattern rules (fnmatch).If specified, all files must match to some pattern, otherwise an error will be raised. | 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`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.adddatasetresponse) ### Returns The dataset response. ## add\_zarr\_dataset ```python add_zarr_dataset( name: str, url: str, labels: list[DatasetLabel] | None = None, tags: dict[str, str] | 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. Deprecated, use tags instead. If only labels are provided, a warning will be logged and the labels will be converted to tags. If both labels and tags are provided, tags will take precedence. | None | | tags | dict\[str, str] \| None | Optional. User-defined tags 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`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.adddatasetresponse) ### Returns The dataset response. ## add\_vector\_dataset ```python add_vector_dataset( name: str, url: str, labels: list[DatasetLabel] | None = None, tags: dict[str, str] | None = None, coordinate_precision: Literal['auto', '1250m', '600m', '300m', '150m', '80m', '40m', '20m', '10m', '5m', '2m', '1m', '50cm', '25cm', '15cm', '8cm'] = 'auto' ) → 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. User-defined labels as key-value pairs. Deprecated, use tags instead. If only labels are provided, a warning will be logged and the labels will be converted to tags. If both labels and tags are provided, tags will take precedence. | None | | tags | dict\[str, str] \| None | Optional. User-defined tags as key-value pairs. | None | | coordinate\_precision | Literal\['auto', '1250m', '600m', '300m', '150m', '80m', '40m', '20m', '10m', '5m', '2m', '1m', '50cm', '25cm', '15cm', '8cm'] | Controls the approximate precision of coordinates in the optimized dataset. ‘auto’ tries to detect an appropriate precision. Other values specify the desired coordinate precision explicitly. Defaults to ‘auto’. | 'auto' | ### Return type [`AddDatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.adddatasetresponse) ### Returns The dataset response. ## add\_tile\_server\_dataset ```python add_tile_server_dataset( name: str, url: str, labels: list[DatasetLabel] | None = None, tags: dict[str, str] | 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. User-defined labels as key-value pairs. Deprecated, use tags instead. If only labels are provided, a warning will be logged and the labels will be converted to tags. If both labels and tags are provided, tags will take precedence. | None | | tags | dict\[str, str] \| None | Optional. User-defined tags as key-value pairs. | None | ### Return type [`AddDatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.adddatasetresponse) ### Returns The dataset response. ## list\_datasets ```python list_datasets( *, name: str | None = None, tags: dict[str, str] | None = None, bbox: tuple[float, float, float, float] | None = None, created_after: datetime | None = None, created_before: datetime | None = None, limit: int | None = None ) → list[ListDatasetResponse] ``` List datasets with optional filtering. Returns up to `limit` datasets in a single request. For iterating over all matching datasets use [`iter_datasets()`](#earthscale.EarthscaleClient.iter_datasets) instead. All filters are combined with AND logic. When multiple tags are given, only datasets matching **all** of them are returned. ### Parameters | Name | Type | Description | Default | | --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | name | str \| None | Case-insensitive substring search on dataset name. For example, name="Zarr" matches “Zarr 1 Band” and “HLS Zarr”. | None | | tags | dict\[str, str] \| None | Filter by tags (AND logic). Only datasets that have all specified key-value pairs are returned. Example: {"source": "satellite", "resolution": "10m"}. | None | | bbox | tuple\[float, float, float, float] \| None | Bounding box filter as (min\_lon, min\_lat, max\_lon, max\_lat) in EPSG:4326. Only datasets whose extent intersects the box are returned. For a point query, use the same value for min and max. | None | | created\_after | datetime \| None | Only return datasets created after this timestamp. | None | | created\_before | datetime \| None | Only return datasets created before this timestamp. | None | | limit | int \| None | Maximum number of results (default 100, max 1000). | None | ### Return type `list`\[[`ListDatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.listdatasetresponse)] ### Returns A list of datasets matching the filters. ### Raises **ValueError** – If `limit` is not between 1 and 1000. ### Examples ```python from earthscale import EarthscaleClient with EarthscaleClient() as client: # Search by name and tags datasets = client.list_datasets( name="Zarr", tags={"source": "satellite", "resolution": "10m"}, ) # Filter by bounding box (Brazil) datasets = client.list_datasets(bbox=(-60, -6, -59, -4)) ``` ## iter\_datasets ```python iter_datasets( *, name: str | None = None, tags: dict[str, str] | None = None, bbox: tuple[float, float, float, float] | None = None, created_after: datetime | None = None, created_before: datetime | None = None, page_size: int = 100 ) → Iterator[ListDatasetResponse] ``` Iterate over all matching datasets with automatic pagination. Yields datasets one at a time, transparently fetching successive pages using cursor-based pagination. This is the recommended way to retrieve large or unbounded result sets. All filters are combined with AND logic. When multiple tags are given, only datasets matching **all** of them are returned. ### Parameters | Name | Type | Description | Default | | --------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | name | str \| None | Case-insensitive substring search on dataset name. For example, name="Zarr" matches “Zarr 1 Band” and “HLS Zarr”. | None | | tags | dict\[str, str] \| None | Filter by tags (AND logic). Only datasets that have all specified key-value pairs are returned. Example: {"source": "satellite", "resolution": "10m"}. | None | | bbox | tuple\[float, float, float, float] \| None | Bounding box filter as (min\_lon, min\_lat, max\_lon, max\_lat) in EPSG:4326. Only datasets whose extent intersects the box are returned. For a point query, use the same value for min and max. | None | | created\_after | datetime \| None | Only return datasets created after this timestamp. | None | | created\_before | datetime \| None | Only return datasets created before this timestamp. | None | | page\_size | int | Number of datasets to fetch per request (max 1000). | 100 | ### Yields [`ListDatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.listdatasetresponse) for each matching dataset. ### Raises **ValueError** – If `page_size` is not between 1 and 1000. ### Examples ```python from earthscale import EarthscaleClient with EarthscaleClient() as client: for ds in client.iter_datasets( tags={"source": "satellite"}, bbox=(-60, -6, -59, -4), ): print(ds.name, ds.tags) ``` ## get\_dataset ```python get_dataset( dataset_id: str | UUID ) → DatasetResponse ``` Get the latest version of a dataset by dataset ID. ### Parameters ### Return type [`DatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.datasetresponse) ### Returns The dataset response. ## get\_dataset\_version\_by\_id ```python get_dataset_version_by_id( version_id: str | UUID ) → DatasetResponse ``` Get a dataset version by version ID. ### Parameters ### Return type [`DatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.datasetresponse) ### Returns The dataset response. ## delete\_dataset ```python delete_dataset( dataset_id: str | UUID, remove_from_maps: bool = True ) → DeleteDatasetResponse ``` Soft-delete a dataset. Deletion works by creating a new dataset version that marks the dataset as deleted. This hides the dataset from the catalog and listing APIs, but tiling requests for existing versions are still accepted. Optionally removes the dataset from all maps. Both dataset IDs and dataset version IDs are accepted — it does not matter which is passed, the entire dataset is deleted either way. ### Parameters | Name | Type | Description | Default | | ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | dataset\_id | str \| UUID | The dataset ID or dataset version ID. Either can be used to identify the dataset — the entire dataset is always deleted, not just a single version. | | | remove\_from\_maps | bool | Whether to remove the dataset from all maps. Defaults to True. | True | ### Return type [`DeleteDatasetResponse`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.deletedatasetresponse) ### Returns Response containing the dataset ID and the ID of the newly created deletion marker version. ## check\_api\_support ```python 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`](https://docs.earthscale.ai/python-api/python-api-reference/pages/ZCkKsG47eGBBKQcgTSxH#earthscale.versioncheckresponse) ### Returns The version check response from the server. ### Raises [**VersionIncompatibleError**](https://docs.earthscale.ai/python-api/python-api-reference/pages/oRfJmdUCZKQG9jfBzy8T#earthscale.versionincompatibleerror) – If the API version is not supported by the server. # Models ## Requests ### AddImageDatasetRequest Request to add an image dataset #### type: Literal\['image'] #### urls: list\[str] #### bands: list\[str] | None #### groupby: str | None 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 #### filename\_band\_pattern: list\[FilenameBandPattern] | None #### labels: list\[DatasetLabel] | None 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 Request to add a vector dataset #### type: Literal\['vector'] #### url: str #### coordinate\_precision: Literal\['auto', '1250m', '600m', '300m', '150m', '80m', '40m', '20m', '10m', '5m', '2m', '1m', '50cm', '25cm', '15cm', '8cm'] #### labels: list\[DatasetLabel] | None 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 Request to add a Zarr dataset #### type: Literal\['zarr'] #### urls: list\[str] #### rename: dict\[str, str] | None #### check\_only\_one\_url\_for\_now ```python check_only_one_url_for_now() → AddZarrDatasetRequest ``` **Return type** [`AddZarrDatasetRequest`](#earthscale.AddZarrDatasetRequest) #### labels: list\[DatasetLabel] | None 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 #### type: Literal\['tileserver'] #### url: str #### labels: list\[DatasetLabel] | None 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 alias of [`AddImageDatasetRequest`](#earthscale.AddImageDatasetRequest) | [`AddZarrDatasetRequest`](#earthscale.AddZarrDatasetRequest) | [`AddVectorDatasetRequest`](#earthscale.AddVectorDatasetRequest) | [`AddTileServerDatasetRequest`](#earthscale.AddTileServerDatasetRequest) ## Responses ### AddDatasetResponse #### dataset\_id: UUID Dataset ID of the newly created dataset version #### dataset\_version\_id: UUID Dataset Version ID of the newly created dataset version ### DeleteDatasetResponse #### dataset\_id: UUID Dataset ID of the deleted dataset #### dataset\_version\_id: UUID Dataset Version ID of the deletion marker version ### DatasetResponse #### dataset\_id: UUID Dataset ID of the dataset #### dataset\_version\_id: UUID ID for the current version of the dataset #### name: str Name of the dataset #### type: DatasetType Type of the dataset, either raster or vector #### labels: list\[DatasetLabel] User-defined labels for the dataset. Superseded by tags. **Type** Deprecated #### tags: dict\[str, str] User-defined tags for the dataset #### variables: dict\[str, Variable] Estimated statistics for each variable in the dataset, useful for visualization #### created\_at: AwareDatetime Timestamp of when the dataset was created #### visualization\_optimization: Optimization Status of the visualization optimization for faster visualization #### pixel\_info\_optimizations: dict\[str, Optimization] Status of the pixel info optimizations for faster pixel info retrieval #### dynamic\_tile\_server: TileServer Dynamic tile server for fast visualization #### optimized\_tile\_server: TileServer | None Optimized tile server for fast visualization ### ListDatasetResponse Single entry in the list of datasets with a subset of information #### dataset\_id: UUID Dataset ID of the dataset #### dataset\_version\_id: UUID ID for the current version of the dataset #### name: str Name of the dataset #### type: DatasetType Type of the dataset, either raster or vector #### labels: list\[DatasetLabel] User-defined labels for the dataset. Superseded by tags. **Type** Deprecated #### tags: dict\[str, str] User-defined tags for the dataset #### created\_at: AwareDatetime Timestamp of when the dataset was created #### updated\_at: AwareDatetime Timestamp of when the dataset was last updated ### PaginatedListDatasetResponse Paginated list of datasets with cursor-based pagination #### data: list\[ListDatasetResponse] List of datasets #### next\_cursor: str | None Opaque cursor token for fetching the next page ### VersionCheckResponse #### is\_supported: bool #### newest\_supported\_version: int #### is\_deprecated: bool #### will\_be\_removed\_after: date | None #### deprecation\_message: str | None ## Other Models ### DatasetType #### RASTER = 'raster' #### VECTOR = 'vector' ### DatasetLabel User-defined label for a dataset #### name: str Name of the label. Can be any string. #### value: str Value of the label. Can be any string. ### SimpleDatasetMetadata Simplified metadata with only essential fields #### description: str | None #### thumbnail\_url: str | None #### attributes: list\[DatasetLabel] #### license: str | None ### FilenameBandPattern Pattern for mapping filename patterns to band names #### pattern: str #### band: str | None #### band\_mapping: dict\[int, str] | None ### DatasetOverviewsStatus #### status: str 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 Timestamp of the last update to the status ### OptimizationStatus alias of `Literal`\[‘not\_started’, ‘pending’, ‘running’, ‘success’, ‘error’] ### Optimization #### status: Literal\['not\_started', 'pending', 'running', 'success', 'error'] 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 Timestamp of the last update to the status ### TileServer #### tile\_url: str Tileserver URL to be used in an application #### pixel\_url: str Pixel info URL to be used in an application #### min\_zoom: int Minimum zoom level supported by the tile server #### max\_zoom: int Maximum zoom level supported by the tile server ### Variable Estimated statistics for a variable in the dataset, useful for visualization #### sampled\_min: float Estimated minimum value in the dataset #### sampled\_max: float Estimated maximum value in the dataset # Exceptions ## EarthscaleClientError Base exception for Earthscale client errors. This is the base class for all exceptions raised by the Earthscale client. All other client exceptions inherit from this class. ### \_\_init\_\_ ```python __init__( message: str, error_class: str | None = None ) ``` ## VersionIncompatibleError Raised when the client version is incompatible with the server. This exception is raised when the client’s API version is not supported by the server, indicating that the client needs to be updated. ## NotFoundError Raised when a resource is not found. This exception is raised when the client requests a resource that does not exist, such as a dataset with a non-existent ID. ## ValidationFailedError Raised when validation fails. This exception is raised when the client or server validation fails, such as when invalid parameters are provided to an API endpoint. ## AuthenticationError Raised when authentication fails. This exception is raised when the client cannot authenticate with the Earthscale API, such as when invalid credentials are provided or when the refresh token has expired. ## TokenRefreshRequired Raised when a token refresh is required. This exception is raised when the authentication token has expired and needs to be refreshed before making further API requests. # Changelog All notable changes to the `earthscale` client package are documented here. ## 0.16.0 ### New Features * **Dataset listing now supports filtering.** `list_datasets()` accepts `name`, `tags`, `bbox`, `created_after`, `created_before`, and `limit` parameters to narrow results. All filters use AND logic. * **New `iter_datasets()` method** for iterating over large result sets with automatic cursor-based pagination. This is the recommended way to list datasets. * **New `PaginatedListDatasetResponse` model** for cursor-based pagination, exposed at the top level. ### Changes * `ListDatasetResponse` now includes an `updated_at` field. * `list_datasets(limit=...)` and `iter_datasets(page_size=...)` now raise `ValueError` if the value is outside the 1–1000 range. ### Fixes * Fixed `ListDatasetResponse.tags` docstring (was incorrectly labeled as "labels"). ## 0.15.1 ### New Features * Support `tags` on datasets as key-value pairs, deprecating `labels`. * Add `AddDatasetRequest.tags` field; `labels` is now deprecated. * Add `AddDatasetResponse.dataset_version_id` field. * Pretty-print client models using JSON in IPython environments. ### Fixes * Fix type handling in client for doc generation. * Nicer error handling for forbidden errors. ## 0.15.0 ### New Features * OAuth login flow with auto-detected free port. * Log which servers are used on client init. ### Fixes * Fix a type warning in the CLI. ## 0.14.2 ### New Features * Add `pixel_info_url` to `TileServer` response. ### Fixes * Correctly pass in credentials file. ## 0.14.0 ### New Features * Add proxy support in client. ### Changes * Improve client docstrings. # Earthscale HTTP API This is the API that can be used to add and list datasets. We recommend to use the [Python API](/python-api/getting-started) for this, since it makes it easier to authenticate. If you need help with using the HTTP API directly, please contact . Dataset responses from this API return the URLs of the tilers that can be used to retrieve raster tiles or pixel information. The available tilers depend on the dataset type and whether or not the dataset has been accelerated already: * The [dynamic tiler](/http-api/dynamic-tiler-http-api) works for any dataset. * Performance depends on the source data structure * The [fast tiler](/http-api/fast-tiler-http-api) is only available for accelerated (pre-processed) datasets * Always high-performance Both of these tilers use API keys to authenticate, so they are easy to integrate into your applications. The easiest way to obtain URLs for them is from the Earthscale web application (see [Use Earthscale in Your Products](/earthscale-documentation/use-earthscale-in-your-products)) # Authentication The API uses Supabase JWT Bearer Authentication. All endpoints require a valid authentication token to be included in the request headers. # Dataset Types * *Image Dataset*: Raster data from image files, e.g. GeoTIFF or COG * *Zarr Dataset*: Multi-dimensional arrays stored in Zarr format * *Vector Dataset*: Geospatial vector data * *Tile Server Dataset*: Pre-tiled raster data from tile servers # Datasets ## List Datasets > List datasets with optional filtering.\ > \ > Returns a flat list of datasets with offset-based pagination.\ > For iterating over large or unbounded result sets, prefer\ > \`\`GET /v1/datasets/cursor\`\` which uses cursor-based pagination\ > and guarantees stable ordering across pages.\ > \ > All filters are combined with AND logic. When multiple tags are\ > specified, only datasets matching \*\*all\*\* of them are returned. ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/datasets":{"get":{"tags":["Datasets","Datasets"],"summary":"List Datasets","description":"List datasets with optional filtering.\n\nReturns a flat list of datasets with offset-based pagination.\nFor iterating over large or unbounded result sets, prefer\n``GET /v1/datasets/cursor`` which uses cursor-based pagination\nand guarantees stable ordering across pages.\n\nAll filters are combined with AND logic. When multiple tags are\nspecified, only datasets matching **all** of them are returned.","operationId":"List_datasets_datasets_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring search on dataset name.","title":"Name"},"description":"Case-insensitive substring search on dataset name."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created after this ISO 8601 timestamp.","title":"Created After"},"description":"Filter datasets created after this ISO 8601 timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created before this ISO 8601 timestamp.","title":"Created Before"},"description":"Filter datasets created before this ISO 8601 timestamp."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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.","title":"Bbox"},"description":"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."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags.","title":"Tag"},"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags."},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ListDatasetResponse"},"title":"Response List Datasets Datasets Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## POST /datasets > Add Dataset ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"AddImageDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"image","title":"Type","default":"image"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs or wildcards to the image files. Wildcards are supported using the ``*`` character. e.g. ``gs://example-bucket/image_*.tif``"},"bands":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bands","description":"List of bands to add to the dataset. If not provided, all bands will be added."},"groupby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Groupby","description":"[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.","deprecated":true},"filename_date_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename Date Pattern","description":"Pattern to extract the date from the filename."},"filename_band_pattern":{"anyOf":[{"items":{"$ref":"#/components/schemas/FilenameBandPattern"},"type":"array"},{"type":"null"}],"title":"Filename Band Pattern","description":"Pattern to extract the band from the filename."}},"type":"object","required":["name","urls"],"title":"AddImageDatasetRequest","description":"Request to add an image dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"FilenameBandPattern":{"properties":{"pattern":{"type":"string","title":"Pattern"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"band_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Band Mapping"}},"type":"object","required":["pattern"],"title":"FilenameBandPattern","description":"Pattern for mapping filename patterns to band names"},"AddZarrDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"zarr","title":"Type","default":"zarr"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs to the Zarr files. Currently only supports 1 URL. Can 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."},"rename":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Rename"}},"type":"object","required":["name","urls"],"title":"AddZarrDatasetRequest","description":"Request to add a Zarr dataset"},"AddVectorDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"vector","title":"Type","default":"vector"},"url":{"type":"string","title":"Url","description":"URL to the vector dataset."},"coordinate_precision":{"type":"string","enum":["auto","1250m","600m","300m","150m","80m","40m","20m","10m","5m","2m","1m","50cm","25cm","15cm","8cm"],"title":"Coordinate Precision","description":"Controls the approximate precision of coordinates in the optimized dataset. 'auto' tries to detect an appropriate precision. Other values specify the desired coordinate precision explicitly.","default":"auto"}},"type":"object","required":["name","url"],"title":"AddVectorDatasetRequest","description":"Request to add a vector dataset"},"AddTileServerDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"tileserver","title":"Type","default":"tileserver"},"url":{"type":"string","title":"Url","description":"URL to an XYZ tile server."}},"type":"object","required":["name","url"],"title":"AddTileServerDatasetRequest"},"AddDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"AddDatasetResponse"},"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"}}},"paths":{"/datasets":{"post":{"tags":["Datasets","Datasets"],"summary":"Add Dataset","operationId":"Add_dataset_datasets_post","parameters":[{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AddImageDatasetRequest"},{"$ref":"#/components/schemas/AddZarrDatasetRequest"},{"$ref":"#/components/schemas/AddVectorDatasetRequest"},{"$ref":"#/components/schemas/AddTileServerDatasetRequest"}],"title":"Request"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDatasetResponse"}}}},"422":{"description":"Unable to process the request (e.g. unsupported dataset type, source files not accessible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Delete Dataset > Soft-delete a dataset.\ > \ > Deletion works by creating a new dataset version that marks the dataset\ > as deleted. This hides the dataset from the catalog and listing APIs,\ > but tiling requests for existing versions are still accepted. Optionally\ > removes the dataset from all maps.\ > \ > Both dataset IDs and dataset version IDs are accepted — it does not\ > matter which is passed, the entire dataset is deleted either way.\ > \ > Returns the dataset ID and the ID of the newly created deletion marker\ > version. ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"DeleteDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"DeleteDatasetResponse"},"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/datasets/{dataset_id}":{"delete":{"tags":["Datasets","Datasets"],"summary":"Delete Dataset","description":"Soft-delete a dataset.\n\nDeletion works by creating a new dataset version that marks the dataset\nas deleted. This hides the dataset from the catalog and listing APIs,\nbut tiling requests for existing versions are still accepted. Optionally\nremoves the dataset from all maps.\n\nBoth dataset IDs and dataset version IDs are accepted — it does not\nmatter which is passed, the entire dataset is deleted either way.\n\nReturns the dataset ID and the ID of the newly created deletion marker\nversion.","operationId":"Delete_dataset_datasets__dataset_id__delete","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dataset Id"}},{"name":"remove_from_maps","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Remove From Maps"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteDatasetResponse"}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dataset is already deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## List Datasets (Cursor Pagination) > List datasets with cursor-based pagination (recommended).\ > \ > This is the preferred endpoint for iterating over datasets. It\ > returns a paginated response with a \`\`next\_cursor\`\` token. Pass the\ > token back as the \`\`cursor\`\` query parameter to fetch the next page.\ > When \`\`next\_cursor\`\` is \`\`null\`\`, all results have been returned.\ > \ > Supports the same filters as \`\`GET /v1/datasets\`\`. All filters are\ > combined with AND logic. When multiple tags are specified, only\ > datasets matching \*\*all\*\* of them are returned.\ > \ > Results are ordered by \`\`updated\_at\`\` descending, then by dataset\ > version ID for stable ordering across pages. ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"PaginatedListDatasetResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ListDatasetResponse"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"PaginatedListDatasetResponse","description":"Paginated list of datasets with cursor-based pagination"},"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/datasets/cursor":{"get":{"tags":["Datasets","Datasets"],"summary":"List Datasets (Cursor Pagination)","description":"List datasets with cursor-based pagination (recommended).\n\nThis is the preferred endpoint for iterating over datasets. It\nreturns a paginated response with a ``next_cursor`` token. Pass the\ntoken back as the ``cursor`` query parameter to fetch the next page.\nWhen ``next_cursor`` is ``null``, all results have been returned.\n\nSupports the same filters as ``GET /v1/datasets``. All filters are\ncombined with AND logic. When multiple tags are specified, only\ndatasets matching **all** of them are returned.\n\nResults are ordered by ``updated_at`` descending, then by dataset\nversion ID for stable ordering across pages.","operationId":"List_datasets__cursor_pagination__datasets_cursor_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring search on dataset name.","title":"Name"},"description":"Case-insensitive substring search on dataset name."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created after this ISO 8601 timestamp.","title":"Created After"},"description":"Filter datasets created after this ISO 8601 timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter datasets created before this ISO 8601 timestamp.","title":"Created Before"},"description":"Filter datasets created before this ISO 8601 timestamp."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor token from a previous paginated response.","title":"Cursor"},"description":"Opaque cursor token from a previous paginated response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"bbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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.","title":"Bbox"},"description":"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."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags.","title":"Tag"},"description":"Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use '\\:' for a literal colon, '\\\\' for a literal backslash. Datasets must match ALL specified tags."},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedListDatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Latest Dataset Version > Get the latest version of a dataset by dataset ID. ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"DatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"variables":{"additionalProperties":{"$ref":"#/components/schemas/Variable"},"type":"object","title":"Variables"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"visualization_optimization":{"$ref":"#/components/schemas/Optimization"},"pixel_info_optimizations":{"additionalProperties":{"$ref":"#/components/schemas/Optimization"},"type":"object","title":"Pixel Info Optimizations"},"dynamic_tile_server":{"$ref":"#/components/schemas/TileServer"},"optimized_tile_server":{"anyOf":[{"$ref":"#/components/schemas/TileServer"},{"type":"null"}]}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","visualization_optimization","dynamic_tile_server","optimized_tile_server"],"title":"DatasetResponse"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"},"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"},"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/datasets/{dataset_id}/latest":{"get":{"tags":["Datasets","Datasets"],"summary":"Get Latest Dataset Version","description":"Get the latest version of a dataset by dataset ID.","operationId":"Get_latest_dataset_version_datasets__dataset_id__latest_get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Dataset Id"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Dataset Version By Id > Get a dataset version by version ID. ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/auth/v1/token?grant_type=password"}}}},"schemas":{"DatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"variables":{"additionalProperties":{"$ref":"#/components/schemas/Variable"},"type":"object","title":"Variables"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"visualization_optimization":{"$ref":"#/components/schemas/Optimization"},"pixel_info_optimizations":{"additionalProperties":{"$ref":"#/components/schemas/Optimization"},"type":"object","title":"Pixel Info Optimizations"},"dynamic_tile_server":{"$ref":"#/components/schemas/TileServer"},"optimized_tile_server":{"anyOf":[{"$ref":"#/components/schemas/TileServer"},{"type":"null"}]}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","visualization_optimization","dynamic_tile_server","optimized_tile_server"],"title":"DatasetResponse"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"},"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"},"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/dataset-versions/{version_id}":{"get":{"tags":["Datasets","Datasets"],"summary":"Get Dataset Version By Id","description":"Get a dataset version by version ID.","operationId":"Get_dataset_version_by_id_dataset_versions__version_id__get","parameters":[{"name":"version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Version Id"}},{"name":"x-earthscale-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Earthscale-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` # Models ## The AddDatasetResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"AddDatasetResponse"}}}} ``` ## The AddImageDatasetRequest object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddImageDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"image","title":"Type","default":"image"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs or wildcards to the image files. Wildcards are supported using the ``*`` character. e.g. ``gs://example-bucket/image_*.tif``"},"bands":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Bands","description":"List of bands to add to the dataset. If not provided, all bands will be added."},"groupby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Groupby","description":"[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.","deprecated":true},"filename_date_pattern":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename Date Pattern","description":"Pattern to extract the date from the filename."},"filename_band_pattern":{"anyOf":[{"items":{"$ref":"#/components/schemas/FilenameBandPattern"},"type":"array"},{"type":"null"}],"title":"Filename Band Pattern","description":"Pattern to extract the band from the filename."}},"type":"object","required":["name","urls"],"title":"AddImageDatasetRequest","description":"Request to add an image dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"FilenameBandPattern":{"properties":{"pattern":{"type":"string","title":"Pattern"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"band_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Band Mapping"}},"type":"object","required":["pattern"],"title":"FilenameBandPattern","description":"Pattern for mapping filename patterns to band names"}}}} ``` ## The AddTileServerDatasetRequest object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddTileServerDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"tileserver","title":"Type","default":"tileserver"},"url":{"type":"string","title":"Url","description":"URL to an XYZ tile server."}},"type":"object","required":["name","url"],"title":"AddTileServerDatasetRequest"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The AddVectorDatasetRequest object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddVectorDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"vector","title":"Type","default":"vector"},"url":{"type":"string","title":"Url","description":"URL to the vector dataset."},"coordinate_precision":{"type":"string","enum":["auto","1250m","600m","300m","150m","80m","40m","20m","10m","5m","2m","1m","50cm","25cm","15cm","8cm"],"title":"Coordinate Precision","description":"Controls the approximate precision of coordinates in the optimized dataset. 'auto' tries to detect an appropriate precision. Other values specify the desired coordinate precision explicitly.","default":"auto"}},"type":"object","required":["name","url"],"title":"AddVectorDatasetRequest","description":"Request to add a vector dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The AddZarrDatasetRequest object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"AddZarrDatasetRequest":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the dataset"},"labels":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array"},{"type":"null"}],"title":"Labels","description":"DEPRECATED: Please use `tags` instead. User-defined labels to add to the dataset. If both `tags` and `labels` are provided, `tags` will be used.","deprecated":true},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags","description":"User-defined tags to add to the dataset. Tags are key-value pairs that can be used to categorize and filter datasets."},"visualization_optimization":{"anyOf":[{"type":"boolean"},{"type":"string","const":"auto"}],"title":"Visualization Optimization","description":"Whether to optimize the dataset for visualization. If set to 'auto', the dataset will be optimized if it is small enough.","default":"auto"},"pixel_info_optimizations":{"items":{"type":"string"},"type":"array","title":"Pixel Info Optimizations","description":"List of dimensions to optimize for the pixel info API. This is useful to quickly retrieve all values of a dimension for a given pixel, e.g. a time series."},"type":{"type":"string","const":"zarr","title":"Type","default":"zarr"},"urls":{"items":{"type":"string"},"type":"array","title":"Urls","description":"List of URLs to the Zarr files. Currently only supports 1 URL. Can 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."},"rename":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Rename"}},"type":"object","required":["name","urls"],"title":"AddZarrDatasetRequest","description":"Request to add a Zarr dataset"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The DatasetLabel object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The DatasetResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"variables":{"additionalProperties":{"$ref":"#/components/schemas/Variable"},"type":"object","title":"Variables"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"visualization_optimization":{"$ref":"#/components/schemas/Optimization"},"pixel_info_optimizations":{"additionalProperties":{"$ref":"#/components/schemas/Optimization"},"type":"object","title":"Pixel Info Optimizations"},"dynamic_tile_server":{"$ref":"#/components/schemas/TileServer"},"optimized_tile_server":{"anyOf":[{"$ref":"#/components/schemas/TileServer"},{"type":"null"}]}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","visualization_optimization","dynamic_tile_server","optimized_tile_server"],"title":"DatasetResponse"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"},"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"},"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"},"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"}}}} ``` ## The DatasetType object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"}}}} ``` ## The DeleteDatasetResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"DeleteDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"}},"type":"object","required":["dataset_id","dataset_version_id"],"title":"DeleteDatasetResponse"}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"properties":{"message":{"type":"string","title":"Message"},"error_class":{"type":"string","title":"Error Class"}},"type":"object","required":["message","error_class"],"title":"ErrorResponse"}}}} ``` ## The FilenameBandPattern object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"FilenameBandPattern":{"properties":{"pattern":{"type":"string","title":"Pattern"},"band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Band"},"band_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Band Mapping"}},"type":"object","required":["pattern"],"title":"FilenameBandPattern","description":"Pattern for mapping filename patterns to band names"}}}} ``` ## The HTTPValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The ListDatasetResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The Optimization object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"Optimization":{"properties":{"status":{"type":"string","enum":["not_started","pending","running","success","error"],"title":"Status"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status"],"title":"Optimization"}}}} ``` ## The PaginatedListDatasetResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"PaginatedListDatasetResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ListDatasetResponse"},"type":"array","title":"Data"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"PaginatedListDatasetResponse","description":"Paginated list of datasets with cursor-based pagination"},"ListDatasetResponse":{"properties":{"dataset_id":{"type":"string","format":"uuid","title":"Dataset Id"},"dataset_version_id":{"type":"string","format":"uuid","title":"Dataset Version Id"},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/DatasetType"},"labels":{"items":{"$ref":"#/components/schemas/DatasetLabel"},"type":"array","title":"Labels"},"tags":{"additionalProperties":{"type":"string"},"type":"object","title":"Tags"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["dataset_id","dataset_version_id","name","type","created_at","updated_at"],"title":"ListDatasetResponse","description":"Single entry in the list of datasets with a subset of information"},"DatasetType":{"type":"string","enum":["raster","vector"],"title":"DatasetType"},"DatasetLabel":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"type":"object","required":["name","value"],"title":"DatasetLabel","description":"User-defined label for a dataset"}}}} ``` ## The TileServer object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"TileServer":{"properties":{"tile_url":{"type":"string","title":"Tile Url"},"pixel_url":{"type":"string","title":"Pixel Url"},"min_zoom":{"type":"integer","title":"Min Zoom"},"max_zoom":{"type":"integer","title":"Max Zoom"}},"type":"object","required":["tile_url","pixel_url","min_zoom","max_zoom"],"title":"TileServer"}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The Variable object ```json {"openapi":"3.1.0","info":{"title":"Earthscale API v1","version":"1.0.0"},"components":{"schemas":{"Variable":{"properties":{"sampled_min":{"type":"number","title":"Sampled Min"},"sampled_max":{"type":"number","title":"Sampled Max"}},"type":"object","required":["sampled_min","sampled_max"],"title":"Variable","description":"Estimated statistics for a variable in the dataset, useful for visualization"}}}} ``` # Fast Tiler HTTP API This is the high-performance tile server used for accelerated (pre-processed) datasets. If a dataset has not been accelerated yet, use the [dynamic tiler](/http-api/dynamic-tiler-http-api) instead. Requests to this service are suitable for production integration into other services, since it is highly scalable, fast and reliable. # Tiles ## Raster Tile > Get a 512x512 pixel raster tile in Web Mercator projection (EPSG:3857)\ > using the common\ > \[XYZ tiling scheme]\( > \ > Note that we use 512x512 instead of 256x256 tiles.\ > \ > Tiles are rendered for predictable, reliably fast performance. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/tiles/{z}/{x}/{y}.{format}":{"get":{"tags":["Tiles"],"summary":"Raster Tile","description":"Get a 512x512 pixel raster tile in Web Mercator projection (EPSG:3857)\nusing the common\n[XYZ tiling scheme](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).\n\nNote that we use 512x512 instead of 256x256 tiles.\n\nTiles are rendered for predictable, reliably fast performance.","operationId":"Raster_Tile_raster__dataset_version_id__tiles__z___x___y___format__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"z","in":"path","required":true,"schema":{"type":"integer","description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)","title":"Z"},"description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)"},{"name":"x","in":"path","required":true,"schema":{"type":"integer","description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"X"},"description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"y","in":"path","required":true,"schema":{"type":"integer","description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"Y"},"description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"format","in":"path","required":true,"schema":{"enum":["webp","jpeg","png"],"type":"string","description":"Output image format. PNG/WEBP support transparency. WEBP offers the best compression-to-quality ratio. JPEG is more widely compatible.","title":"Format"},"description":"Output image format. PNG/WEBP support transparency. WEBP offers the best compression-to-quality ratio. JPEG is more widely compatible."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variables","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Dataset variables to render. Specify one variable for grayscale/colormapped output, or exactly three for RGB composites (mapped to red, green, blue channels)","default":[],"title":"Variables"},"description":"Dataset variables to render. Specify one variable for grayscale/colormapped output, or exactly three for RGB composites (mapped to red, green, blue channels)"},{"name":"colormap_name","in":"query","required":false,"schema":{"anyOf":[{"enum":["accent","afmhot","algae","amp","autumn","balance","binary","blues","bone","brbg","brg","bugn","bupu","bwr","cfastie","cividis","cmrmap","cool","coolwarm","copper","cubehelix","curl","dark2","deep","delta","dense","diff","flag","gist_earth","gist_gray","gist_heat","gist_ncar","gist_rainbow","gist_stern","gist_yarg","gnbu","gnuplot","gnuplot2","gray","greens","greys","haline","hot","hsv","ice","inferno","jet","magma","matter","nipy_spectral","ocean","oranges","orrd","oxy","paired","pastel1","pastel2","phase","pink","piyg","plasma","prgn","prism","pubu","pubugn","puor","purd","purples","rain","rainbow","rdbu","rdgy","rdpu","rdylbu","rdylgn","reds","rplumbo","schwarzwald","seismic","set1","set2","set3","solar","spectral","speed","spring","summer","tab10","tab20","tab20b","tab20c","tarn","tempo","terrain","thermal","topo","turbid","turbo","twilight","twilight_shifted","viridis","winter","wistia","ylgn","ylgnbu","ylorbr","ylorrd","accent_r","afmhot_r","algae_r","amp_r","autumn_r","balance_r","binary_r","blues_r","bone_r","brbg_r","brg_r","bugn_r","bupu_r","bwr_r","cividis_r","cmrmap_r","cool_r","coolwarm_r","copper_r","cubehelix_r","curl_r","dark2_r","deep_r","delta_r","dense_r","diff_r","flag_r","gist_earth_r","gist_gray_r","gist_heat_r","gist_ncar_r","gist_rainbow_r","gist_stern_r","gist_yarg_r","gnbu_r","gnuplot_r","gnuplot2_r","gray_r","greens_r","greys_r","haline_r","hot_r","hsv_r","ice_r","inferno_r","jet_r","magma_r","matter_r","nipy_spectral_r","ocean_r","oranges_r","orrd_r","oxy_r","paired_r","pastel1_r","pastel2_r","phase_r","pink_r","piyg_r","plasma_r","prgn_r","prism_r","pubu_r","pubugn_r","puor_r","purd_r","purples_r","rain_r","rainbow_r","rdbu_r","rdgy_r","rdpu_r","rdylbu_r","rdylgn_r","reds_r","seismic_r","set1_r","set2_r","set3_r","solar_r","spectral_r","speed_r","spring_r","summer_r","tab10_r","tab20_r","tab20b_r","tab20c_r","tarn_r","tempo_r","terrain_r","thermal_r","topo_r","turbid_r","turbo_r","twilight_r","twilight_shifted_r","viridis_r","winter_r","wistia_r","ylgn_r","ylgnbu_r","ylorbr_r","ylorrd_r"],"type":"string"},{"type":"null"}],"description":"Color palette to apply when rendering a single variable. Maps data values to colors (e.g., 'viridis', 'terrain', 'coolwarm')","title":"Colormap Name"},"description":"Color palette to apply when rendering a single variable. Maps data values to colors (e.g., 'viridis', 'terrain', 'coolwarm')"},{"name":"reverse_colormap","in":"query","required":false,"schema":{"type":"boolean","description":"Flip the colormap direction so high values get colors normally assigned to low values and vice versa","default":false,"title":"Reverse Colormap"},"description":"Flip the colormap direction so high values get colors normally assigned to low values and vice versa"},{"name":"lossless","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Use lossless compression to preserve exact pixel values. PNG is always lossless, JPEG always lossy. WEBP supports both. Defaults to lossless for PNG/WEBP","title":"Lossless"},"description":"Use lossless compression to preserve exact pixel values. PNG is always lossless, JPEG always lossy. WEBP supports both. Defaults to lossless for PNG/WEBP"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},{"name":"rescale","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Rescale values","description":"Map data values to the 0-255 display range. Format: 'min,max' where min maps to 0 (black) and max maps to 255 (white/full color). Example: '0,100' stretches values 0-100 across the full range. For RGB, provide one pair (applies to all) or three pairs (one per channel). Use 'null' to skip: 'null,255' only clips the maximum"},"description":"Map data values to the 0-255 display range. Format: 'min,max' where min maps to 0 (black) and max maps to 255 (white/full color). Example: '0,100' stretches values 0-100 across the full range. For RGB, provide one pair (applies to all) or three pairs (one per channel). Use 'null' to skip: 'null,255' only clips the maximum"},{"name":"color_bin","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Create a discrete color classification for single-band data. Format: 'threshold:color' where pixels below the threshold get that color. Specify multiple bins in ascending order. Example: ?color_bin=10:#0000FF&color_bin=50:#00FF00&color_bin=100:#FF0000 colors values <10 blue, 10-50 green, 50-100 red. Colors can be names (red) or hex codes (#FF0000)","title":"Color Bin"},"description":"Create a discrete color classification for single-band data. Format: 'threshold:color' where pixels below the threshold get that color. Specify multiple bins in ascending order. Example: ?color_bin=10:#0000FF&color_bin=50:#00FF00&color_bin=100:#FF0000 colors values <10 blue, 10-50 green, 50-100 red. Colors can be names (red) or hex codes (#FF0000)"},{"name":"nodata","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Additional nodata values","description":"Treat specific values as transparent/missing data, in addition to any nodata value defined in the dataset. Format: 'variable:value1,value2'. Example: 'temperature:-9999' treats -9999 as missing, 'elevation:0,-1' treats both 0 and -1 as missing for that variable"},"description":"Treat specific values as transparent/missing data, in addition to any nodata value defined in the dataset. Format: 'variable:value1,value2'. Example: 'temperature:-9999' treats -9999 as missing, 'elevation:0,-1' treats both 0 and -1 as missing for that variable"},{"name":"threshold_min","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Minimum threshold","description":"Hide pixels below this value (make them transparent). Useful for masking out low values like ocean depths or cloud shadows. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},"description":"Hide pixels below this value (make them transparent). Useful for masking out low values like ocean depths or cloud shadows. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},{"name":"threshold_max","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Maximum threshold","description":"Hide pixels above this value (make them transparent). Useful for masking out high values like cloud-covered areas or saturated pixels. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},"description":"Hide pixels above this value (make them transparent). Useful for masking out high values like cloud-covered areas or saturated pixels. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Vector Tile > Get a vector tile in MVT (Mapbox Vector Tile) format using the common\ > \[XYZ tiling scheme]\(). ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/tiles/{z}/{x}/{y}.mvt":{"get":{"tags":["Tiles"],"summary":"Vector Tile","description":"Get a vector tile in MVT (Mapbox Vector Tile) format using the common\n[XYZ tiling scheme](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).","operationId":"Vector_Tile_vector__dataset_version_id__tiles__z___x___y__mvt_get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"z","in":"path","required":true,"schema":{"type":"integer","description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)","title":"Z"},"description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)"},{"name":"x","in":"path","required":true,"schema":{"type":"integer","description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"X"},"description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"y","in":"path","required":true,"schema":{"type":"integer","description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"Y"},"description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"include_properties","in":"query","required":false,"schema":{"type":"boolean","description":"Embed attribute data in the vector tile. When true, each feature includes its properties (e.g., name, category). Increases tile size but enables data-driven styling and feature inspection","default":false,"title":"Include Properties"},"description":"Embed attribute data in the vector tile. When true, each feature includes its properties (e.g., name, category). Increases tile size but enables data-driven styling and feature inspection"}],"responses":{"200":{"description":"Mapbox Vector Tile (MVT).","content":{"application/json":{"schema":{}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Encoding":{"description":"Set to gzip when the response body is gzip-compressed.","schema":{"type":"string","enum":["gzip"]}}}},"204":{"description":"No data for this tile"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Queries ## Raster Pixel Info > Get a single pixel value at a given location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/pixels/{lon}/{lat}":{"get":{"tags":["Queries"],"summary":"Raster Pixel Info","description":"Get a single pixel value at a given location.","operationId":"Raster_Pixel_Info_raster__dataset_version_id__pixels__lon___lat__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variable","in":"query","required":true,"schema":{"type":"string","description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')","title":"Variable"},"description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RasterPixelResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"RasterPixelResponse":{"properties":{"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"value":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["dimension_selection","value"],"title":"RasterPixelResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Raster Pixel Info Series > Get all pixel values for a given dimension and location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/pixels/{lon}/{lat}/{dim}":{"get":{"tags":["Queries"],"summary":"Raster Pixel Info Series","description":"Get all pixel values for a given dimension and location.","operationId":"Raster_Pixel_Info_Series_raster__dataset_version_id__pixels__lon___lat___dim__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"dim","in":"path","required":true,"schema":{"type":"string","description":"Name of the dimension to retrieve all values for (e.g., 'time'). Returns a time series or similar array of values at the given location. The dimension must be indexed in the dataset; use dimidx to fix other dimensions","title":"Dim"},"description":"Name of the dimension to retrieve all values for (e.g., 'time'). Returns a time series or similar array of values at the given location. The dimension must be indexed in the dataset; use dimidx to fix other dimensions"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variable","in":"query","required":true,"schema":{"type":"string","description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')","title":"Variable"},"description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. Specify all dimensions except the one in the URL path (dim parameter), which will be iterated over to return a series of values"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. Specify all dimensions except the one in the URL path (dim parameter), which will be iterated over to return a series of values"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RasterPixelDimensionSeriesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"RasterPixelDimensionSeriesResponse":{"properties":{"dimension":{"type":"string","title":"Dimension"},"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"values":{"anyOf":[{"items":{"anyOf":[{"type":"integer"},{"type":"null"}]},"type":"array"},{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array"}],"title":"Values"}},"type":"object","required":["dimension","dimension_selection","values"],"title":"RasterPixelDimensionSeriesResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Vector Point Query > Get vector features at a given location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/point/{lon}/{lat}":{"get":{"tags":["Queries"],"summary":"Vector Point Query","description":"Get vector features at a given location.","operationId":"Vector_Point_Query_vector__dataset_version_id__point__lon___lat__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"zoom","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches","title":"Zoom"},"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches"},{"name":"include_area_in_square_meters","in":"query","required":false,"schema":{"type":"boolean","description":"Calculate and include the geographic area of each feature in square meters using Mollweide equal-area projection. Adds an 'area_m2' property to each feature. Request fails if the dataset already has this column","default":false,"title":"Include Area In Square Meters"},"description":"Calculate and include the geographic area of each feature in square meters using Mollweide equal-area projection. Adds an 'area_m2' property to each feature. Request fails if the dataset already has this column"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Zero-based page number for paginated results. Each page returns up to 500 items","default":0,"title":"Page"},"description":"Zero-based page number for paginated results. Each page returns up to 500 items"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## List vector features with bounding boxes > Get a paginated list of all features in a vector dataset in column-oriented format.\ > The response includes column names, arrays of values (one array per row),\ > feature indices,\ > and bounding boxes (in EPSG:4326).\ > \ > This endpoint is useful for building feature explorer UIs where users can browse\ > all features in a dataset and zoom to individual features using the bounding box. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/features":{"get":{"tags":["Queries"],"summary":"List vector features with bounding boxes","description":"Get a paginated list of all features in a vector dataset in column-oriented format.\nThe response includes column names, arrays of values (one array per row),\nfeature indices,\nand bounding boxes (in EPSG:4326).\n\nThis endpoint is useful for building feature explorer UIs where users can browse\nall features in a dataset and zoom to individual features using the bounding box.","operationId":"Vector_Features_List_vector__dataset_version_id__features_get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Page number (0-indexed). Each page contains up to `page_size` features.","default":0,"title":"Page"},"description":"Page number (0-indexed). Each page contains up to `page_size` features."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of features per page. Default is 100.","default":100,"title":"Page Size"},"description":"Number of features per page. Default is 100."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Styles ## Get vector dataset style > Returns a style definition corresponding to the latest visualization settings used in\ > the Earthscale app for the dataset version.\ > \ > If \`map\_id\` is provided, only visualization settings from that specific map are\ > returned. Returns 204 (No Content) if the dataset version is not in that map or has\ > no visualization settings. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/style":{"get":{"tags":["Styles"],"summary":"Get vector dataset style","description":"Returns a style definition corresponding to the latest visualization settings used in\nthe Earthscale app for the dataset version.\n\nIf `map_id` is provided, only visualization settings from that specific map are\nreturned. Returns 204 (No Content) if the dataset version is not in that map or has\nno visualization settings.","operationId":"Vector_Style_vector__dataset_version_id__style_get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"format","in":"query","required":false,"schema":{"const":"mapbox","type":"string","description":"Style specification format. 'mapbox' returns a MapLibre/Mapbox GL style JSON with sources and layers configured for this dataset","default":"mapbox","title":"Format"},"description":"Style specification format. 'mapbox' returns a MapLibre/Mapbox GL style JSON with sources and layers configured for this dataset"},{"name":"map_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Restrict to visualization settings from a specific Earthscale map. If omitted, returns the most recently used style for this dataset globally","title":"Map Id"},"description":"Restrict to visualization settings from a specific Earthscale map. If omitted, returns the most recently used style for this dataset globally"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Models ## The HTTPValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The RasterPixelDimensionSeriesResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"components":{"schemas":{"RasterPixelDimensionSeriesResponse":{"properties":{"dimension":{"type":"string","title":"Dimension"},"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"values":{"anyOf":[{"items":{"anyOf":[{"type":"integer"},{"type":"null"}]},"type":"array"},{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array"}],"title":"Values"}},"type":"object","required":["dimension","dimension_selection","values"],"title":"RasterPixelDimensionSeriesResponse"}}}} ``` ## The RasterPixelResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"components":{"schemas":{"RasterPixelResponse":{"properties":{"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"value":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["dimension_selection","value"],"title":"RasterPixelResponse"}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Tiles API v1","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Dynamic Tiler HTTP API This is the tile server designed for maximum flexibility and fast iterations, since it directly reads from the source data, and does not require any pre-processing. The performance highly depends on the layout of the source data, so it might be advisable to trigger acceleration using the [web application](/earthscale-documentation/quickstart) or the [Python API](/python-api/getting-started) and use the [Fast Tiler](/http-api/fast-tiler-http-api) for integration into production workloads that need high performance. # Tiles ## Raster Tile > Get a 512x512 pixel raster tile in Web Mercator projection (EPSG:3857)\ > using the common\ > \[XYZ tiling scheme]\( > \ > Note that we use 512x512 instead of 256x256 tiles.\ > \ > Tiles are rendered on-demand from the source dataset. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/tiles/{z}/{x}/{y}.{format}":{"get":{"tags":["Tiles"],"summary":"Raster Tile","description":"Get a 512x512 pixel raster tile in Web Mercator projection (EPSG:3857)\nusing the common\n[XYZ tiling scheme](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).\n\nNote that we use 512x512 instead of 256x256 tiles.\n\nTiles are rendered on-demand from the source dataset.","operationId":"raster_tile_raster__dataset_version_id__tiles__z___x___y___format__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"z","in":"path","required":true,"schema":{"type":"integer","description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)","title":"Z"},"description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)"},{"name":"x","in":"path","required":true,"schema":{"type":"integer","description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"X"},"description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"y","in":"path","required":true,"schema":{"type":"integer","description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"Y"},"description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"format","in":"path","required":true,"schema":{"enum":["webp","jpeg","png"],"type":"string","description":"Output image format. PNG/WEBP support transparency. WEBP offers the best compression-to-quality ratio. JPEG is more widely compatible.","title":"Format"},"description":"Output image format. PNG/WEBP support transparency. WEBP offers the best compression-to-quality ratio. JPEG is more widely compatible."},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variables","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Dataset variables to render. Specify one variable for grayscale/colormapped output, or exactly three for RGB composites (mapped to red, green, blue channels)","default":[],"title":"Variables"},"description":"Dataset variables to render. Specify one variable for grayscale/colormapped output, or exactly three for RGB composites (mapped to red, green, blue channels)"},{"name":"colormap_name","in":"query","required":false,"schema":{"anyOf":[{"enum":["accent","afmhot","algae","amp","autumn","balance","binary","blues","bone","brbg","brg","bugn","bupu","bwr","cfastie","cividis","cmrmap","cool","coolwarm","copper","cubehelix","curl","dark2","deep","delta","dense","diff","flag","gist_earth","gist_gray","gist_heat","gist_ncar","gist_rainbow","gist_stern","gist_yarg","gnbu","gnuplot","gnuplot2","gray","greens","greys","haline","hot","hsv","ice","inferno","jet","magma","matter","nipy_spectral","ocean","oranges","orrd","oxy","paired","pastel1","pastel2","phase","pink","piyg","plasma","prgn","prism","pubu","pubugn","puor","purd","purples","rain","rainbow","rdbu","rdgy","rdpu","rdylbu","rdylgn","reds","rplumbo","schwarzwald","seismic","set1","set2","set3","solar","spectral","speed","spring","summer","tab10","tab20","tab20b","tab20c","tarn","tempo","terrain","thermal","topo","turbid","turbo","twilight","twilight_shifted","viridis","winter","wistia","ylgn","ylgnbu","ylorbr","ylorrd","accent_r","afmhot_r","algae_r","amp_r","autumn_r","balance_r","binary_r","blues_r","bone_r","brbg_r","brg_r","bugn_r","bupu_r","bwr_r","cividis_r","cmrmap_r","cool_r","coolwarm_r","copper_r","cubehelix_r","curl_r","dark2_r","deep_r","delta_r","dense_r","diff_r","flag_r","gist_earth_r","gist_gray_r","gist_heat_r","gist_ncar_r","gist_rainbow_r","gist_stern_r","gist_yarg_r","gnbu_r","gnuplot_r","gnuplot2_r","gray_r","greens_r","greys_r","haline_r","hot_r","hsv_r","ice_r","inferno_r","jet_r","magma_r","matter_r","nipy_spectral_r","ocean_r","oranges_r","orrd_r","oxy_r","paired_r","pastel1_r","pastel2_r","phase_r","pink_r","piyg_r","plasma_r","prgn_r","prism_r","pubu_r","pubugn_r","puor_r","purd_r","purples_r","rain_r","rainbow_r","rdbu_r","rdgy_r","rdpu_r","rdylbu_r","rdylgn_r","reds_r","seismic_r","set1_r","set2_r","set3_r","solar_r","spectral_r","speed_r","spring_r","summer_r","tab10_r","tab20_r","tab20b_r","tab20c_r","tarn_r","tempo_r","terrain_r","thermal_r","topo_r","turbid_r","turbo_r","twilight_r","twilight_shifted_r","viridis_r","winter_r","wistia_r","ylgn_r","ylgnbu_r","ylorbr_r","ylorrd_r"],"type":"string"},{"type":"null"}],"description":"Color palette to apply when rendering a single variable. Maps data values to colors (e.g., 'viridis', 'terrain', 'coolwarm')","title":"Colormap Name"},"description":"Color palette to apply when rendering a single variable. Maps data values to colors (e.g., 'viridis', 'terrain', 'coolwarm')"},{"name":"reverse_colormap","in":"query","required":false,"schema":{"type":"boolean","description":"Flip the colormap direction so high values get colors normally assigned to low values and vice versa","default":false,"title":"Reverse Colormap"},"description":"Flip the colormap direction so high values get colors normally assigned to low values and vice versa"},{"name":"lossless","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Use lossless compression to preserve exact pixel values. PNG is always lossless, JPEG always lossy. WEBP supports both. Defaults to lossless for PNG/WEBP","title":"Lossless"},"description":"Use lossless compression to preserve exact pixel values. PNG is always lossless, JPEG always lossy. WEBP supports both. Defaults to lossless for PNG/WEBP"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},{"name":"rescale","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Rescale values","description":"Map data values to the 0-255 display range. Format: 'min,max' where min maps to 0 (black) and max maps to 255 (white/full color). Example: '0,100' stretches values 0-100 across the full range. For RGB, provide one pair (applies to all) or three pairs (one per channel). Use 'null' to skip: 'null,255' only clips the maximum"},"description":"Map data values to the 0-255 display range. Format: 'min,max' where min maps to 0 (black) and max maps to 255 (white/full color). Example: '0,100' stretches values 0-100 across the full range. For RGB, provide one pair (applies to all) or three pairs (one per channel). Use 'null' to skip: 'null,255' only clips the maximum"},{"name":"color_bin","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Create a discrete color classification for single-band data. Format: 'threshold:color' where pixels below the threshold get that color. Specify multiple bins in ascending order. Example: ?color_bin=10:#0000FF&color_bin=50:#00FF00&color_bin=100:#FF0000 colors values <10 blue, 10-50 green, 50-100 red. Colors can be names (red) or hex codes (#FF0000)","title":"Color Bin"},"description":"Create a discrete color classification for single-band data. Format: 'threshold:color' where pixels below the threshold get that color. Specify multiple bins in ascending order. Example: ?color_bin=10:#0000FF&color_bin=50:#00FF00&color_bin=100:#FF0000 colors values <10 blue, 10-50 green, 50-100 red. Colors can be names (red) or hex codes (#FF0000)"},{"name":"nodata","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Additional nodata values","description":"Treat specific values as transparent/missing data, in addition to any nodata value defined in the dataset. Format: 'variable:value1,value2'. Example: 'temperature:-9999' treats -9999 as missing, 'elevation:0,-1' treats both 0 and -1 as missing for that variable"},"description":"Treat specific values as transparent/missing data, in addition to any nodata value defined in the dataset. Format: 'variable:value1,value2'. Example: 'temperature:-9999' treats -9999 as missing, 'elevation:0,-1' treats both 0 and -1 as missing for that variable"},{"name":"threshold_min","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Minimum threshold","description":"Hide pixels below this value (make them transparent). Useful for masking out low values like ocean depths or cloud shadows. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},"description":"Hide pixels below this value (make them transparent). Useful for masking out low values like ocean depths or cloud shadows. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},{"name":"threshold_max","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Maximum threshold","description":"Hide pixels above this value (make them transparent). Useful for masking out high values like cloud-covered areas or saturated pixels. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"},"description":"Hide pixels above this value (make them transparent). Useful for masking out high values like cloud-covered areas or saturated pixels. For RGB, provide one value (applies to all) or three (one per channel). Use 'null' to skip thresholding for a channel"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Vector Tile > Get a vector tile for a given dataset, dataset version, and tile. Encoded as a Mapbox Vector Tile (MVT). The layer name is always 'default'. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/tiles/{z}/{x}/{y}.mvt":{"get":{"tags":["Tiles"],"summary":"Vector Tile","description":"Get a vector tile for a given dataset, dataset version, and tile. Encoded as a Mapbox Vector Tile (MVT). The layer name is always 'default'.","operationId":"vector_tile_vector__dataset_version_id__tiles__z___x___y__mvt_get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"z","in":"path","required":true,"schema":{"type":"integer","description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)","title":"Z"},"description":"Web Mercator zoom level (0-22). Higher values show more detail. Zoom 0 shows the whole world in one tile. We use 512x512 pixel tiles, so the resolution might be twice as high as what you might expect. See [Zoom levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)"},{"name":"x","in":"path","required":true,"schema":{"type":"integer","description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"X"},"description":"Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"y","in":"path","required":true,"schema":{"type":"integer","description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1","title":"Y"},"description":"Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"include_properties","in":"query","required":false,"schema":{"type":"boolean","description":"Embed attribute data in the vector tile. When true, each feature includes its properties (e.g., name, category). Increases tile size but enables data-driven styling and feature inspection","default":false,"title":"Include Properties"},"description":"Embed attribute data in the vector tile. When true, each feature includes its properties (e.g., name, category). Increases tile size but enables data-driven styling and feature inspection"}],"responses":{"200":{"description":"Mapbox Vector Tile (MVT)","content":{"application/json":{"schema":{}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Encoding":{"description":"Set to gzip when the response body is gzip-compressed.","schema":{"type":"string","enum":["gzip"]}}}},"204":{"description":"No data for this tile"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Queries ## Raster Pixel Info > Get a single pixel value at a given location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/pixels/{lon}/{lat}":{"get":{"tags":["Queries"],"summary":"Raster Pixel Info","description":"Get a single pixel value at a given location.","operationId":"raster_pixel_info_raster__dataset_version_id__pixels__lon___lat__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variable","in":"query","required":true,"schema":{"type":"string","description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')","title":"Variable"},"description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')"},{"name":"zoom","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches","title":"Zoom"},"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. All extra dimensions of the dataset must be specified to select a single value"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RasterPixelResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"RasterPixelResponse":{"properties":{"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"value":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["dimension_selection","value"],"title":"RasterPixelResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Raster Pixel Info Series > Get all pixel values for a given dimension and location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/raster/{dataset_version_id}/pixels/{lon}/{lat}/{dim}":{"get":{"tags":["Queries"],"summary":"Raster Pixel Info Series","description":"Get all pixel values for a given dimension and location.","operationId":"raster_pixel_info_series_raster__dataset_version_id__pixels__lon___lat___dim__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"dim","in":"path","required":true,"schema":{"type":"string","description":"Name of the dimension to retrieve all values for (e.g., 'time'). Returns a time series or similar array of values at the given location. The dimension must be indexed in the dataset; use dimidx to fix other dimensions","title":"Dim"},"description":"Name of the dimension to retrieve all values for (e.g., 'time'). Returns a time series or similar array of values at the given location. The dimension must be indexed in the dataset; use dimidx to fix other dimensions"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"variable","in":"query","required":true,"schema":{"type":"string","description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')","title":"Variable"},"description":"Name of the data variable/band to retrieve from the dataset (e.g., 'temperature', 'B4', 'elevation')"},{"name":"zoom","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches","title":"Zoom"},"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Zero-based page number for paginated results. Each page returns up to 500 items","default":0,"title":"Page"},"description":"Zero-based page number for paginated results. Each page returns up to 500 items"},{"name":"dimidx","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Dimension indices","description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. Specify all dimensions except the one in the URL path (dim parameter), which will be iterated over to return a series of values"},"description":"Select a slice from multi-dimensional datasets (e.g., with time or depth axes). Format: 'dimension:index' where index is zero-based. Example: 'time:0' selects the first timestep, 'depth:5' selects the 6th depth level. Repeat for multiple dimensions: ?dimidx=time:0&dimidx=depth:2. Specify all dimensions except the one in the URL path (dim parameter), which will be iterated over to return a series of values"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RasterPixelDimensionSeriesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"RasterPixelDimensionSeriesResponse":{"properties":{"dimension":{"type":"string","title":"Dimension"},"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"values":{"anyOf":[{"items":{"anyOf":[{"type":"integer"},{"type":"null"}]},"type":"array"},{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array"}],"title":"Values"},"page_size":{"type":"integer","title":"Page Size","default":500}},"type":"object","required":["dimension","dimension_selection","values"],"title":"RasterPixelDimensionSeriesResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Vector Point Query > Get vector features at a given location. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/point/{lon}/{lat}":{"get":{"tags":["Queries"],"summary":"Vector Point Query","description":"Get vector features at a given location.","operationId":"vector_point_query_vector__dataset_version_id__point__lon___lat__get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"lon","in":"path","required":true,"schema":{"type":"number","description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)","title":"Lon"},"description":"Longitude in decimal degrees (-180 to 180, WGS84/EPSG:4326)"},{"name":"lat","in":"path","required":true,"schema":{"type":"number","description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)","title":"Lat"},"description":"Latitude in decimal degrees (-90 to 90, WGS84/EPSG:4326)"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"zoom","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches","title":"Zoom"},"description":"Map zoom level for fuzzy coordinate matching. When specified, searches within a pixel-sized radius around the coordinates to handle click imprecision. If omitted, returns only exact coordinate matches"},{"name":"include_area_in_square_meters","in":"query","required":false,"schema":{"type":"boolean","description":"Calculate and include the geographic area of each feature in square meters using Mollweide equal-area projection. Adds an 'area_m2' property to each feature. Request fails if the dataset already has this column","default":false,"title":"Include Area In Square Meters"},"description":"Calculate and include the geographic area of each feature in square meters using Mollweide equal-area projection. Adds an 'area_m2' property to each feature. Request fails if the dataset already has this column"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Zero-based page number for paginated results. Each page returns up to 500 items","default":0,"title":"Page"},"description":"Zero-based page number for paginated results. Each page returns up to 500 items"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorPointQueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"VectorPointQueryResponse":{"properties":{"feature_collection":{"$ref":"#/components/schemas/FeatureCollection_Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type_____dict_str__Any___"},"page_size":{"type":"integer","title":"Page Size","default":500}},"type":"object","required":["feature_collection"],"title":"VectorPointQueryResponse","description":"Response model for vector point query."},"FeatureCollection_Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type_____dict_str__Any___":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"FeatureCollection","title":"Type"},"features":{"items":{"$ref":"#/components/schemas/Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__"},"type":"array","title":"Features"}},"type":"object","required":["type","features"],"title":"FeatureCollection[Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]]"},"Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Feature","title":"Type"},"geometry":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},{"type":"null"}],"title":"Geometry"},"properties":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Properties"},"id":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Id"}},"type":"object","required":["type","geometry","properties"],"title":"Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]"},"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3},"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"},"GeometryCollection":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"GeometryCollection","title":"Type"},"geometries":{"items":{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},"type":"array","title":"Geometries"}},"type":"object","required":["type","geometries"],"title":"GeometryCollection","description":"GeometryCollection Model"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Styles ## Get vector dataset style > Returns a style definition corresponding to the latest visualization settings used in\ > the Earthscale app for the dataset version.\ > \ > If \`map\_id\` is provided, only visualization settings from that specific map are\ > returned. Returns 204 (No Content) if the dataset version is not in that map or has\ > no visualization settings. ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"servers":[{"url":"/v1"}],"paths":{"/vector/{dataset_version_id}/style":{"get":{"tags":["Styles"],"summary":"Get vector dataset style","description":"Returns a style definition corresponding to the latest visualization settings used in\nthe Earthscale app for the dataset version.\n\nIf `map_id` is provided, only visualization settings from that specific map are\nreturned. Returns 204 (No Content) if the dataset version is not in that map or has\nno visualization settings.","operationId":"get_vector_style_vector__dataset_version_id__style_get","parameters":[{"name":"dataset_version_id","in":"path","required":true,"schema":{"type":"string","description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time","title":"Dataset Version Id"},"description":"UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time"},{"name":"api_key","in":"query","required":true,"schema":{"type":"string","description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'","title":"Api Key"},"description":"Earthscale API key used to authenticate requests and determine which datasets you have access to. API keys can be managed in the [Earthscale Web App](https://app.earthscale.ai) under the user menu (top-right) -> 'API Settings'"},{"name":"format","in":"query","required":false,"schema":{"const":"mapbox","type":"string","description":"Style specification format. 'mapbox' returns a MapLibre/Mapbox GL style JSON with sources and layers configured for this dataset","default":"mapbox","title":"Format"},"description":"Style specification format. 'mapbox' returns a MapLibre/Mapbox GL style JSON with sources and layers configured for this dataset"},{"name":"map_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Restrict to visualization settings from a specific Earthscale map. If omitted, returns the most recently used style for this dataset globally","title":"Map Id"},"description":"Restrict to visualization settings from a specific Earthscale map. If omitted, returns the most recently used style for this dataset globally"}],"responses":{"200":{"description":"Mapbox/MapLibre style JSON","content":{"application/json":{"schema":{}}}},"204":{"description":"If the dataset version is not in that map or has no defined visualization."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` # Models ## The FeatureCollection\_Feature\_Annotated\_Union\_Point\_\_MultiPoint\_\_LineString\_\_MultiLineString\_\_Polygon\_\_MultiPolygon\_\_GeometryCollection\_\_\_FieldInfo\_annotation\_NoneType\_\_required\_True\_\_discriminator\_\_type\_\_\_\_\_dict\_str\_\_Any\_\_\_ object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"FeatureCollection_Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type_____dict_str__Any___":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"FeatureCollection","title":"Type"},"features":{"items":{"$ref":"#/components/schemas/Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__"},"type":"array","title":"Features"}},"type":"object","required":["type","features"],"title":"FeatureCollection[Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]]"},"Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Feature","title":"Type"},"geometry":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},{"type":"null"}],"title":"Geometry"},"properties":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Properties"},"id":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Id"}},"type":"object","required":["type","geometry","properties"],"title":"Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]"},"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3},"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"},"GeometryCollection":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"GeometryCollection","title":"Type"},"geometries":{"items":{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},"type":"array","title":"Geometries"}},"type":"object","required":["type","geometries"],"title":"GeometryCollection","description":"GeometryCollection Model"}}}} ``` ## The Feature\_Annotated\_Union\_Point\_\_MultiPoint\_\_LineString\_\_MultiLineString\_\_Polygon\_\_MultiPolygon\_\_GeometryCollection\_\_\_FieldInfo\_annotation\_NoneType\_\_required\_True\_\_discriminator\_\_type\_\_\_\_dict\_str\_\_Any\_\_ object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Feature","title":"Type"},"geometry":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},{"type":"null"}],"title":"Geometry"},"properties":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Properties"},"id":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Id"}},"type":"object","required":["type","geometry","properties"],"title":"Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]"},"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3},"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"},"GeometryCollection":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"GeometryCollection","title":"Type"},"geometries":{"items":{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},"type":"array","title":"Geometries"}},"type":"object","required":["type","geometries"],"title":"GeometryCollection","description":"GeometryCollection Model"}}}} ``` ## The GeometryCollection object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"GeometryCollection":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"GeometryCollection","title":"Type"},"geometries":{"items":{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},"type":"array","title":"Geometries"}},"type":"object","required":["type","geometries"],"title":"GeometryCollection","description":"GeometryCollection Model"},"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3},"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"}}}} ``` ## The HTTPValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The LineString object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The MultiLineString object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The MultiPoint object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The MultiPolygon object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The Point object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The Polygon object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The Position2D object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2}}}} ``` ## The Position3D object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3}}}} ``` ## The RasterPixelDimensionSeriesResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"RasterPixelDimensionSeriesResponse":{"properties":{"dimension":{"type":"string","title":"Dimension"},"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"values":{"anyOf":[{"items":{"anyOf":[{"type":"integer"},{"type":"null"}]},"type":"array"},{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array"}],"title":"Values"},"page_size":{"type":"integer","title":"Page Size","default":500}},"type":"object","required":["dimension","dimension_selection","values"],"title":"RasterPixelDimensionSeriesResponse"}}}} ``` ## The RasterPixelResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"RasterPixelResponse":{"properties":{"dimension_selection":{"additionalProperties":{"type":"integer"},"type":"object","title":"Dimension Selection"},"value":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"title":"Value"}},"type":"object","required":["dimension_selection","value"],"title":"RasterPixelResponse"}}}} ``` ## The ValidationError object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## The VectorPointQueryResponse object ```json {"openapi":"3.1.0","info":{"title":"Earthscale Dynamic Tiler API v1","version":"1.0.0"},"components":{"schemas":{"VectorPointQueryResponse":{"properties":{"feature_collection":{"$ref":"#/components/schemas/FeatureCollection_Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type_____dict_str__Any___"},"page_size":{"type":"integer","title":"Page Size","default":500}},"type":"object","required":["feature_collection"],"title":"VectorPointQueryResponse","description":"Response model for vector point query."},"FeatureCollection_Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type_____dict_str__Any___":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"FeatureCollection","title":"Type"},"features":{"items":{"$ref":"#/components/schemas/Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__"},"type":"array","title":"Features"}},"type":"object","required":["type","features"],"title":"FeatureCollection[Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]]"},"Feature_Annotated_Union_Point__MultiPoint__LineString__MultiLineString__Polygon__MultiPolygon__GeometryCollection___FieldInfo_annotation_NoneType__required_True__discriminator__type____dict_str__Any__":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Feature","title":"Type"},"geometry":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},{"type":"null"}],"title":"Geometry"},"properties":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Properties"},"id":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Id"}},"type":"object","required":["type","geometry","properties"],"title":"Feature[Annotated[Union[Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection], FieldInfo(annotation=NoneType, required=True, discriminator='type')], dict[str, Any]]"},"Point":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Point","title":"Type"},"coordinates":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}],"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Point","description":"Point Model"},"Position2D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"}],"type":"array","maxItems":2,"minItems":2},"Position3D":{"prefixItems":[{"type":"number","title":"Longitude"},{"type":"number","title":"Latitude"},{"type":"number","title":"Altitude"}],"type":"array","maxItems":3,"minItems":3},"MultiPoint":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPoint","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPoint","description":"MultiPoint Model"},"LineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"LineString","title":"Type"},"coordinates":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2,"title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"LineString","description":"LineString Model"},"MultiLineString":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiLineString","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":2},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiLineString","description":"MultiLineString Model"},"Polygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"Polygon","title":"Type"},"coordinates":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"Polygon","description":"Polygon Model"},"MultiPolygon":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"MultiPolygon","title":"Type"},"coordinates":{"items":{"items":{"items":{"anyOf":[{"$ref":"#/components/schemas/Position2D"},{"$ref":"#/components/schemas/Position3D"}]},"type":"array","minItems":4},"type":"array"},"type":"array","title":"Coordinates"}},"type":"object","required":["type","coordinates"],"title":"MultiPolygon","description":"MultiPolygon Model"},"GeometryCollection":{"properties":{"bbox":{"anyOf":[{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":4,"minItems":4},{"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}],"type":"array","maxItems":6,"minItems":6},{"type":"null"}],"title":"Bbox"},"type":{"type":"string","const":"GeometryCollection","title":"Type"},"geometries":{"items":{"oneOf":[{"$ref":"#/components/schemas/Point"},{"$ref":"#/components/schemas/MultiPoint"},{"$ref":"#/components/schemas/LineString"},{"$ref":"#/components/schemas/MultiLineString"},{"$ref":"#/components/schemas/Polygon"},{"$ref":"#/components/schemas/MultiPolygon"},{"$ref":"#/components/schemas/GeometryCollection"}],"discriminator":{"propertyName":"type","mapping":{"GeometryCollection":"#/components/schemas/GeometryCollection","LineString":"#/components/schemas/LineString","MultiLineString":"#/components/schemas/MultiLineString","MultiPoint":"#/components/schemas/MultiPoint","MultiPolygon":"#/components/schemas/MultiPolygon","Point":"#/components/schemas/Point","Polygon":"#/components/schemas/Polygon"}}},"type":"array","title":"Geometries"}},"type":"object","required":["type","geometries"],"title":"GeometryCollection","description":"GeometryCollection Model"}}}} ``` # Privacy Policy *Version: 2025-12 / Effective: December 10th, 2025* Earthscale, Inc. (“**Earthscale**,” “**we**,” “**our**,” or “**us**”) is a Delaware corporation headquartered in San Francisco, California, United States. We take your privacy seriously. This policy explains what personal data we collect, how we use it, and the choices you have. *** ### 1. Information We Collect Automatically When you use our web application, documentation site, or marketing pages, we collect limited technical information such as IP address, browser type, timestamps, request paths, and performance indicators. We use this to operate and secure our systems, prevent abuse, and understand service reliability. We may use privacy-preserving, first-party analytics that do not track you across websites or build advertising profiles. *** ### 2. Account and Support Information We collect the information you provide when creating an account, inviting teammates, submitting feedback, or contacting support—typically name, email, organization, and your messages. We use this only to provide Earthscale and respond to your requests. We may send service-related or product update emails; you can unsubscribe from non-essential announcements at any time. *** ### 3. Service Operation and Improvement To operate and support Earthscale, we process information about how you use core features (for example, creating maps or running exports). This ensures the service works as expected, helps prevent misuse, and allows us to allocate computing resources. We also use aggregated and de-identified patterns to improve the service — for example, seeing which features are broadly helpful or where errors occur. We do not use usage data to create behavioral profiles of individual users for advertising or cross-context purposes. In limited cases where you explicitly show interest in capabilities (for example, by clicking a “Book a call” or “Request more quota” button), we may surface relevant service options or assistance. These interactions are considered part of providing and supporting the service. You can opt out of promotional communications at any time. We minimize the collection of personal data to what is necessary to operate, secure, and continually improve the service. *** ### 4. Cookies and Similar Technologies We use **essential** cookies for authentication and security. You can disable cookies in your browser, but Earthscale may not function properly without essential cookies. *** ### 5. Service Providers and International Transfers We rely on trusted service providers for hosting, authentication, storage, analytics, and support. These providers act only under our instructions and are bound by confidentiality and security obligations. If personal data is transferred outside your region (for example, to the United States), we use appropriate safeguards such as standard contractual clauses where required. We maintain an up-to-date list of subprocessors at . *** ### 6. Data Security We use industry-standard measures including encryption in transit, least-privilege access controls, and limited retention of diagnostic data to help safeguard personal information. No method of storage or transmission is 100% secure. *** ### 7. Retention | Data Category | Typical Retention | | ------------------ | ------------------------------------------------ | | Diagnostic logs | 90 days | | Cloud request logs | 90 days | | Account data | Until you delete your account or request erasure | | Billing records | 7 years (legal obligations) | Some information may remain in secure backups until automatically removed. *** ### 8. Your Rights Depending on your location, you may have the right to: * Access, correct, export, or delete your data * Object to certain processing * Withdraw consent where applicable We do **not** sell personal data. To make a request, contact **** from the email address associated with your account. We will respond within 30 days. *** ### 9. Children’s Data Earthscale is not intended for children under 16, and we do not knowingly collect personal data from them. *** ### 10. Changes to This Policy We may update this policy periodically. Material changes will be communicated through the app or email. Continued use after a change means you accept the updated policy. *** ### 11. Contact Earthscale, Inc. San Francisco, California United States Email: **** If you are in the EEA or UK, you may contact our designated representative once appointed (details will under Trust & Compliance). # Earthscale Architecture Overview Earthscale provides software to efficiently serve and visualize geospatial datasets from cloud storage. Earthscale’s architecture consists of the following services: * **Earthscale Explorer:** a web application to visualize geospatial datasets registered with Earthscale. * **Metadata Service**: allows users to register datasets with Earthscale, search for datasets, and query dataset metadata. * **Data Query Service**: efficiently reads and serves data from registered geospatial datasets. * **Cache Service**: manages a smart dataset cache to optimize serving latency. Writes to the **Earthscale Cache** object store. The **Earthscale Explorer** and **Metadata Service** form the Earthscale **control plane**. The **Data Query Service,** **Cache Service**, and the **Cache** form the **data plane**. First, users submit requests to the **Metadata Service** to register a new dataset given its location in cloud storage. The service reads basic metadata like spatial extent. To serve data in applications, users make API calls to the **Data** **Query** service. There are two common methods for deploying Earthscale within an organization. In both cases, any communication between the customer’s cloud and Earthscale’s cloud is governed by **secure short-lived OIDC federated credentials**. ### Standard Deployment Here, the control plane and data plane both run in Earthscale’s cloud account. Earthscale’s services read data from the customer’s cloud, and optionally cache this data in the **Cache** object store to reduce serving latency. Earthscale deploys the control and data planes in the same cloud region as the customer to minimize egress across cloud regions.
### Bring-Your-Own-Cloud Deployment In a “bring-your-own-cloud” deployment, the Earthscale **data plane** runs in the customer’s cloud account. Only metadata leaves the customer's network to register datasets with the Earthscale control plane.
*Last updated: December 10, 2025* # Subprocessors Earthscale engages subprocessors in connection with providing its Services. A subprocessor is a third-party engaged by Earthscale AI, Inc. that might process personal data on behalf of Earthscale's customers as defined in our DPA. Additional vendors may support Earthscale operations but do not process Customer Data. ### Current Subprocessors | Entity Name | Purpose | Entity Country | | ------------------------- | ------------------------- | -------------- | | Google LLC | Cloud Service Provider | United States | | Amazon Web Services, Inc. | Cloud Service Provider | United States | | Microsoft Corporation | Cloud Service Provider | United States | | Supabase, Inc. | Database Service Provider | United States | | Functional Software, Inc. | Error Monitoring | United States | *Last updated: December 10, 2025* # Data Processing Addendum (DPA) *Version: 2025-01 / Effective: December 10th, 2025* 📄 [**Download PDF**](https://storage.googleapis.com/earthscale-cdn-aa04f22d/legal/dpa/v2025-01.pdf) This Data Processing Addendum ("**DPA**") is incorporated by reference into the agreement for Earthscale services between **Earthscale AI, Inc.** ("Earthscale") and the customer entity that entered into that agreement ("**Customer**") (the "Principal Agreement"). By entering into the Principal Agreement (or any Order Form under it), **Customer agrees to this DPA**. No separate signatures are required. This DPA applies solely to the extent Earthscale processes Customer Personal Data in connection with the Earthscale Services. ## WHEREAS * The Customer acts as a **Data Controller**. * The Customer wishes to subcontract certain Services, which imply the processing of personal data, to Earthscale. * The Parties seek to implement a data processing agreement that complies with the requirements of the current legal framework, including the **General Data Protection Regulation (EU) 2016/679 (GDPR)** and any other Applicable Data Protection Laws. * The Parties wish to lay down their rights and obligations. **IT IS AGREED AS FOLLOWS:** ## 1. Definitions and Interpretation ### 1.1. Defined Terms | Term | Definition | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Applicable Data Protection Laws** | All data protection and privacy laws and regulations applicable to the respective party in its role in the processing of Customer Personal Data under the Principal Agreement, which may include European Data Protection Laws and the CCPA, to the extent applicable. | | **CCPA** | The California Consumer Privacy Act of 2018 (Cal. Civ. Code § 1798.100, et seq.), as may be amended, superseded or replaced from time to time. | | **Customer Personal Data** | Any Personal Data Processed by Earthscale on behalf of Customer pursuant to or in connection with the Principal Agreement. | | **DPA** | This Data Processing Addendum and all Schedules. | | **EEA** | The European Economic Area. | | **Earthscale Services** | The platform services (as defined in the Principal Agreement) and/or any other services directly provided by Earthscale. | | **EU Data Protection Laws** | EU Directive 95/46/EC, as transposed into domestic legislation of each Member State and as amended, replaced or superseded from time to time, including by the GDPR and laws implementing or supplementing the GDPR. | | **GDPR** | EU General Data Protection Regulation 2016/679. | | **Principal Agreement** | The SaaS Services Agreement (or other agreement for Earthscale services) between Earthscale and Customer. | | **Restricted Data Transfer** | A transfer of Customer Personal Data from the Customer to Earthscale; or an onward transfer from Earthscale to a Subprocessor, in each case, where such transfer would be prohibited by Data Protection Laws or by the terms of data transfer agreements. | | **Subprocessor** | Any person appointed by or on behalf of Earthscale to process Personal Data on behalf of the Customer in connection with the Principal Agreement. | ### 1.2. GDPR Terms The terms **Commission**, **Controller**, **Data Subject**, **Member State**, **Personal Data**, **Personal Data Breach**, **Processing**, and **Supervisory Authority** shall have the same meaning as in the GDPR, and their cognate terms shall be construed accordingly. ## 2. Processing of Customer Personal Data Earthscale shall: 1. Comply with all applicable **Data Protection Laws** in the Processing of Customer Personal Data; and 2. Not Process Customer Personal Data other than on the relevant Customer's **documented instructions**. The Customer instructs Earthscale to process Customer Personal Data. ## 3. Processor Personnel Earthscale shall take reasonable steps to ensure the reliability of any employee, agent, or contractor who may have access to the Customer Personal Data, ensuring in each case that access is **strictly limited** to those individuals who need to know / access the relevant Customer Personal Data, as strictly necessary for the purposes of the Principal Agreement, and to comply with Applicable Laws in the context of that individual's duties to Earthscale. Earthscale must ensure that all such individuals are subject to **confidentiality undertakings** or professional or statutory obligations of confidentiality. ## 4. Security ### 4.1. Technical and Organizational Measures Taking into account the state of the art, the costs of implementation and the nature, scope, context and purposes of Processing as well as the risk of varying likelihood and severity for the rights and freedoms of natural persons, Earthscale shall in relation to the Customer Personal Data implement **appropriate technical and organizational measures** to ensure a level of security appropriate to that risk, including, as appropriate, the measures referred to in Article 32(1) of the GDPR. ### 4.2. Risk Assessment In assessing the appropriate level of security, Earthscale shall take account in particular of the risks that are presented by Processing, in particular from a **Personal Data Breach**. ## 5. Subprocessing ### 5.1. Authorization Customer hereby **authorizes Earthscale to engage Subprocessors** for the processing of Customer Personal Data as described in this Section, including the Subprocessors listed at . ### 5.2. Obligations Earthscale shall: 1. Execute a **written agreement** with each Subprocessor that incorporates data protection obligations and security measures that are **no less protective** than those outlined in this DPA; and 2. Remain **fully responsible and liable** for any breach of this Agreement or DPA caused by an act, omission, or error of a Subprocessor, to the same extent Earthscale would be liable had it directly committed such act, omission, or error. ### 5.3. Notification and Objection Earthscale will update its Subprocessor List and **notify Customer at least thirty (30) calendar days** before any new Subprocessor begins processing Customer Personal Data. Customer may reasonably **object** to Earthscale's appointment of a new Subprocessor by providing written notification to Earthscale within **ten (10) calendar days** following Earthscale's notice described in Section 5.3. ### 5.4. Resolution and Termination Upon receiving an objection, Earthscale and Customer will engage in good-faith discussions aimed at resolving the objection. If a resolution cannot be reached within ten (10) calendar days of Earthscale's receipt of the objection, **Customer’s sole and exclusive remedy** is to terminate the affected Order Form(s), limited to the services that cannot be delivered without the use of the contested Subprocessor. In such cases, Earthscale shall refund Customer any prepaid, unused fees for the terminated services, prorated as of the termination date. ## 6. Data Subject Rights ### 6.1. Assistance Taking into account the nature of the Processing, Earthscale shall assist the Customer by implementing appropriate technical and organisational measures, insofar as this is possible, for the fulfilment of the Customer obligations, as reasonably understood by Customer, to respond to requests to exercise **Data Subject rights** under the Data Protection Laws. ### 6.2. Earthscale’s Responsibilities Earthscale shall: 1. **Promptly notify Customer** if it receives a request from a Data Subject under any Data Protection Law in respect of Customer Personal Data; and 2. Ensure that it **does not respond** to that request except on the documented instructions of Customer or as required by Applicable Laws to which Earthscale is subject, in which case Earthscale shall to the extent permitted by Applicable Law inform Customer of that legal requirement before it responds to the request. ## 7. Personal Data Breach ### 7.1. Notification Earthscale shall notify Customer **without undue delay** upon becoming aware of a **Personal Data Breach** affecting Customer Personal Data, providing Customer with sufficient information to allow the Customer to meet any obligations to report or inform Data Subjects of the Personal Data Breach under the Data Protection Laws. ### 7.2. Cooperation Earthscale shall **co-operate** with the Customer and take reasonable commercial steps as are directed by Customer to assist in the investigation, mitigation and remediation of each such Personal Data Breach. ## 8. Data Protection Impact Assessment and Prior Consultation Earthscale shall provide **reasonable assistance** to the Customer with any data protection impact assessments, and prior consultations with Supervisory Authorities or other competent data privacy authorities, which Customer reasonably considers to be required by Article 35 or 36 of the GDPR or equivalent provisions of any other Data Protection Law. This assistance is solely in relation to Processing of Customer Personal Data by, and taking into account the nature of the Processing and information available to Earthscale. ## 9. Deletion or Return of Customer Personal Data ### 9.1. Deletion Requirement Subject to this section 9, Earthscale shall promptly and in any event within **10 business days** of the date of cessation of any Earthscale Services involving the Processing of Customer Personal Data (the "**Cessation Date**"), **delete** and procure the deletion of all copies of those Customer Personal Data. ### 9.2. Certification Earthscale shall provide **written certification** to Customer that it has fully complied with this section 9 within 10 business days of the Cessation Date. ## 10. Audit rights ### 10.1. Audit Provision Subject to this section 10, Earthscale shall make available to the Customer on request all information necessary to demonstrate compliance with this DPA, and shall allow for and contribute to **audits, including inspections**, by the Customer or an auditor mandated by the Customer in relation to the Processing of the Customer Personal Data by Earthscale. ### 10.2. Limitations Information and audit rights of the Customer only arise under section 10.1 to the extent that the DPA does not otherwise give them information and audit rights meeting the relevant requirements of Data Protection Law. ## 11. Restricted Data Transfer ### 11.1. Transfer Mechanism Earthscale may not perform or authorize a **Restricted Data Transfer** without the prior written consent of the Customer. If personal data processed under this DPA is transferred from a country within the European Economic Area to a country outside the European Economic Area, the Parties shall ensure that the personal data are adequately protected. To achieve this, the Parties shall, unless agreed otherwise, rely on **EU approved standard contractual clauses** for the transfer of personal data. ## 12. CCPA Compliance ### 12.1. Restrictions Earthscale shall not process, retain, use, or disclose Customer Personal Data for any purpose other than for the purposes set out in the Principal Agreement, DPA and as permitted under the CCPA. Earthscale shall **not sell or share** information as those terms are defined under the CCPA. ## 13. General Terms ### 13.1. Confidentiality Each Party must keep this DPA and information it receives about the other Party and its business in connection with this DPA ("Confidential Information") confidential and must not use or disclose that Confidential Information without the prior written consent of the other Party except to the extent that: * Disclosure is **required by law**; or * The relevant information is **already in the public domain**. ### 13.2. Notices All notices and communications given under this DPA must be in **writing** and will be delivered personally, sent by post or sent by email to the address or email address set out in the heading of this DPA. Notices regarding updates to this DPA may be provided by posting by email and/or at . ### 13.3. Order of Precedence In the event of a **conflict** between this DPA and the Principal Agreement, **this DPA controls** with respect to the processing of personal data; otherwise, the Principal Agreement controls. ## 14. Updates to this DPA Earthscale may **update this DPA** from time to time to reflect changes in legal requirements, industry standards, or Earthscale's business practices, provided that **no update will materially reduce Customer's rights** under this DPA. Earthscale will provide notice of material updates by posting a notice at and/or by email, and such updates take effect **thirty (30) days after posting**. If Customer reasonably **objects** to a material update that materially diminishes Customer's rights, Customer may **terminate the affected services** and receive a pro-rated refund of any prepaid, unused fees for those services. ## 15. Governing Law and Jurisdiction This DPA is governed by, and any disputes will be brought as set out in, the **governing law and venue provisions of the Principal Agreement**. # Terms of Service *Version: 2025-12 / Effective: December 10th, 2025* These Terms of Service (“**Terms**”) govern your access to and use of Earthscale’s products, websites, APIs, and services (“**Services**”). By creating an account, accessing, or using the Services, you agree to be bound by these Terms. If you are using the Services on behalf of an organization, you represent that you have authority to bind that organization to these Terms. *** ### 1. Accounts and Eligibility You must be at least **18 years old** to use the Services. You are responsible for: * Keeping your credentials secure * All activity conducted under your account * Maintaining accurate account information We may suspend or terminate accounts for violations of these Terms or misuse of the Services. *** ### 2. User Content “User Content” means any data, files, imagery, metadata, code, or other material you provide to or store on the Services. You retain ownership of User Content. To operate the Services, you grant Earthscale a worldwide, non-exclusive license to: • Host, process, reproduce, transform, and display User Content • Generate derived visualizations and exports solely as needed to provide the Services Earthscale does not claim ownership of User Content. You represent that you have all necessary rights to upload, store, process, and display User Content, and that doing so does not infringe any laws or third-party rights. We will take commercially reasonable steps to avoid data loss; however, the Services are not intended to function as a sole data repository. You are responsible for maintaining independent backups of User Content. Data Content Warranty: You warrant that User Content will not contain Sensitive Personal Data (such as health, financial, biometric, or highly protected information) and will not contain Personal Data of any third party, unless you have obtained all necessary consents and clearances for its use, processing, and storage on the Services. Earthscale assumes no liability for the presence of any Personal Data within User Content uploaded in violation of this Term. *** ### 3. Public and Third-Party Data (Updated) Some data in the Services (“**Public Data**”), including but not limited to basemaps, geocoding data, and satellite imagery, is owned or operated by third parties and is subject to their licenses and terms. This includes **attribution obligations** required by data providers (e.g., MapTiler, OpenStreetMap, or others). Earthscale: * Does not claim ownership of Public Data. * Does not guarantee availability, accuracy, or continuity of Public Data. * Is not responsible for misuse or licensing non-compliance by users. You agree to abide by all applicable attribution requirements and license restrictions required by such third parties when displaying, exporting, or otherwise utilizing Public Data. You are solely responsible for verifying your right to use Public Data for your intended purpose. *** ### 4. Sharing and Published Content The Services allow you to share maps, visualizations, or links (“**Shared Content**”). Shared Content may be visible to anyone who has access to the link. By sharing, you grant Earthscale the right to: * Host, copy, transmit, and display Shared Content * Enable viewing and limited interaction by others you share it with You are responsible for ensuring you have the rights to share any data included in Shared Content. We may remove Shared Content to comply with law or protect the Services. *** ### 5. APIs, Fair Use, and Technical Restrictions The Services may include APIs such as tile-server endpoints. You agree not to: * Circumvent **rate limits** or **usage quotas** * Use bots, scrapers, or automated tools to extract or harvest data * Interfere with or degrade system performance, security, or availability * Attempt to access systems or data without authorization Exceeding any usage quotas or rate limits may result in the automatic throttling, suspension, or termination of your access to the relevant Services or API keys. We may apply or modify usage limits and temporarily or permanently suspend API keys that violate these Terms. *** ### 6. Feedback and Usage Data If you provide feedback, suggestions, or ideas, you grant Earthscale a worldwide, perpetual, royalty-free license to use it without obligation to you. Earthscale may collect information about usage, performance, and interaction with the Services (“**Usage Data**”) for analytics, security, and product improvement. Usage Data is owned exclusively by Earthscale. *** ### 7. Privacy Our **Privacy Policy** explains how we collect and use personal information. By using the Services, you consent to that data handling. *** ### 8. Intellectual Property Except for User Content and Public Data, the **Services** — including software, UI, design elements, documentation, and trademarks — are owned by Earthscale and its licensors. No rights are granted except as expressly provided in these Terms. *** ### 9. Beta Features and Changes to the Service Some features may be offered as **beta or experimental**. Beta features are provided **“as is”** and may be modified or discontinued at any time. We may introduce fees or modify pricing in the future. We will provide reasonable prior notice, and continued use of the Services after fee changes take effect constitutes acceptance. *** ### 10. Disclaimers THE SERVICES ARE PROVIDED **“AS IS”** AND **“AS AVAILABLE.”** EARTHSCALE MAKES NO WARRANTIES OF ANY KIND, INCLUDING: * Availability, accuracy, completeness, or continuity of Public Data * Uptime or error-free performance of compute workloads, APIs, or exports * Merchantability or fitness for a particular purpose You acknowledge that: * Compute operations may fail or be delayed * Public Data sources may become unavailable at any time * Visual outputs may represent approximations or derived transforms *** ### 11. Limitation of Liability To the fullest extent permitted by law, Earthscale will not be liable for **indirect, incidental, or consequential damages**, including lost data or lost profits. Earthscale’s total liability arising out of these Terms shall not exceed **USD $100**. Some jurisdictions do not allow certain limitations; these may not apply to you. *** ### 12. Indemnification You will indemnify and hold harmless Earthscale, its affiliates, and personnel from any claims arising from: * Your User Content or Shared Content * Your use of Public Data * Your violation of these Terms or applicable law *** ### 13. Logo and Marketing Rights You grant Earthscale the right to use your organization’s name and logo to identify you as a customer on websites and marketing materials. You can request removal at any time by contacting ****. *** ### 14. Termination You may stop using the Services at any time. We may suspend or terminate free accounts at any time, including due to prolonged inactivity or misuse of the Services. For paid subscriptions, we will provide reasonable advance notice (for example, 30 days) before terminating access, unless earlier action is required due to: • Legal or regulatory reasons • Security threats or attempts at unauthorized access • Material violation of these Terms If your access is suspended or terminated, we will provide a reasonable opportunity to export User Content prior to permanent deletion, unless we are legally prohibited from doing so or termination resulted from serious misconduct. Provisions that by nature survive termination — including ownership, warranties, liability limits, and indemnity — will remain in effect. *** ### 15. Assignment and Force Majeure We may assign or transfer these Terms in connection with a merger, acquisition, or sale of assets. You may not assign your rights without consent. Earthscale is not liable for delays or failures caused by events beyond reasonable control, including outages of cloud providers or data hosts. *** ### 16. Governing Law These Terms are governed by **California law**, excluding conflict-of-law rules. Any disputes will be resolved exclusively in courts located in **San Francisco County, California**. *** ### 17. Changes to Terms We may update these Terms from time to time. If changes are significant, we will notify you. Continued use of the Services after changes become effective constitutes acceptance. *** ### 18. Contact Questions about these Terms may be sent to: ****