Usage scenarios
If you are using MapGL JS API for the first time, learn about primary components of the map architecture and examples of using the map.
Map architecture
Architecture of the MapGL JS API map consists of two main components: data and styles.
Data is all information that can be displayed on the map: buildings, roads, water objects, borders, and more.
Data for MapGL JS API can be provided in two ways:
- As separate, self-contained geoobjects: points, lines, polygons.
- As tiles: square areas that each contain information about a set of objects in this area. Tiles can be provided in vector and raster formats.
Styles are rules of displaying map data that define which data and in which order to render. No data appears on the map if its style is not defined.
You can either work with prepared Urbi data or upload your data to enrich information on the map. To upload user data, use any of the following ways:
-
Add dynamic objects to the map one by one (for example, a group of markers, a label, or a polyline). This may be useful if you need to place a small number of objects on the map and flexibly manage them.
Style and geometry for each object are defined separately: for example, you can set a unique icon for each marker.
-
Connect a data source (GeoJSON or a WMS/WMTS raster source) that will overlay the map. This may be useful if the data set is large and does not require frequent updates.
Styles of objects from a data source are defined via style layers. You can also add or change them in runtime using map methods (style specification) or the Style editor. For details, see the Styles chapter.
Examples of map usage
Map as underlay
Follow this scenario if Urbi data is enough for your goals, but you need to configure the map look. Example: show intercity roads only and highlight them with a specific color or configure the light and dark theme for your map.
Steps:
- Initialize the map.
- Configure the display of required layers in the Style editor.
Example of a map without user data with styles configured for the light and dark themes:
<!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="Style apply in runtime example" />
<style>
html,
body,
#container {
margin: 0;
width: 100%;
height: 100%;
overflow: hidden;
font-family: Helvetica, Arial, sans-serif;
}
#dark_theme, #light_theme {
margin: 0 10px 10px;
padding: 3px 12px;
background: #3b3b3b;
color: #fff;
border: none;
}
</style>
</head>
<body>
<div>
Click to switch theme:
<button id="dark_theme">Switch to dark theme 🌙</button>
<button id="light_theme">Switch to light theme 🌞</button>
</div>
<div id="container"></div>
<script src="https://mapgl.2gis.com/api/js/v1"></script>
<script>
const map = new mapgl.Map('container', {
center: [55.187609, 25.141736],
styleZoom: 16,
pitch: 40,
rotation: -45,
key: 'Your API access key',
});
document.getElementById('dark_theme').addEventListener('click', function() {
map.setStyleById('e05ac437-fcc2-4845-ad74-b1de9ce07555');
});
document.getElementById('light_theme').addEventListener('click', function() {
map.setStyleById('c080bb6a-8134-4993-93a1-5b4d8c36a59b');
});
</script>
</body>
</html>
Map + single objects
Follow this scenario if you need to add a set of custom objects to the Urbi map. Example: show spots where new facilities will be opened in the future and set a unique icon for each.
Steps:
- Initialize the map.
- Add dynamic objects and configure the style of each.
- If needed, additionally configure the look of the map underlay in the Style editor, like in the scenario above.
Example of a map with separately added markers:
<!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="Several markers example" />
<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',
});
const coords = [
[55.27414804174869, 25.257576991034284],
[55.289254243403306, 25.211614202468652],
[55.34418588368302, 25.215341562259866],
[55.35036569359612, 25.26068195798851],
[55.32976632814914, 25.238324424362062],
];
coords.forEach((coord) => {
const marker = new mapgl.Marker(map, {
coordinates: coord,
});
});
</script>
</body>
</html>
Map + data source
Follow this scenario if you need to add a data source with a set of complex data to the map. Example: overlay the Urbi map with a cadastral plan or display some external data as a heatmap.
Steps:
-
Add a data source.
You can also add independent dynamic objects to the map, if needed.
-
Configure the style of displaying data by defining style layers in the style specification or the Style editor.
-
If needed, additionally configure the look of the map underlay in the Style editor.
Example of a map with a connected GeoJSON source and its style configured as a heatmap:
<!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="Heatmap layer example" />
<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.425, 25.355],
zoom: 10,
key: 'Your API access key',
});
const data = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
properties: { customProperty: 1 },
geometry: {
type: 'MultiPoint',
coordinates: [
[55.44, 25.34],
[55.43, 25.37],
[55.41, 25.34],
],
},
},
{
type: 'Feature',
properties: { customProperty: 2 },
geometry: {
type: 'Point',
coordinates: [55.4, 25.3],
},
},
],
};
const source = new mapgl.GeoJsonSource(map, {
data,
attributes: {
purpose: 'heatmap',
},
});
const layer = {
id: 'my-heatmap-layer', // Each layer ID must be unique
// Data filtering logic
filter: [
'match',
['sourceAttr', 'purpose'],
['heatmap'],
true, // Result if value of purpose source attribute equals "heatmap"
false, // Result if not
],
// Drawing object type
type: 'heatmap',
// Style of drawing object
style: {
color: [
'interpolate',
['linear'],
['heatmap-density'],
0,
'rgba(0, 0, 0, 0)',
0.2,
'rgba(172, 32, 135, 1)',
0.4,
'rgba(255, 154, 0, 1)',
0.6,
'rgba(255, 252, 0, 1)',
0.8,
'rgba(255, 255, 63, 1)',
1,
'rgba(255, 255, 255, 1)',
],
radius: 50,
weight: ['get', 'customProperty'],
intensity: 0.8,
opacity: 0.8,
downscale: 1,
},
};
map.on('styleload', () => {
map.addLayer(layer);
});
</script>
</body>
</html>