Skip to content
Add a Raster Tile Source

Add a Raster Tile Source in MapLibre GL JS

On this page

A raster tile source adds images from any XYZ tile service to a Maptoolkit vector map. This example adds aerial imagery of Austria from basemap.at and places it below the map labels, so street and place names stay readable on top of the photo.

import * as maplibregl from "maplibre-gl";
    import { LogoControl } from "https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.js";

    const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
        container: 'map',
        style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
        center: [13.0453, 47.7985],
        zoom: 15,
        attributionControl: { compact: false }
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');

    map.on('load', () => {
        const firstSymbolId = map.getStyle().layers.find((layer) => layer.type === 'symbol')?.id;

        map.addSource('aerial', {
            type: 'raster',
            tiles: ['https://mapsneu.wien.gv.at/basemap/bmaporthofoto30cm/normal/google3857/{z}/{y}/{x}.jpeg'],
            tileSize: 256,
            maxzoom: 19,
            bounds: [9.52, 46.37, 17.16, 49.02],
            attribution: 'Datenquelle: <a href="https://basemap.at/">basemap.at</a>'
        });

        map.addLayer({
            id: 'aerial',
            type: 'raster',
            source: 'aerial'
        }, firstSymbolId);
    });

    map.addControl(new LogoControl({ variant: "com" }));
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Add a Raster Tile Source - MapLibre GL JS</title>
    <meta property="og:description" content="Add an external raster tile source below the labels of the map." />
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- MapLibre GL JS 6 is an ES module. The import map tells the browser
         where to load "maplibre-gl" from. -->
    <script type="importmap">
      {
        "imports": {
          "maplibre-gl": "https://cdn.jsdelivr.net/npm/maplibre-gl@6.16.0/dist/maplibre-gl.mjs"
        }
      }
    </script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.16.0/dist/maplibre-gl.css" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.css" />
    <style>
        html, body { width: 100%; height: 100%; margin: 0; padding: 0; }
        #map { width: 100%; height: 100%; }
    </style>
</head>
<body>
<div id="map"></div>
<script type="module">
    import * as maplibregl from "maplibre-gl";
    import { LogoControl } from "https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.js";

    const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
        container: 'map',
        style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
        center: [13.0453, 47.7985],
        zoom: 15,
        attributionControl: { compact: false }
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');

    map.on('load', () => {
        const firstSymbolId = map.getStyle().layers.find((layer) => layer.type === 'symbol')?.id;

        map.addSource('aerial', {
            type: 'raster',
            tiles: ['https://mapsneu.wien.gv.at/basemap/bmaporthofoto30cm/normal/google3857/{z}/{y}/{x}.jpeg'],
            tileSize: 256,
            maxzoom: 19,
            bounds: [9.52, 46.37, 17.16, 49.02],
            attribution: 'Datenquelle: <a href="https://basemap.at/">basemap.at</a>'
        });

        map.addLayer({
            id: 'aerial',
            type: 'raster',
            source: 'aerial'
        }, firstSymbolId);
    });

    map.addControl(new LogoControl({ variant: "com" }));
</script>
</body>
</html>

Use the prompt below with any LLM to get the same result. Make sure the Maptoolkit MCP server is connected first — check out AI Integration & MCP to get started.

Use the Maptoolkit MCP. Create an interactive map with zoom level 15, centered around [13.0453, 47.7985]. Add the basemap.at aerial imagery (https://mapsneu.wien.gv.at/basemap/bmaporthofoto30cm/normal/google3857/{z}/{y}/{x}.jpeg) as a raster layer below the first label layer, with the attribution “Datenquelle: basemap.at”.

How it works

The map loads the Summer style from the Vector Tiles API. After the style loads, the example adds a raster source and a raster layer for the imagery.

Source optionValue in this exampleWhy
tilesbasemap.at URL templateThe service uses {z}/{y}/{x}, not the more common {z}/{x}/{y}. Check the order in the documentation of each service.
tileSize256Must match the pixel size of the images the service returns. A wrong value shows blurry or tiny images.
maxzoom19The highest zoom level the service provides. At higher zoom levels, MapLibre GL JS scales up the level 19 tiles instead of requesting tiles that do not exist.
boundsAustriabasemap.at covers Austria only. Outside these bounds, the map does not request any tiles.
attributionDatenquelle: basemap.atRaster tiles do not include an attribution. The text you set here appears in the attribution control next to the Maptoolkit and OpenStreetMap credits. basemap.at requires this text under its CC BY 4.0 license.

The second argument of addLayer is the ID of an existing layer. The new layer is drawn below that layer. The example passes the first symbol layer of the style, so the imagery covers the roads and areas of the Summer style, and the labels stay on top. Without this argument, the imagery would cover the labels too.

When you zoom out, white areas appear next to the Austrian border. basemap.at serves JPEG images, and JPEG has no transparency: in tiles along the border, the area outside Austria is filled white. Further away from the border, the service sends no tiles, so the Summer map shows there. A service that serves transparent PNG tiles does not have this problem.

Any XYZ tile service works the same way, for example historical maps, weather radar or your own tiles. Check the license of a service before you use it.

Next steps