Get started with maps

The Maps SDK for TypeScript delivers powerful mapping capabilities, enabling developers to effortlessly integrate dynamic map views into their web applications. Core features include embedding and customizing map views, controlling displayed locations, and fine-tuning map properties. At the center of the mapping API is the GemMap class, offering a wide range of configurable options.

Display a map

The following code demonstrates how to show a map view in a web application.

HTML Structure

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello Map</title>
    <style>
        body, html {
            margin: 0;
            padding: 0;
            width: 100%;
            height: 100%;
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
        }
        #app-container {
            width: 100%;
            height: 100%;
            display: flex;
            flex-direction: column;
        }
        #app-bar {
            background-color: #4a148c;
            color: white;
            padding: 16px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.2);
        }
        #map-container {
            flex: 1;
            position: relative;
        }
    </style>
</head>
<body>
    <div id="app-container">
        <div id="app-bar">
            <h1 style="margin: 0; font-size: 20px;">Hello Map</h1>
        </div>
        <div id="map-container"></div>
    </div>
    <script type="module" src="/src/main.ts"></script>
</body>
</html>

TypeScript Code

import { GemKit, GemMap } from '@magiclane/maps-sdk';

const projectApiToken = import.meta.env.VITE_MAGICLANE_API_TOKEN;

async function initializeMap() {
    try {
        // Initialize GemKit
        const gemKit = await GemKit.initialize(projectApiToken);
        
        // Get the map container element
        const container = document.getElementById('map-container');
        if (!container) {
            throw new Error('Map container not found');
        }
        
        // Create the map view
        const viewId = 1;
        const wrapper = gemKit.createView(viewId, onMapCreated);
        
        if (wrapper) {
            container.appendChild(wrapper);
        }
    } catch (error) {
        console.error('Failed to initialize map:', error);
    }
}

function onMapCreated(gemMap: GemMap) {
    // Code executed when the map is initialized
    console.log('Map created successfully!');
    
    // Access map controller for additional functionalities
    // You can now use gemMap to control the map
}

// Initialize when the DOM is ready
if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', initializeMap);
} else {
    initializeMap();
}

The createView method includes a callback, onMapCreated, which is triggered once the map has finished initializing. It provides a GemMap instance to enable additional map functionalities.

const wrapper = gemKit.createView(viewId, onMapCreated);

tip

Multiple map views can be instantiated within a single application, allowing for the display of different data on each map. Each map view is independently controlled via its respective GemMap instance.

Note that certain settings, such as language, overlay visibility, and position tracking, are shared across all map instances within the application.

Working with the Map Controller

Once the map is created, you can use the GemMap instance to control various aspects of the map:

import { Coordinates } from '@magiclane/maps-sdk';

function onMapCreated(gemMap: GemMap) {
    // Set map center
    const center = new Coordinates({ latitude: 48.858844, longitude: 2.294351 }); // Eiffel Tower
    gemMap.centerOnCoordinates(center);
    
    // Set zoom level
    gemMap.setZoomLevel(15, {});
}

Cleanup

When your application unmounts or the map view is no longer needed, make sure to properly clean up resources:

// When you're done with GemKit (e.g., on page unload)
window.addEventListener('beforeunload', () => {
    GemKit.release();
});

Next Steps

Now that you have a basic map displayed, you can explore:

Adjusting map view properties (zoom, center, tilt)
Handling user interactions and gestures
Adding markers and overlays
Implementing custom map styles

Display a map​

HTML Structure​

TypeScript Code​

Working with the Map Controller​

Cleanup​

Next Steps​