Terrains
The base maps, their sources, sprites and glyphs, and the elevation raster, served through this API so a map draws its base map under the credential it sends here. Each route is an address a map renderer is handed and fetches on its own.
A built-in terrain: the base map itineraries and zones are drawn on, such as the summer topographic map or satellite imagery. variants carries its light and dark renditions, locales its display name per language.
idstring (uuid)
Identifier of the terrain. slug is the value a person reads; this is the one the catalog keys on.
localesobject
The terrain's display name per language. Render from here rather than from slug: the slug is a stable identifier and is not translated.
slugstring
Stable, URL-safe identifier of the terrain. Unlike the display name in locales, it does not change between languages or releases. Lowercase letters, digits and single hyphens, the same shape every slug on this surface carries.
variantsobject
The light and dark renditions of this terrain. Both are always present, so a client follows the user's color scheme without fetching the catalog again.
/v1/terrains/{terrain}/{variant}/styleReturns one rendition of a terrain, light or dark, as a complete map style document in the MapLibre Style Specification, ready to hand to a map renderer unmodified. It is the address the layer catalog answers under terrains[].variants.<variant>.style.url, so a client reads it from the catalog rather than writing it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
Response 200
The style document, with every source, sprite and glyph address on this API.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/terrains/{terrain}/{variant}/tiles.jsonReturns one rendition of a terrain, light or dark, as a raster tile source described by a TileJSON document, for a client composing a style of its own rather than drawing the terrain's. It is the address the layer catalog answers under terrains[].variants.<variant>.tiles.url, so a client reads it from the catalog rather than writing it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
Response 200
The TileJSON document, its tiles template on this API.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/terrains/{terrain}/{variant}/{z}/{x}/{y}Returns one raster tile of a terrain rendition at the given zoom level, x and y coordinates, as an image whose format the Content-Type header says. It is the tiles template of the rendition's TileJSON document, getTerrainTileJson, with the {z}, {x} and {y} placeholders intact, and a map library expands and fetches it on its own schedule, so the generated SDKs bind no method for it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
zinteger (int32)
in path
Zoom level. Higher values show more detail over a smaller area. On a publishable-key request for anything but the base map (a terrain's tiles, the tiles of the sources its style draws and the elevation raster's), the organization's zoom-bounds safety rule narrows the accepted range, and a z outside it is a 400 naming z, so a structurally valid value can still be refused. Each layer's zoom_min and zoom_max in the specification say where a map should ask for tiles; they are not a refusal. A specification served to a publishable key reports them already narrowed to that rule, so a map that follows it asks only for a z the rule accepts.
xinteger (int32)
in path
Tile column index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming x, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
yinteger (int32)
in path
Tile row index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming y, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
Response 200 image/png, image/jpeg, image/webp
The tile, as a PNG (image/png), a JPEG (image/jpeg) or a WebP (image/webp) image, as the Content-Type header says.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/terrains/{terrain}/{variant}/sprites/{sprite_file}Returns one of the four sprite files of a terrain rendition: sprite.json, the index of the icons the style draws, sprite.png, the sheet they are cut from, and sprite@2x.json and sprite@2x.png, the same at twice the pixel density. A map renderer derives all four from the sprite address of the terrain's style, getTerrainStyle, and fetches the ones the screen needs on its own, so the generated SDKs bind no method for it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
sprite_filestring
in path
The sprite file a map renderer asks for: sprite.json and sprite.png, the index and the sheet of the terrain's icons, or sprite@2x.json and sprite@2x.png, the same at twice the pixel density. A renderer derives all four from the sprite URL of the terrain's style, so read them from there rather than writing them. Any other name is a 400 naming sprite_file.
Response 200
The sprite index (application/json) for a .json file, or the sprite sheet (image/png) for a .png one.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/terrains/{terrain}/{variant}/sources/{terrain_source}/{z}/{x}/{y}Returns one tile of one of the sources a terrain rendition's style draws from, vector or raster, at the given zoom level, x and y coordinates. It is the tiles template every source of getTerrainStyle that fetches tiles carries, under the same terrain and rendition as the style, with the {z}, {x} and {y} placeholders intact, and a map renderer expands and fetches it on its own schedule, so the generated SDKs bind no method for it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
terrain_sourcestring
in path
The identifier of one of the tile sources the rendition's style draws from, as the tiles URL template of that source in the style names it. The set follows the terrains and changes with them, so read it from the style rather than writing it. An identifier the rendition's style does not name is a 404, even when another terrain's style names it.
zinteger (int32)
in path
Zoom level. Higher values show more detail over a smaller area. On a publishable-key request for anything but the base map (a terrain's tiles, the tiles of the sources its style draws and the elevation raster's), the organization's zoom-bounds safety rule narrows the accepted range, and a z outside it is a 400 naming z, so a structurally valid value can still be refused. Each layer's zoom_min and zoom_max in the specification say where a map should ask for tiles; they are not a refusal. A specification served to a publishable key reports them already narrowed to that rule, so a map that follows it asks only for a z the rule accepts.
xinteger (int32)
in path
Tile column index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming x, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
yinteger (int32)
in path
Tile row index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming y, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
Response 200 application/x-protobuf, image/png, image/jpeg, image/webp
The tile: a Mapbox Vector Tile (application/x-protobuf) for a vector source, or a PNG (image/png), JPEG (image/jpeg) or WebP (image/webp) image for a raster one, as the Content-Type header says. A square inside the vector source's range that it holds nothing on, open sea or past the poles, is a zero-length vector tile.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/terrains/{terrain}/{variant}/glyphs/{fontstack}/{glyph_range}Returns the glyphs of one font stack for a block of 256 Unicode code points, as the protocol-buffer glyph format a map renderer draws text with. It is the glyphs template every terrain style, getTerrainStyle, carries, under the same terrain and rendition as the style, and a renderer expands it with the font stack and the code-point range each label needs and fetches it on its own, so the generated SDKs bind no method for it.
Path parameters
terrainstring
in path
Terrain slug, such as topo or winter. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each terrain, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. A slug the catalog does not list is a 404. Every terrain the catalog lists is served to every credential this API takes: a base map carries no organization's data, so no safety rule narrows which terrain is drawn.
variantstring
in path
One of: light, dark
The rendition of the terrain: light for a light color scheme, dark for a dark one. Every terrain the catalog lists publishes both.
fontstackstring
in path
The font stack a style's text layer names under text-font, its fonts joined by commas, as a map renderer puts it in the glyphs URL template of the terrain's style. A rendition publishes a stack when each of its fonts is one the rendition's style names under text-font, or one of the fonts a map renderer asks for a text layer that names none (Open Sans Regular and Arial Unicode MS Regular). A stack naming any other font is a 404, even when another terrain's style names it.
glyph_rangestring
in path
The block of 256 Unicode code points the glyphs are asked for, as a map renderer writes it into the glyphs URL template: its first and last code points joined by a hyphen, with the .pbf extension, such as 0-255.pbf or 256-511.pbf. A block that does not start at a multiple of 256 and end 255 later, or one past 65280-65535.pbf, is a 400 naming glyph_range.
Response 200 application/x-protobuf
The glyph range, as protocol-buffer bytes (application/x-protobuf).
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.
/v1/elevation/tiles.jsonReturns the elevation raster a renderer reads heights out of as a raster-dem source described by a TileJSON document, with the encoding its pixels are decoded with. It is the address the layer catalog answers under elevation.url, so a client reads it from the catalog rather than writing it.
Response 200
The TileJSON document, its tiles template on this API.
Errors 400, 401, 402, 403, 405, 429, 500, 504. See Errors.
/v1/elevation/{z}/{x}/{y}Returns one tile of the elevation raster at the given zoom level, x and y coordinates: an image whose pixels encode height rather than colour, in the encoding the elevation TileJSON document, getElevationTileJson, names. It is that document's tiles template, with the {z}, {x} and {y} placeholders intact, and a map renderer expands and fetches it on its own schedule, so the generated SDKs bind no method for it.
Path parameters
zinteger (int32)
in path
Zoom level. Higher values show more detail over a smaller area. On a publishable-key request for anything but the base map (a terrain's tiles, the tiles of the sources its style draws and the elevation raster's), the organization's zoom-bounds safety rule narrows the accepted range, and a z outside it is a 400 naming z, so a structurally valid value can still be refused. Each layer's zoom_min and zoom_max in the specification say where a map should ask for tiles; they are not a refusal. A specification served to a publishable key reports them already narrowed to that rule, so a map that follows it asks only for a z the rule accepts.
xinteger (int32)
in path
Tile column index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming x, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
yinteger (int32)
in path
Tile row index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming y, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
Response 200 image/webp, image/png
The tile, as a WebP (image/webp) or PNG (image/png) image, as the Content-Type header says.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.