API Reference

API Reference

Concepts and usage patterns for the MaplatApp API exposed by MaplatCore. This page focuses on release-independent explanatory material (ADR-0012). For the complete and up-to-date API signature list, see docs/api/ in the repository.

Table of Contents

• MaplatApp lifecycle
• Option categories
• Usage patterns
• API signature reference
• See Also

---

MaplatApp lifecycle

MaplatApp is the main class for embedding MaplatCore into an application. Its lifecycle has three phases:

1. Initialization — MaplatApp.createObject(option) returns a Promise that resolves when the map data is loaded and the transform is ready. This is the recommended way to create an instance.
2. Running — the instance is interactive: the user can switch maps, toggle layers, view POIs, etc.
3. Destruction — release event listeners, DOM elements, and tile caches.

Why a Promise? MaplatCore must load map definition JSON, compute (or load pre-computed) TIN transforms, and initialize the OpenLayers map before it is ready. The Promise resolves only after all of this is complete.

The lifecycle phases and uiHooks are documented in docs/ui-core-lifecycle.md in the Maplat viewer repository (the lifecycle is shared with @maplat/ui).

Option categories

The option object passed to createObject has several categories of properties:

Category	Key properties	Purpose
Map identity	startFrom	Initial map ID
DOM target	div	Target div ID (default 'map_div')
External tokens	mapboxToken	Access tokens for Mapbox tile services
Vector tile engines	maplibregl, mapboxgl	Injected globals for vector tile rendering

The option object controls runtime behavior. The map and app data (which maps, POIs, styles) are defined in the app JSON file, not in the option. See Concepts for data format details.

Usage patterns

Pattern 1: CDN minimal usage

For a quick embed without a bundler, load OpenLayers and MaplatCore from a CDN. You must load OpenLayers before MaplatCore.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.js"></script>

<script src="https://cdn.jsdelivr.net/npm/@maplat/core@0.13.2/dist/maplat_core.umd.js"></script>

<div id="map_div"></div>
<script>
  MaplatApp.createObject({ startFrom: 'gsi' }).then(function (app) {
    console.log('Maplat initialized');
  });
</script>

Pattern 2: npm ESM import

For a modern bundler-based project, import MaplatApp as an ES module.

import { MaplatApp } from '@maplat/core';
import 'ol/ol.css';

MaplatApp.createObject({ startFrom: 'gsi' }).then((app) => {
  // Application initialized
});

Peer dependency: ol (OpenLayers) v9 or v10 must be installed separately.

Pattern 3: Framework integration

When integrating MaplatCore into a framework (React, Vue, etc.), manage the lifecycle in the component's mount/unmount hooks:

// Pseudocode
onMount: MaplatApp.createObject(option).then(app => { this.app = app; })
onUnmount: this.app.destroy(); // or release per the current API

Do not create multiple MaplatApp instances on the same DOM element. Release the old instance before creating a new one.

API signature reference

The complete API signature list (instance methods for map state, coordinates, markers, lines/vectors, POI layers, GPS, events) is maintained in docs/api/ in the repository. This Wiki page intentionally does not duplicate the signatures to avoid divergence from the source of truth.

See:

• docs/api/ — authoritative API signatures
• README §API reference — overview and links

---

日本語版はこちら / Read this page in Japanese

See Also

• Home
• Concepts — data formats and coordinate transform theory
• Tutorials — usage walkthrough
• README — install and quick start