Style zoom

Consider one little piece from a style object:

{
    type: 'polygon',
    id: 'background',
    filter: ['match', ['get', 'sublayer'], ['s_region'], true, false],
    style: {
        color: [
            'interpolate', ['linear'], ['zoom'],
            9, 'hsl(50, 61%, 90%)',
            12, 'hsl(51, 37%, 90%)',
            14, 'hsl(49, 48%, 91%)',
            16, 'hsl(51, 51%, 92%)',
        ],
    },
},

This object describes the background color for data with the "sublayer" field equal to s_region. Please note the code snippet below:

color: [
    'interpolate', ['linear'], ['zoom'],
    9, 'hsl(50, 61%, 90%)',
    12, 'hsl(51, 37%, 90%)',
    14, 'hsl(49, 48%, 91%)',
    16, 'hsl(51, 51%, 92%)',
],

This array describes how the background color depends on zoom. But it is not an ordinary zoom level, which you can set in map options, it is styleZoom. The styleZoom and zoom options set the same map scale but in different projections. And styleZoom value is used in styles.

You can set styleZoom in map options if you want to set the same zoom that is used in the style settings. If both options are set (zoom and styleZoom), the styleZoom has a higher priority than the zoom option. If you need to set/get styleZoom in runtime, you can use setStyleZoom and getStyleZoom methods.

There is an example, where you can see the difference between zoom and styleZoom:

<!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="Style zoom example" />
        <style>
            html,
            body {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
                font-family: Helvetica, Arial, sans-serif;
            }
            #container_1, #container_2 {
                height: 250px;
                width: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <h2>Map with zoom option equal to 16</h2>
        <div id="container_1"></div>
        <h2>Map with styleZoom option equal to 16</h2>
        <div id="container_2"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            let key = 'Your API access key';
            const map_1 = new mapgl.Map('container_1', {
                center: [55.190803, 25.141451],
                zoom: 16,
                pitch: 40,
                rotation: -90,
                key,
            });
            const map_2 = new mapgl.Map('container_2', {
                center: [55.190803, 25.141451],
                styleZoom: 16,
                pitch: 40,
                rotation: -90,
                key,
            });
        </script>
    </body>
</html>

When you need zoom and when styleZoom

styleZoom introduced to compensate Mercator projection distortions. It makes map objects appear with the same scale on different latitudes.

Use zoom if you want to work with map scale. Map scale will be the same near the Arctic circle and on the equator.

Use styleZoom if you want to work precisely with zoom boundaries in styles. Usually, this is the case when you develop map style with the map Style editor and need to ensure that certain zoom-bounded objects will be visible.

By default, the zoom option is used.