# 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"}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.earthscale.ai/http-api/dynamic-tiler-http-api/tiles.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.