Raster WMS/WMTS sources

The MapGL JS API allows you to display data from external raster sources, so you can add layers of various geographical objects, hillshade, satellite images, and other data to the map. To do this, you need to connect RasterTileSource and add a layer to the map style for this source. RasterTileSource allows you to request tiles both by bounding box (Web Map Service — WMS), and by their coordinates in the tile matrix (Web Map Tile Service — WMTS).

WMS

WMS is a standard developed by the OGC (Open Geospatial Consortium) which allows you to dynamically retrieve geographic data as an image (PNG, JPEG, GIF, etc.) binded to a location. The image construction is based on the parameters passed in the user's request: geographic coordinates (bounding box), format, and size. WMS allows you to obtain data images by layers and also to make the background of the final image transparent — this provides the ability, for example, to overlap layers obtained from different servers. For customization, you can specify styles for data layers in the request.

To connect a WMS data source, use the following code example:

const source = new mapgl.RasterTileSource(map, {
    url: (_x, _y, _zoom, bbox) => {
        const southWest = bbox.southWest.map((c) => String(c).replace(',', '.')).join(',');
        const northEast = bbox.northEast.map((c) => String(c).replace(',', '.')).join(',');
        return `https://ows.terrestris.de/osm/service?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=OSM-Overlay-WMS&HEIGHT=256&WIDTH=256&SRS=EPSG:3857&STYLES=&BBOX=${southWest},${northEast}`;
    },
    attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    attributes: { bar: 'asd' },
});

Note

The bbox function argument from the url option in RasterTileSourceOptions should contain coordinate values in the EPSG:3857 projection (Web Mercator, Pseudo-Mercator).

To make the source different from the others, you need to add a unique property via the attributes field - after that, you can link it to a new layer of the map style, and therefore display it.

Remember that most services require to specify the copyright. You can do this via the attribution field.

WMTS

WMTS is a standard also developed by OGC. It shares the work logic with WMS, but is designed for performance and scalability: a user gets pre-prepared or cached images of size 256 or 512 pixels, which does not require manipulations with them or processing of geographic data.

To connect a WMTS data source, use the following code example:

const source = new mapgl.RasterTileSource(map, {
    url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,
    attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    attributes: { bar: 'asd' },
});

Note

To make the source different from the others, you need to add a unique property via the attributes field — after that, you can link it to a new layer of the map style, and therefore display it.

Remember that most services require to specify the copyright. You can do this via the attribution field.

Adding a layer to the map style

The map style is a config that describes map data rendering. The style consists of layers each of which contains:

filter — the field that defines the logic of filtering the map data to determine which data this layer will render;
style — the field that defines the appearance of objects for rendering (color, width, font, etc.).

You can learn more about the map style in Style Specification.

First, create a new layer:

const layer = {
    id: 'raster-tile-layer', // Each layer ID must be unique

    // The logic of filtering or selecting data for this layer
    filter: [
        'match',
        ['sourceAttr', 'bar'],
        ['asd'],
        true, // Value when the "bar" attribute of the source matches the "asd" value
        false, // Value in case of mismatch
    ],

    // Type of an object being rendered
    type: 'raster',

    // Style of an object being rendered
    style: {
        opacity: 1,
    },
};

Then add a layer after loading the style:

map.on('styleload', () => {
    map.addLayer(layer);
});

filter uses the following expressions:

SourceAttrExpression — to get values from the bar property of the data source;
MatchExpression — to match the property obtained from the bar attribute with the asd string value.

Example of RasterTileSource working with the WMS standard:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="RWMS example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.425, 25.355],
                zoom: 13,
                key: 'Your API access key',
            });

            const source = new mapgl.RasterTileSource(map, {
                url: (_x, _y, _zoom, bbox) => {
                    const southWest = bbox.southWest.map((c) => String(c).replace(',', '.')).join(',');
                    const northEast = bbox.northEast.map((c) => String(c).replace(',', '.')).join(',');
                    return `https://ows.terrestris.de/osm/service?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&TRANSPARENT=true&LAYERS=OSM-Overlay-WMS&HEIGHT=256&WIDTH=256&SRS=EPSG:3857&STYLES=&BBOX=${southWest},${northEast}`;
                },
                attribution:
                    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',

                // Source attribute for data filtering logic
                attributes: { bar: 'asd' },
            })

            const layer = {
                // Type of object being rendered
                type: 'raster',

                // Each layer ID must be unique
                id: 'raster-tile-layer',

                // Data filtering logic
                filter: [
                    'match',
                    ['sourceAttr', 'bar'], // Match with attribute from data source
                    ['asd'],
                    true, // Value when the "bar" attribute of the source matches the "asd" value
                    false // Value in case of mismatch
                ],
                // Styles of object being rendered
                style: {
                    opacity: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer);
            });
        </script>
    </body>
</html>

Example of RasterTileSource working with WMTS standard:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="WMTS example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.425, 25.355],
                zoom: 13,
                key: 'Your API access key',
            });

            const source = new mapgl.RasterTileSource(map, {
                url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,
                attribution:
                    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',

                // Source attribute for data filtering logic
                attributes: { bar: 'asd' },
            })

            const layer = {
                // Type of object being rendered
                type: 'raster',

                // Each layer ID must be unique
                id: 'raster-tile-layer',

                // Data filtering logic
                filter: [
                    'match',
                    ['sourceAttr', 'bar'], // Match with attribute from data source
                    ['asd'],
                    true, // Value when the "bar" attribute of the source matches the "asd" value
                    false // Value in case of mismatch
                ],
                // Style of object being rendered
                style: {
                    opacity: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer);
            });
        </script>
    </body>
</html>