Raster tiles | MapGL | 2GIS Documentation
MapGL JS API

Raster tiles

To show raster tiles on the map, you need to add:

  1. a source with the tiles to the map;
  2. a layer to a map style to describe tiles appearance.

To add a tiles source to a map, you need to use RasterTileSource:

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' },
});

To distinguish it from other data, you should add a unique attribute for it in attributes field. Now the raster tiles can be associated with a new map style layer and therefore drawn.

Note that most tile servers require attribution, which you can set in attribution field.

A map style is a config that describes map data appearance. The style contains layers. Each layer contains:

  • filter field — to describe a data filtering logic to determine which data will be drawn by this layer;
  • style field — to describe the appearance of the drawing objects (color, width, font, etc.).

You can find more information about the map style in Style Specification.

At first, create a new layer:

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

    // Data filtering logic
    filter: [
        'match',
        ['sourceAttr', 'bar'],
        ['asd'],
        true, // Result if value of bar source attribute equals "asd"
        false, // Result if not
    ],

    // Drawing object type
    type: 'raster',

    // Style of drawing object
    style: {
        opacity: 1,
    },
};

Then add the layer after loading the style:

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

Here in filter we use:

  • SourceAttrExpression — to get values from bar source attribute;
  • MatchExpression — to match the values with string "asd".
<!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="Raster source 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`,

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

            const layer = {
                // Drawing object type
                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, // Result if value of bar source attribute equals "asd"
                    false // Result if not
                ],
                // Style of drawing object
                style: {
                    opacity: 1,
                },
            };

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