Quick start
To start using MapGL JS API:
- Get an access key.
- Add the MapGL JS API library to your project.
- Initialize the map.
- (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:
- Sign in to the Platform Manager.
- 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.
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
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',
});
});
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 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>
What's next?
- Apply additional settings for more convenient interaction with the map.
- Configure the look of the map and the rules of rendering objects using styles.
- Add individual objects to the map or connect a data source with a set of objects.