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 get an access key for using API:

  1. Sign in to the Platform Manager.
  2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.

In the Platform Manager, you can also:

  • See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
  • Set restrictions for a key by HTTP headers or by IP and subnet.
  • Check the statistics of request distribution for each key.
  • Interact with a ready-made 3D map in a playground.

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>