MapGL JS API Overview | 2GIS Documentation
MapGL JS API

MapGL JS API Overview

MapGL JS API is a JavaScript library that allows you to add a 2GIS map to your website or web application.

The features include:

Geodata complies with OGC standards.

Important

Use only MapGL JS API methods and fields described in the documentation. Stable operation of undocumented functionality is not guaranteed.

To work with the API of the service, you need to get an access key:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase an access key for using API: see the Access keys instruction.

To work with access keys, you can use the Platform Manager: see the Platform Manager section.

To add MapGL JS API to your project, use the following line:

<script src="https://mapgl.2gis.com/api/js/v1"></script>

The script will add a global variable called mapgl. See the API Reference for the full list of available methods of that variable.

Alternatively you can use npm package @2gis/mapgl.

import { load } from '@2gis/mapgl';
// or const { load } = require('@2gis/mapgl');

load().then((mapglAPI) => {
    const map = new mapglAPI.Map('container', {
        center: [55.31878, 25.23584],
        zoom: 13,
        key: 'Your API access key',
    });
});

To load the map asynchronously, you can use the async and defer script attributes. You can specify the function that will be called when the script has finished loading by using the callback parameter in the URL.

<script src="https://mapgl.2gis.com/api/js/v1?callback=initMap" async defer></script>
<script>
    function initMap() {
        const map = new mapgl.Map('container', {
            center: [55.31878, 25.23584],
            zoom: 13,
            key: 'Your API access key',
        });
    }
</script>

In case of system.js you can use System.import:

System.import('https://mapgl.2gis.com/api/js/v1').then((mapgl) => {
    const map = new mapgl.Map('container', {
        center: [55.31878, 25.23584],
        zoom: 13,
        key: 'Your API access key',
    });
});

To display a map, you need to add an HTML element that will act as a container for the map:

<div id="container"></div>

Since the map will be placed inside the container, you also need to specify the size of that container:

<style>
    #container {
        width: 500px;
        height: 300px;
    }
</style>

After that, you need to initialize the map. To do that, call the Map() method passing the id of the container and your API key. You can also pass the initial coordinates and the required zoom level. See the API Reference for the full list of map options.

const map = new mapgl.Map('container', {
    key: 'Your API access key',
    center: [55.31878, 25.23584],
    zoom: 13,
});

To add a Marker to the map, call the Marker() method and pass the name of the map instance and coordinates of the marker:

const marker = new mapgl.Marker(map, {
    coordinates: [55.31878, 25.23584],
});

See the API Reference for more information on marker initialization options.

You can also interact with a ready-made map in a playground.

<!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="Quickstart with 2GIS Map API" />
        <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.31878, 25.23584],
                zoom: 13,
                key: 'Your API access key',
                style: 'c080bb6a-8134-4993-93a1-5b4d8c36a59b'
            });
            const marker = new mapgl.Marker(map, {
                coordinates: [55.31878, 25.23584],
            });
        </script>
    </body>
</html>