Skip to main content

Quick start

To start using MapGL JS API, check the basic usage scenarios and follow the steps below:

  1. Get an access key.
  2. Install the MapGL JS API library in your project.
  3. Initialize the map.
  4. (Optional) Add a marker to the map.

1. Get an access key​

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase a subscription for using the Map Tiles API service, which provides access to vector map tiles. For details on service prices, see the Tariffs section.

Note

If you already have an active API key obtained for the MapGL JS API, you can use it to access the Map Tiles API until the subscription expires. You can view the subscription expiration date in the Platform Manager, on the Dashboard tab.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Install library​

Using script tag​

Add the following line in your HTML page code:

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

The script will add a global variable called mapgl. For the full list of available methods of the variable, see the API Reference.

Using npm package​

If you use npm, install the library using the @2gis/mapgl package:

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

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

To use the MapGL JS API installed in the On-Premise environment, additionally specify the service address:

load('http://mapgl-js-api.example.com/api/js').then((mapgl) => {
    const map = new mapgl.Map('container', {
        center: [55.31878, 25.23584],
        zoom: 13,
        key: 'Your API access key',
    });
});

Using async callback​

To load the map asynchronously, specify the async and defer script attributes. In the callback parameter of the query string, specify the name of the function that will be called after the library is loaded:

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

Note

You can also use MapGL JS API in your React projects.

3. Initialize map​

To display the map on the page, add an HTML element that will be used as a container:

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

Specify the size of the container for the map:

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

To initialize the map, call the Map() method, specify the container ID and your API key. You can also specify the initial coordinates and the required zoom level:

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

For the full list of map options, see the API Reference.

4. Add marker​

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

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

For the full list of marker options, see the API Reference.

Usage example​

You can also interact with a ready-made map in the playground (no authorization needed).

What's next?​