Skip to content

SmartMaps GL JS

SmartMaps GL JS is the globally usable vector map base to integrate interactive and customizable maps into your web applications. Built on top of MapLibre GL, SmartMaps GL JS provides a powerful and flexible solution for map rendering and location data visualization. Whether you're a beginner or an experienced developer, this documentation will provide you with the knowledge and tools necessary to harness the full potential of SmartMaps GL. You'll find detailed explanations, code examples, and best practices to help you create stunning, interactive maps that enhance your web applications.

Getting Started

To get started with SmartMaps GL JS, you need an API key. Register for free and choose the plan that best suits your requirements.

Next, include the SmartMaps GL JS library in your web page:

<script src="https://cdn.smartmaps.cloud/packages/smartmaps/smartmaps-gl/v2/umd/smartmaps-gl.min.js"></script>

Initializing the Map

Create a container element for the map and initialize a new smartmapsgl.Map instance:

<div id="map"></div>
<script>
    const map = new smartmapsgl.Map({
        apiKey: '[INSERT API-KEY]',
        container: 'map',
        center: { lat: 49.0216, lng: 8.4393 },
        zoom: 12,
        style: smartmapsgl.MapStyle.AUTO
    });
</script>

Map Styles

SmartMaps GL JS offers various predefined map styles:

  • Essential
  • Light
  • Dark
  • Grey
  • Accessible
  • Satellite

For more details, refer to the style documentation.

Controls

Enhance your map with convenient controls:

  • Fullscreen: View the map in fullscreen
  • Geolocation: Determine the user's position
  • Globe: Change map projection to globe view
  • Language: Change language based on user or browser settings
  • Navigation: Zoom and rotation controls
  • Scale Control: Display distances on the map
  • Terrain: Activate 3D-terrain and hillshading

Markers and Popups

  • Markers: Place custom markers at specific positions
  • Popups: Display information when clicking on markers or map features

Data Sources

Supported data sources for versatile map rendering:

  • GeoJSON: Load and display GeoJSON data
  • Vector Tiles: Efficient rendering of vector tiles
  • Raster Tiles: Integrate raster tile layers
  • Image Overlays: Add static images as overlays

Layers and Styles

Customize the appearance of the map with layers and styles:

  • Custom Layers: Create your own layers for data visualization
  • Layer Filters: Show or hide features based on attributes
  • Style Specification: Customize the visual appearance using the MapLibre style specification

Integration

Simple Map

This example demonstrates how to load a map into a DIV container. The center coordinate together with the zoom level determines the map section. Simply copy the code into your application and add your API key.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <script src="https://cdn.smartmaps.cloud/packages/smartmaps/smartmaps-gl/v2/umd/smartmaps-gl.min.js"></script>
        <style>
            html,
            body {
                height: 100vh;
                margin: 0;
                padding: 0;
            }
            #map {
                height: 100%;
            }
        </style>   
    </head>

    <body>
        <div id="map"></div>
        <script>
            const map = new smartmapsgl.Map({
                apiKey: "[INSERT API-KEY]",
                container: "map",
                center: { lat: 49.021, lng: 8.4393 },
                zoom: 12,
                style: smartmapsgl.MapStyle.LIGHT
            });
        </script>
    </body>
</html>

With SmartMaps GL JS, developers can easily create dynamic and interactive maps. Whether you are building a simple map or a complex geospatial application, SmartMaps GL JS provides you with the necessary tools for effective map integration.

Integration with other GL libraries

SmartMaps enables seamless integration with popular mapping libraries. Below are examples demonstrating how to use Leaflet, MapLibre GL, and OpenLayers with SmartMaps styles.

Use the tabs below to explore integration with Leaflet, MapLibre GL, and OpenLayers.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link
      rel="stylesheet"
      href="https://cdn.smartmaps.cloud/packages/leaflet/leaflet-1.9.4.css"
    />
    <script src="https://cdn.smartmaps.cloud/packages/leaflet/leaflet-1.9.4.min.js"></script>
    <style>
      #map { height: 400px; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = L.map('map').setView([51.1657, 10.4515], 6);

      L.tileLayer(
        'https://tiles.smartmaps.cloud/tiles/v1/smartmaps/light/{z}/{x}/{y}.webp?apiKey=[INSERT API-KEY]',
        { attribution: '© <a href="https://smartmaps.net/copyright" target="_blank">SmartMaps</a> | © <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap contributors</a>' }
      ).addTo(map);
    </script>
  </body>
</html>

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script src="https://cdn.smartmaps.cloud/packages/maplibre-gl/5.1.1/maplibre-gl.js"></script>
    <link
      href="https://cdn.smartmaps.cloud/packages/maplibre-gl/5.1.1/maplibre-gl.css"
      rel="stylesheet"
    />
    <style>
      #map { height: 400px; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/style.json?apiKey=[INSERT API-KEY]',
        center: [10.4515, 51.1657],
        zoom: 6
      });
    </script>
  </body>
</html>

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>SmartMaps GL - OpenLayers Demo</title>
    <meta charset="UTF-8" />
    <style>
      html,
      body,
      #map {
        font-family: sans-serif;
        margin: 0;
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script type="module" src="index.js"></script>
  </body>
</html>

index.js

import "ol/ol.css";
import { apply as applyMapboxStyle } from "ol-mapbox-style";
import Map from "ol/Map";
import View from "ol/View";
import { useGeographic as olUseGeographic } from "ol/proj";
import {
  DragRotateAndZoom,
  defaults as defaultInteractions
} from "ol/interaction.js";

// Enable geographic coordinates
olUseGeographic();

const center = [10.4515, 51.1657]; // Centering on Germany

// Initialize the map
const map = new Map({
  interactions: defaultInteractions().extend([new DragRotateAndZoom()]),
  view: new View({
    center: center,
    zoom: 6
  }),
  target: "map"
});

// Apply SmartMaps GL style
applyMapboxStyle(
  map,
  "https://tiles.smartmaps.cloud/tiles/v1/smartmaps/light/style.json?apiKey=[INSERT API-KEY]"
);

package.json

{
  "name": "smartmaps-openlayers-demo",
  "version": "1.0.0",
  "description": "SmartMaps GL - OpenLayers Demo",
  "main": "index.html",
  "scripts": {
    "start": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "ol": "10.3.0",
    "ol-mapbox-style": "12.3.5",
    "vite": "6.0.2"
  },
  "devDependencies": {
    "@babel/core": "7.26.0",
    "typescript": "5.7.2"
  },
  "resolutions": {
    "@babel/preset-env": "7.26.0"
  },
  "keywords": ["javascript", "smartmaps", "openlayers"]
}

SmartMaps GL Integration with GIS Software

SmartMaps GL provides seamless integration with popular GIS tools such as QGIS and ArcGIS Online, enabling advanced visualization and overlay of vector tile layers. Follow the instructions below to integrate SmartMaps into your preferred GIS environment.

GIS Integration Examples

QGIS natively supports vector tile services from version 3.16 onward. However, due to incomplete support for Mapbox specifications, there may be discrepancies in rendering (e.g., hillshading and zoom-level content).

Steps to Integrate SmartMaps GL in QGIS:

  1. Open QGIS (version 3.16 or later).

  2. Navigate to:

    • Layer > Add layer > Add Vector Tile Layer
    • Click New > New Generic Connection
    • Name: SmartMaps GL - Light
    • URL: https://tiles.smartmaps.cloud/tiles/v1/smartmaps/{z}/{x}/{y}.pbf?apiKey=[INSERT API-KEY]
    • Style URL: https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/style.json?apiKey=[INSERT API-KEY]
    • Click OK

  3. Replace [INSERT API-KEY] with your actual SmartMaps API key.

  4. Add the vector tile layer to your project and adjust styles as needed.

Font Configuration

To ensure proper text rendering, install these fonts: -- Noto Sans Regular -- Noto Sans Bold

Download them from Google Noto Fonts.

ArcGIS Online and ArcGIS Enterprise Portal (version 11.1 or later for Windows) support SmartMaps GL styles for vector tile layers. Follow these steps to integrate:

  1. Save the JSON Style: Download the desired SmartMaps GL style file:

  2. https://tiles.smartmaps.cloud/styles/v1/smartmaps/light/style.json?apiKey=[INSERT API-KEY]

  3. Duplicate a Vector Tile Layer: Copy and save a hosted vector tile layer in ArcGIS Online or ArcGIS Enterprise.

  4. Update the Style: On the Item Details page of the duplicated layer, use the Update option to replace the existing style with the saved SmartMaps GL JSON style.

  5. Use the Updated Layer: The updated layer can now be added to the ArcGIS Map Viewer as a layer or basemap.

Events

SmartMaps GL JS supports various events to handle user interactions and map state changes:

  • load: Fired when the map has finished loading
  • click: Fired when the user clicks on the map
  • mousemove: Fired when the user moves the mouse over the map
  • mouseenter: Fired when the mouse enters the map container
  • mouseleave: Fired when the mouse leaves the map container
  • zoom: Fired when the map zoom level changes
  • zoomstart: Fired when a zoom animation starts
  • zoomend: Fired when a zoom animation ends
  • rotate: Fired when the map rotation changes
  • rotatestart: Fired when a rotation animation starts
  • rotateend: Fired when a rotation animation ends
  • drag: Fired repeatedly during a "drag to pan" interaction
  • dragstart: Fired when a "drag to pan" interaction starts
  • dragend: Fired when a "drag to pan" interaction ends

Browser Support

SmartMaps GL JS supports all browsers that support WebGL:

  • Chrome
  • Firefox
  • Safari
  • Edge

For optimal performance and functionality, we recommend using the latest versions of these browsers.

Support and Feedback

If you have any questions, issues, or feedback regarding SmartMaps GL JS, please contact our support team at maps@yellowmap.de. We are here to help you with your mapping needs.

Happy mapping with SmartMaps GL JS!