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. Add the MapGL JS API library to your project.
  3. Initialize the map.
  4. (Optional) Add an object to the map (for example, a marker).

1. Get an access key​

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 a subscription for using API.

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

2. Install the library​

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​

If you use npm, you can 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',
    });
});

If you want to use the MapGL JS API installed in the On-Premise environment, additionally specify the service address. Example:

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

Note

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

3. Initialize the 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,
});

4. Add 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 the playground (no authorization needed).


What's next?​