Legacy v2 API reference

Archived. This page is the v2 API surface as it was, preserved for customers still running v2 (2.x) in production who need a lookup reference. Do not use as a guide for new integrations — build against the current release, 4.0.1 (API reference, tutorials).

This page is extracted from the v2.13.0 example bundle that shipped on the mapi.mapsted.com/v2.13.0/ CDN path — specifically the eight demo pages under assets/v2.13.0/example/ (index.html, boost.html, building.html, example1.html, floor.html, source.html, source1.html, style.css). Every snippet below is faithful to the v2 wire surface.

Loading v2

v2 was UMD-only, loaded from the CDN with the property id on the query string:

<!-- Same-origin hosting -->
<script src="/v2.13.0/maps.js?id=202"></script>

<!-- Cross-origin (CDN) -->
<script src="https://mapi.mapsted.com/v2.13.0/maps.js?id=202"></script>

Every public method was attached to the global mapsted.maps namespace.

mapsted.maps.initialize(options)

Mounts an interactive map into a container element.

mapsted.maps.initialize({
  element: document.getElementById('mapContainer'),
  entityDefaults: {
    marker: '<div style="background-color: red; width: 20px; height: 20px; border-radius: 20px; margin:-10px;"></div>',
    highlight: {
      stroke: { color: 'rgba(200, 0, 47,1)', width: 4, lineDash: [10] },
      fill:   { color: 'rgba(200, 0, 47,0.2)' },
    },
  },
  entityData: [
    { id: 599, name: 'Lot 83 - Holt', html: 'Popup HTML', marker: 'https://example.com/icon.png' },
    { id: 376, html: 'HTML popup', marker: '<b style="color:purple;">COS</b>' },
    { id: 974 },                        // marker only, no popup
    { id: 1308, html: 'Markers are only rendered on the correct floor' },
  ],
  coordsData: [
    {
      long: -79.45310177219832,
      lat:   43.72558186431165,
      floor: 373,
      html:  'This one is HTML.',
      name:  'Sample name',
      marker: 'https://example.com/icon.png',
    },
  ],
  features: { qrCode: false },
});

Options (as observed across the v2 examples):

Option	Type	Purpose
element	HTMLElement	Container node for the map.
entityDefaults	{ marker, highlight }	Fallback marker + highlight style for all entities.
entityData	Array<{ id, name?, html?, marker? }>	Entity overrides by id — popup HTML, custom marker, display name.
coordsData	Array<{ long, lat, floor, html?, name?, marker? }>	Point-based markers anchored to coordinates + floor.
features	{ qrCode?: boolean }	Built-in feature flags.
focus	'property'	Zoom level at load (example1.html).
boost	{ building?, floor? } | BoostObject	Deep-link boost (see createBoostSelect/createBoostRouting).
loader	custom loader override	Loader hook.

mapsted.maps.set(data)

Replaces the live map data — equivalent to calling initialize again with a new payload. Used by index.html to push Ace-editor JSON5 edits into the running map.

const sendMapData = () =>
  mapsted.maps.set(JSON5.parse(editor.getValue()));

Migration: set() re-mounts the map

In 4.0.1 the migration shim maps set() directly to init() (see the migration guide). Unlike v2 where set() hot-swapped entity data, 4.0.1 set() performs a full map re-mount — the iframe is torn down and re-initialized. Call setEntityData() / setEntityDataById() for live data updates without a re-mount. See the v3 → 4.0.1 migration guide.

mapsted.maps.selectEntity(id)

Programmatically selects a map entity by id, emitting a select event.

const selectHolt = () => mapsted.maps.selectEntity(599);

Event API (addEventListener / removeEventListener)

v2 used DOM-style listeners. Every event delivered a CustomEvent-like object with a .detail payload.

Migration: use on() instead of addEventListener()

In 4.0.1 the addEventListener and removeEventListener names are re-exported via the migration shim. Calling either method fires a console.warn deprecation notice on the first call. In strict mode (strict: true passed to init()), they throw MAPSTED-1093 immediately.

Replace all occurrences with the current canonical event API:

// v2 (deprecated)
mapsted.maps.addEventListener('select', handler);
mapsted.maps.removeEventListener('select', handler);

// 4.0.1 replacement
mapsted.maps.on('select', handler);
mapsted.maps.off('select', handler);

See Public API — Event system for full details.

// Built-in: load
mapsted.maps.addEventListener('load', (e) => {
  document.getElementById('loading-status').innerText = 'Done !';
});

// Built-in: select (fires on entity click or programmatic selectEntity)
mapsted.maps.addEventListener('select', (e) => {
  document.getElementById('selected').innerText = `Selected ${e.detail.longName}!`;
});

// Built-in: zoomLevelChange
mapsted.maps.addEventListener('zoomLevelChange', (e) => {
  document.getElementById('currentZoomLevel').innerText =
    `Current Zoom Level: ${e.detail.zoomLevel}`;
});

// Firehose listener — delivers every event
mapsted.maps.addEventListener('all', (e) => {
  console.log(e.detail);
});

Representative v2 events observed across the example bundle:

Event	e.detail shape	Fired when
load	(empty)	Map finishes initial load.
select	{ entityId, longName, ... }	User clicks an entity or selectEntity() is called.
zoomLevelChange	{ zoomLevel: number }	Map zoom changes.
promotionClick	{ entity, floor, building, property, name }	User taps a promotion banner / marker.
navigationStart	{ route: [...], options: { IncludeEscalators, IncludeRamps } }	User starts route guidance.
searchText	{ text: string }	Search query initiated.
detailsView	{ entity, floor, building, property, name }	User opens an entity detail panel.
all	{ type: string, ...detailForThatEvent }	Firehose — every emitted event.

Custom events via data-mapsted-* attributes

v2 lets popup HTML declare custom events inline with data-mapsted-trigger, data-mapsted-event, data-mapsted-payload:

<a href="#"
   data-mapsted-trigger="onclick"
   data-mapsted-event="alert"
   data-mapsted-payload='{ "test": "str", "num": 55 }'>
  Data Alert
</a>
<button data-mapsted-trigger="onmouseover" data-mapsted-event="confetti">🎉</button>

// subscriber picks up both the inlined payload AND the envelope mapsted adds
mapsted.maps.addEventListener('alert',    (e) => window.alert(JSON.stringify(e.detail, null, 2)));
mapsted.maps.addEventListener('confetti', ()  => jsConfetti.addConfetti({ confettiRadius: 5 }));

Deep linking — createBoostSelect / createBoostRouting

Boost helpers turn a v2 share-URL query string into an initialize({ boost }) payload so deep-links open to a pre-selected entity or a preloaded route.

// boost.html — pattern: accept either .../select?... or .../routing?... URLs
const generateAndApplyBoost = () => {
  const urlString = document.getElementById('urlInput').value;
  const url       = new URL(urlString);
  const linkType  = url.pathname.split('/').pop(); // "select" | "routing"

  let boost;
  if (linkType === 'select')  boost = mapsted.maps.createBoostSelect(url.search);
  if (linkType === 'routing') boost = mapsted.maps.createBoostRouting(url.search);

  if (boost) {
    const container = document.getElementById('mapContainer');
    container.innerHTML = null;
    mapsted.maps.initialize({ element: container, boost });
  }
};

Boost options at initialize time

Beyond share-URL boosts, v2 also accepted direct boost shortcuts inside initialize — covered by building.html and floor.html:

// building.html — open map focused on a specific building
mapsted.maps.initialize({
  element: document.getElementById('mapContainer'),
  boost:   { building: 754 },
});

// floor.html — open map focused on a specific floor
mapsted.maps.initialize({
  element: document.getElementById('mapContainer'),
  boost:   { floor: 3291 },
});

mapsted.maps.calculateDistance(data)

Returns distance(s) between a start point and one or more destinations. Each endpoint is typed — 'entity', 'coordinate', or 'mapOverlay'.

// example1.html — mixed endpoint types in a single request
const data = {
  start: {
    type: 'entity',
    data: { buildingId: 95, floorId: 184, entityId: 140 },
  },
  destinations: [
    { type: 'entity',     data: { buildingId: 95, floorId: 184, entityId: 142 } },
    { type: 'coordinate', data: { latitude: 43.7752654, longitude: -79.2585689, buildingId: 95, floorId: 184 } },
    { type: 'coordinate', data: { latitude: 43.7753178, longitude: -79.2585296, buildingId: 95, floorId: 185 } },
    { type: 'mapOverlay', data: { mapOverlayId: '9419' } },
  ],
};
const res = await mapsted.maps.calculateDistance(data);
// res contains distances (metres) between start and each destination.

Each endpoint shape:

type	data shape
entity	{ buildingId, floorId, entityId }
coordinate	{ latitude, longitude, buildingId, floorId }
mapOverlay	{ mapOverlayId }

mapsted.maps.initialize({ features })

Feature flag hash — a single boolean slot in v2 (qrCode). v3 expands this into the typed FeatureFlagSet interface; see the Feature Flags reference.

mapsted.maps.initialize({
  element:  mapContainer,
  features: { qrCode: false },
});

Ready to upgrade?

Every v2 method above has a 4.0.1 equivalent — see the migration guide for the full rename table, event renames, new SecurityConfig contract, and a six-step upgrade checklist. Upgrading is optional: mapi.mapsted.com keeps serving v2.13.0, so existing integrations continue to work with no action required.