Appearance

Type Definitions ​

All types listed here are exported from the @mapsted/maps-js-api package and available via the dist/index.d.ts declaration file.

ts
import type { MapstedId, MapEntity, FloorInfo /* … */ } from '@mapsted/maps-js-api';

Primitives ​

MapstedId ​

ts
type MapstedId = string | number;

A Mapsted entity, floor, or building identifier. The API accepts both string and number forms — they are treated as equal when the server-side integer value matches.

Entity and POI types ​

MapEntity ​

An entity display override object passed to setEntityData(), setEntityDataById(), setEntityDefaults(), and the entityData init option.

ts
type MapEntity = {
  id: MapstedId;
  name?: string;          // Shown at the top of the popup
  html?: string;          // HTML string rendered inside the popup
  marker?: string;        // Custom marker: HTML string (starts with "<") or image URL
  highlight?: HighlightStyle;
  buildingId?: string | number;
};

HighlightStyle ​

OpenLayers fill and stroke style applied when an entity is highlighted. See the OpenLayers Fill and Stroke docs for accepted color formats.

ts
interface HighlightStyle {
  stroke: { color: string; width: number };
  fill: { color: string };
}

CoordsData ​

Marker placed at arbitrary WGS84 coordinates, used with setCoordsData() and returned by the coordsSelect event.

ts
type CoordsData = {
  lat: number;     // Latitude (WGS84)
  long: number;    // Longitude (WGS84)
  floor: number;   // Floor ID the marker belongs to
  name?: string;   // Popup title
  html?: string;   // Popup HTML body
  marker?: string; // Custom marker: HTML string or image URL
};

MapOverlayMarker ​

Marker attached to a CMS map overlay region. Used with setMapOverlayMarkers() and returned by the mapOverlayMarkerSelect event.

ts
type MapOverlayMarker = {
  id: string;       // CMS map overlay ID (obtain from Mapsted Manage)
  name?: string;
  html?: string;
  marker?: string;
  /** @internal API sets this from `id` during transform — do not set manually. */
  mapOverlayId?: string;
};

MultiLangString ​

A dictionary keyed by 2-letter BCP 47 language code (e.g. "en", "fr", "zh"). Almost always contains an "en" entry.

ts
type MultiLangString = Record<string, string>;

Feature flags ​

FeatureFlagSet ​

All 11 boolean flags controlling built-in UI widget visibility. See the Feature Flags reference for per-flag descriptions.

ts
interface FeatureFlagSet {
  showText: boolean;
  showImages: boolean;
  qrCode: boolean;
  categories: boolean;
  buildingLogo: boolean;
  languageSwitcher: boolean;
  themeSwitcher: boolean;
  headerBar: boolean;
  defaultPopup: boolean;
  floors: boolean;
  zoom: boolean;
}

Boost types ​

Boosts are pre-encoded navigation commands applied to the map via applyBoost() or the boost init option.

FloorBoost ​

Navigate to a floor, optionally scoped to a building.

ts
interface FloorBoost {
  floor: number;
  building?: number;
}

SelectEntityBoost ​

Select an entity on the map after navigating to its floor and building.

ts
interface SelectEntityBoost extends FloorBoost {
  type: BoostTypes;      // BoostTypes.SELECT
  entity: number;        // Entity ID to select
  addDestination?: boolean; // If true, open the "Add Destination" routing modal
}

RoutingBoost ​

Render a route between two or more entities.

ts
interface RoutingBoost {
  type: BoostTypes;      // BoostTypes.ROUTING
  routing: string;       // e.g. "95:3595,95:3818"
  routeOptions?: string; // e.g. "IncludeElevators,OptimizeItinerary"
}

Boost ​

The union of all boost types (or undefined for no boost).

ts
type Boost = FloorBoost | SelectEntityBoost | RoutingBoost | undefined;

RoutingConfig ​

Object form for building a RoutingBoost via createBoostRouting().

ts
type RoutingConfig = {
  routing: string;       // "buildingId:entityId,buildingId:entityId[,…]"
  routeOptions?: string; // Comma-separated RouteOptions values
};

Routing configuration ​

DefaultCustomRoutingConfig ​

Full set of routing preferences. All fields are required. Passed to setDefaultRoutingConfig() and setAccessibilityMode().

ts
interface DefaultCustomRoutingConfig {
  accessibility: boolean;
  OptimizeItinerary: boolean;
  IncludeElevators: boolean;
  IncludeEscalators: boolean;
  IncludeStairs: boolean;
  IncludeRamps: boolean;
  PreferIndoorRoute: boolean;
  PreferOutdoorRoute: boolean;
}

RouteOptions (enum) ​

String values accepted in RoutingConfig.routeOptions and RoutingBoost.routeOptions.

ValueDescription
IncludeElevatorsAllow elevator transition points
IncludeEscalatorsAllow escalator transition points
IncludeStairsAllow staircase transition points
IncludeRampsAllow ramp transition points
OptimizeItineraryPrefer the shortest route
PreferIndoorRoutePrefer indoor segments
PreferOutdoorRoutePrefer outdoor segments

Default when no routeOptions is specified: IncludeElevators,IncludeEscalators,IncludeStairs,IncludeRamps.

Distance calculation types ​

LocationType ​

ts
type LocationType = "entity" | "coordinate" | "mapOverlay";

Location<T> ​

Generic wrapper for any location input.

ts
interface Location<T> {
  type: LocationType;
  data: T;
}

EntityData ​

Location data for an entity-based location.

ts
interface EntityData {
  buildingId: string | number;
  floorId: string | number;
  entityId: string | number;
}

CoordinateData ​

Location data for a raw coordinate.

ts
interface CoordinateData {
  latitude: number;
  longitude: number;
  buildingId: string | number;
  floorId: string | number;
}

MapOverlayData ​

Location data for a map overlay-based location.

ts
interface MapOverlayData {
  mapOverlayId: string; // CMS overlay ID
}

LocationData ​

Union of all location input forms.

ts
type LocationData =
  | Location<EntityData>
  | Location<CoordinateData>
  | Location<MapOverlayData>;

CalculationRequest ​

Input to calculateDistance().

ts
interface CalculationRequest {
  start: LocationData;
  destinations: LocationData[];
}

CalculationResult ​

Output from calculateDistance().

ts
interface CalculationResult {
  start: LocationData;
  destinations: {
    destination: LocationData;
    distance: number;  // metres
  }[];
  message: "Success" | "Failed" | "DataValidation | DataNotLoaded";
}

API state types ​

ApiState ​

The API lifecycle progresses through these states in order. Only READY permits command methods.

ts
type ApiState = 'UNINITIALIZED' | 'LOADING' | 'READY' | 'DESTROYED';

The legacy alias SdkState is retained for backwards compatibility; new code should use ApiState.

MapState ​

Snapshot of the current API state. Returned by getState() and passed to subscribe() callbacks.

ts
interface MapState {
  sdkState: ApiState;
  isReady: boolean;
  currentFloor: FloorInfo | null;
  selectedEntityId: MapstedId | null;
  mapCenter: [number, number] | null;  // [longitude, latitude]
  zoomLevel: number | null;
  language: string | null;
  idleState: 'active' | 'idle';
}

Unsubscribe ​

Function returned by subscribe(). Calling it detaches the handler.

ts
type Unsubscribe = () => void;

Map instance and options ​

MapInstance ​

Opaque handle returned by init(). The API is module-scoped (single map per page), so MapInstance is a convenience wrapper for the four state-related methods.

ts
interface MapInstance {
  destroy(): Promise<void>;
  isReady(): Promise<boolean>;
  getState(): Promise<MapState>;
  subscribe(handler: (state: MapState) => void): Unsubscribe;
}

FloorInfo ​

Floor metadata returned by getFloors() and the floorChange event.

ts
interface FloorInfo {
  floorId: MapstedId;
  longName: MultiLangString;
  shortName: MultiLangString;
  floorNumber: number;
}

SelectOptions ​

Optional second argument to selectEntity().

ts
interface SelectOptions {
  zoomTo?: number;       // Zoom level (10–24)
  buildingId?: number;   // -1 for property-level entities
  actionType?: ActionTypes;
}

ViewportOptions ​

Argument to setViewport(). At least one field is required.

ts
type ViewportOptions = {
  zoomLevel?: number;              // 10–24
  mapCenter?: [number, number];    // [longitude, latitude] WGS84
};

InitOptions ​

The full configuration object for init(). See the InitOptions reference for field-level documentation.

ts
interface InitOptions extends SetOptions {
  element?: HTMLElement | string;
  onload?: () => void;
  accessKey?: string;
  language?: string;
  mapsDomain?: string;
  propertyId?: string | number;
}

Event payload types ​

See the Events reference for payload field descriptions.

TypeUsed by event
EntityDataselect, detailsView
CoordsDatacoordsSelect
FloorInfofloorChange
NavigationDatanavigationStart
PromotionDatapromotionClick, promotionDetails
ProtocolErrorPayloadprotocolError
ts
interface NavigationData {
  routing?: string;
  routeOptions?: string;
}

PromotionData ​

ts
interface PromotionData {
  entity?: EntityData;
  [key: string]: unknown;
}

ProtocolErrorPayload ​

ts
interface ProtocolErrorPayload {
  reason: string;
  code: string;
  message: string;
  details: Record<string, unknown>;
}