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.

Key features

The features include:

• Add a 3D WebGL map with geodata to your website or to your web application.
• Rotate, pitch, and zoom the map using a mouse or finger gestures.
• Display floor plans for shopping centers and airports.
• Customize the appearance of the map using Map Styles Editor including 3D models and terrain.
• Display single markers and marker clusters.
• Display text labels and draw custom shapes like circles and polygons.
• Calculate and display car and pedestrian routes.
• Add tooltips and popups for map objects.
• Customize the set of map control buttons and add your own.
• Work with GeoJSON.

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.

Getting an access key

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.

Installation

Using script tag

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.

Using npm package

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

Using async callback

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>

Using system.js

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

Getting started

Creating a map

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

Adding a marker

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.

Full code example

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