Tiles

Raster Tile

get

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 from preprocessed, optimized data for predictable and reliably fast performance.

Path parameters

dataset_version_idstring · uuidRequired

UUID of the dataset version to query. Each dataset can have multiple versions representing different states of the data over time

zintegerRequired

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

xintegerRequired

Tile column index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1

yintegerRequired

Tile row index in the Web Mercator grid. Range depends on zoom level: 0 to 2^z - 1

Query parameters

api_keystringRequired

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 under the user menu (top-right) -> 'API Settings'

variablesstring[]Required

Dataset variables to render. Specify one variable for grayscale/colormapped output, or exactly three for RGB composites (mapped to red, green, blue channels)

colormap_nameany ofOptional

Color palette to apply when rendering a single variable. Maps data values to colors (e.g., 'viridis', 'terrain', 'coolwarm')

string · enumOptionalPossible values:

or

nullOptional

reverse_colormapbooleanOptional

Flip the colormap direction so high values get colors normally assigned to low values and vice versa

Default: false

losslessbooleanOptional

Use lossless WebP compression. Lossy uses quality=80. Default is lossless

Default: true

dimidxany ofOptional

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

string[]Optional

or

nullOptional

rescaleany ofOptional

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

string[]Optional

or

nullOptional

color_binany ofOptional

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)

string[]Optional

or

nullOptional

nodataany ofOptional

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

string[]Optional

or

nullOptional

threshold_minany ofOptional

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

string[]Optional

or

nullOptional

threshold_maxany ofOptional

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

string[]Optional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

get

/raster/{dataset_version_id}/tiles/{z}/{x}/{y}.webp

HTTPcURLJavaScriptPython

GET /v1/raster/{dataset_version_id}/tiles/{z}/{x}/{y}.webp?api_key=text&variables=text HTTP/1.1
Accept: */*

No content