Getting Started
Using Mappedin JS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.
This getting started guide demonstrates how to start a project using Mappedin JS. Following this guide results in a working demo with a map that you can interact with (zoom, pan, rotate etc).
Mappedin JS v6 is available as @mappedin/mappedin-js in NPM.
Video Walkthrough
Local Development
For local development, clone the Mappedin JS v6 Quickstart repository or start a project using Vite. Refer to the Vite Getting Started guide for setup details. Guides are written in TypeScript (JavaScript), as the SDK is also written in Typescript and uses comprehensive types.
1. Create a Project
Run these shell commands to set up a new project and install Mappedin JS.
pnpm create vite mappedin-quickstart
cd mappedin-quickstart
pnpm add @mappedin/mappedin-js
2. Update index.html, main.ts
Modify & update the contents of index.html and main.ts to match the following.
<!DOCTYPE html>
<html>
<head>
<title>Mappedin JS v6 Getting Started</title>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8" />
<style>
* {
margin: 0;
padding: 0;
}
html,
body {
width: 100%;
height: 100%;
}
#mappedin-map {
height: 100%;
width: 100%;
position: relative;
}
</style>
</head>
<body>
<div id="mappedin-map"></div>
<script type="module" src="src/main.ts"></script>
</body>
</html>
Create or update a file under the src directory called main.ts. Write the following contents to the file.
import { getMapData, show3dMap } from '@mappedin/mappedin-js';
// See Demo API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
const options = {
key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
mapId: '65c0ff7430b94e3fabd5bb8c',
};
async function init() {
// Load the map data from Mappedin servers.
const mapData = await getMapData(options);
// Show the map in the div with id 'mappedin-map'.
// Enable shadows to provide more depth and realism to the map.
const mapView = await show3dMap(
document.getElementById('mappedin-map') as HTMLDivElement,
mapData,
{ shadows: 'auto' }
);
}
init();
3. Run the Project
To run the demo (with hotloading), use the following command:
pnpm dev
The following example demonstrates what should be shown.
This should result in a prompt showing the project being served at http://127.0.0.1:5173 (default port). The 3D rendered map can be zoomed, panned and rotated via mouse or fingers.
Create a Key & Secret
A key and secret to use Mappedin Demo maps can be found on the Demo Keys & Maps Page. To use your own maps, create your own unique key and secret.
Using maps with your own key and secret requires a Pro or Solutions Map Account.
- Log into Mappedin Maker.
- Click on the
Developerstab. - Click
Generate API Key. - Enter a name for the key.
- Click
Generate Key. - Store the
keyandsecretis a safe and secure place.

Get a Map Id
Each map has a unique identifier used by Mappedin JS to load a map. To get the mapId of a map:
- Log into Mappedin Maker.
- Click on the
Developerstab. - Select the desired map from the dropdown.
- The
mapIdwill be shown in the code snippet.

Not seeing your map?
- Remember to set the map to Live. To do so click on the
Share Mapsbutton and changeDrafttoLive. - Integrations require a Pro or Enterprise Map Account. Demo API Keys will only work for Mappedin demo maps.

Authenticating with a Bearer Token
Mappedin JS can also be authenticated with a short lived bearer token. This can be used to prevent exposing credentials by generating a token on the server side. The server can securely store the credentials, allowing the client to use the token to authenticate with Mappedin JS.
The way a bearer token is obtained depends on where a map is hosted. Maps created in Mappedin Maker use an API key and secret, while maps managed in the Mappedin Enterprise Content Management System (CMS) use a client ID and client secret.
Mappedin Maker Maps
Maps created in Mappedin Maker are authenticated with an API key and secret. A Mappedin Maker API key begins with the mik_ prefix.
To obtain a bearer token, make a request to the API Key REST endpoint sending the API key and secret. Additional examples can be found in the API Key REST documentation.
The following complete TypeScript example requests a bearer token and uses it to load and display a map.
import { getMapData, show3dMap } from '@mappedin/mappedin-js';
interface TokenResponse {
access_token: string;
expires_in: number;
}
// See Trial API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
async function getAccessToken(): Promise<string> {
const response = await fetch('https://app.mappedin.com/api/v1/api-key/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
key: 'YOUR_KEY',
secret: 'YOUR_SECRET',
}),
});
const data: TokenResponse = await response.json();
return data.access_token;
}
async function init() {
const accessToken = await getAccessToken();
const mapData = await getMapData({
accessToken,
mapId: 'YOUR_MAP_ID',
});
const mapView = await show3dMap(
document.getElementById('mappedin-map') as HTMLDivElement,
mapData,
{ shadows: 'auto' }
);
}
init();
The API Key REST endpoint returns JSON that contains the bearer token, for example:
{
"access_token": "…",
"expires_in": 172800
}
Mappedin CMS Maps
Maps managed in Mappedin CMS are authenticated with a client ID and client secret using the OAuth client credentials grant.
To obtain a bearer token, make a request to the Mappedin API Gateway authentication endpoint sending the client ID and client secret.
The following complete TypeScript example requests a bearer token and uses it to load and display a map.
import { getMapData, show3dMap } from '@mappedin/mappedin-js';
interface TokenResponse {
access_token: string;
expires_in: number;
}
async function getAccessToken(): Promise<string> {
const response = await fetch('https://api-gateway.mappedin.com/auth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
grant_type: 'client_credentials',
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET',
}),
});
const data: TokenResponse = await response.json();
return data.access_token;
}
async function init() {
const accessToken = await getAccessToken();
const mapData = await getMapData({
accessToken,
mapId: 'YOUR_MAP_ID',
});
const mapView = await show3dMap(
document.getElementById('mappedin-map') as HTMLDivElement,
mapData,
{ shadows: 'auto' }
);
}
init();
The authentication endpoint returns JSON that contains the bearer token, for example:
{
"access_token": "…",
"expires_in": 172800
}
Local Development without NPM
While NPM is highly recommended for version control and to receive the latest bug fixes and features, Mappedin JS may also be imported from a CDN.
When importing Mappedin JS from a CDN, use the package root with the /+esm suffix (e.g. https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@6/+esm) rather than a direct file path like /lib/esm/index.min.js.
In this example JSDelivr will be used to demonstrate importing the mappedin-js package. Mappedin JS is also available on unpkg. Please feel free to reach out if Mappedin JS is not available on a preferred CDN.
Import the SDK stylesheet in the document <head> and any other necessary styles for the app.
<style>
* {
margin: 0;
padding: 0;
}
html,
body {
width: 100%;
height: 100%;
}
#mappedin-map {
height: 100%;
width: 100%;
position: relative;
}
</style>
In the <body>, include the element which the map will attach too and the script to asynchronously load the MapView.
<div id="mappedin-map"></div>
<script type="module">
import {
getMapData,
show3dMap,
} from 'https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@6/+esm';
// See Demo API key Terms and Conditions
// https://developer.mappedin.com/web/docs/demo-keys-and-maps
const options = {
key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
mapId: '65c0ff7430b94e3fabd5bb8c',
};
getMapData(options).then(async mapData => {
const mapView = await show3dMap(document.getElementById('mappedin-map'), mapData, {
shadows: 'auto',
});
});
</script>
Putting it all together, the entire HTML document should resemble the following.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<style>
* {
margin: 0;
padding: 0;
}
html,
body {
width: 100%;
height: 100%;
}
#mappedin-map {
height: 100%;
width: 100%;
position: relative;
}
</style>
<title>Mappedin JS v6 Getting Started with JSDelivr</title>
</head>
<body>
<div id="mappedin-map"></div>
<script type="module">
import {
getMapData,
show3dMap,
} from 'https://cdn.jsdelivr.net/npm/@mappedin/mappedin-js@6/+esm';
// See Demo API key Terms and Conditions
const options = {
key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
mapId: '65c0ff7430b94e3fabd5bb8c',
};
getMapData(options).then(async mapData => {
const mapView = await show3dMap(document.getElementById('mappedin-map'), mapData, {
shadows: 'auto',
});
});
</script>
</body>
</html>
With only the above document, a map will be rendered into the window. Just like with NPM, the 3D rendered map can be zoomed, panned and rotated via mouse or fingers.
Using Mappedin JS with Node.js
Mappedin JS can be used in a Node.js application without a user interface. This is useful for back end tasks such as pulling map data into an existing system, generating a report of a venue's Floors and Locations, or using map data as part of a build or sync process. In this environment the SDK is used to load and query map data. Rendering a map with show3dMap() requires a DOM and is not available in Node.js.
1. Create a Project
Run these shell commands to set up a new project and install Mappedin JS.
mkdir mappedin-node
cd mappedin-node
npm init -y
npm install @mappedin/mappedin-js
npm install --save-dev typescript @types/node
2. Configure TypeScript
Mappedin JS is distributed as ECMAScript Modules (ESM), so the project must be configured to use them. Add the following to package.json to enable ESM.
{
"type": "module"
}
Create a tsconfig.json configured for Node.js with a target of ES2022 or later.
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "dist",
"rootDir": ".",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["index.ts"]
}
3. Load Map Data
Create a file called index.ts. The following example uses getMapData() to load a map, then reads the venue name and each FloorStack (building) with its Floor objects.
import {
getMapData,
type MapData,
type FloorStack,
type TGetMapDataOptions,
} from '@mappedin/mappedin-js';
// See Demo API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
const options: TGetMapDataOptions = {
key: 'mik_yeBk0Vf0nNJtpesfu560e07e5',
secret: 'mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022',
mapId: '682e13a2703478000b567b66',
};
const mapData: MapData = await getMapData(options);
console.log('Map name:', mapData.mapName);
const stacks: FloorStack[] = mapData.getByType('floor-stack');
for (const stack of stacks) {
console.log(`Building: ${stack.name}`);
for (const floor of stack.floors) {
console.log(` - ${floor.name} (elevation ${floor.elevation})`);
}
}
// The SDK leaves handles open (analytics/workers), so exit explicitly.
// process.exit() does not wait for pending asynchronous writes to stdout,
// so explicitly drain stdout before exiting to avoid truncated output.
await new Promise<void>((resolve) => process.stdout.write('', () => resolve()));
process.exit(0);
The MapData object returned by getMapData() provides the venue's Floors, Locations and more. Data can be queried using getByType() or getById().
Mappedin JS leaves handles open for analytics and worker threads, so a script that only loads and queries map data must exit explicitly when finished. Without this, the process does not terminate on its own.
4. Run the Project
Add a script to package.json to compile and run the project.
{
"scripts": {
"start": "tsc && node dist/index.js"
}
}
Run the script with the following command:
npm start
The following output demonstrates what should be shown.
Map name: University Campus Demo
Building: Outdoor
- Overview (elevation 0)
Building: 1901 Marketplace Building
- Basement (elevation -1)
- Level 1 (elevation 0)
Building: Cafe Pavilion
- Level 1 (elevation 0)
Building: Engineering South Building
- Level 1 (elevation 0)
- Level 2 (elevation 1)
Building: Printing Press
- Level 1 (elevation 0)
Building: Graphic Arts Building
- Level 1 (elevation 0)
- Level 2 (elevation 1)
- Level 3 (elevation 2)
Building: Mott Athletics Center
- Level 1 (elevation 0)
- Level 2 (elevation 1)
Offline Mode
The examples in the Mappedin JS guides assume that the user is online and connected to the Internet. In some environments, this may not be possible. There are two methods available to store map data offline and use it to render a map.
Offline Loading from TMVF Objects
Offline loading of TMVF objects stored as JSON is appropriate for scenarios where Mappedin JS is used to initially download the map data using the getMapData() function. This data could be stored in a JSON file to be read from when the user is offline. The steps below outline how to do this.
- Load the map using getMapData().
- Use MapData.toJSONBundle() to create a TMVF object.
- Store the TMVF object.
- When the user is offline, read the JSON file and use hydrateMapData() to create a MapData object.
- Use the MapData object to render a map using show3dMap().
The code snippet below demonstrates how to load the map, store the map data in a cache, and then use the cached on subsequent loads.
import { getMapData, hydrateMapData, MapData, show3dMap, THydrateMapDataBundle } from '@mappedin/mappedin-js';
import Dexie, { type EntityTable } from 'dexie';
interface MapDataCache {
file: THydrateMapDataBundle;
mapId: string;
}
async function getMapDataFromCache(options: { mapId: string }) {
try {
const handle = new Dexie('Mappedin') as Dexie & {
mapData: EntityTable<MapDataCache, 'mapId'>;
};
handle.version(1).stores({
mapData: '++mapId',
});
await handle.open();
const cached = await handle.mapData.get(options.mapId);
return cached;
} catch (e) {
return null;
}
}
async function saveMapDataToCache(mapData: MapData, mapId: string) {
const backup = await mapData.toBinaryBundle();
if (backup) {
const db = new Dexie('Mappedin') as Dexie & {
mapData: EntityTable<MapDataCache, 'mapId'>;
};
db.version(1).stores({
mapData: '++mapId',
});
await db.mapData.put({ mapId, file: backup });
}
}
async function deleteMapDataFromCache(mapId: string) {
const handle = new Dexie('Mappedin') as Dexie & {
mapData: EntityTable<MapDataCache, 'mapId'>;
};
handle.version(1).stores({
mapData: '++mapId',
});
await handle.open();
await handle.mapData.delete(mapId);
console.log('deleted map data from cache');
}
async function init() {
const options = {
key: '5eab30aa91b055001a68e996',
secret: 'RJyRXKcryCMy4erZqqCbuB1NbR66QTGNXVE0x3Pg6oCIlUR1',
mapId: 'mappedin-demo-mall',
};
const cached = await getMapDataFromCache({ mapId: options.mapId });
let mapData: MapData;
if (cached && cached.file) {
console.log('using cached map data');
mapData = await hydrateMapData(cached.file, options);
} else {
console.log('getting map data from server');
mapData = await getMapData(options);
await saveMapDataToCache(mapData, options.mapId);
}
const mapView = await show3dMap(document.getElementById('mappedin-map') as HTMLDivElement, mapData, {
shadows: 'auto',
});
}
init();
Offline Loading from MVF Files
Offline loading of Mappedin Venue Format (MVF) files is appropriate for scenarios where the map data is not fetched using Mappedin JS. This approach is particularly useful in offline or low-connectivity environments—such as air gapped networks, cruise ships, or remote locations. It's also beneficial when you need full control over content distribution, for example, to meet internal security requirements or to ensure that a specific version of the map is always available, regardless of network conditions.
An MVF file can be downloaded from Mappedin Maker or fetched using Mappedin REST API endpoints. Instructions for downloading an MVF file can be found in the Getting Started with MVF v3 guide.
The code snippet below demonstrates how to load a self hosted MVF file.
import { show3dMap, hydrateMapData } from "@mappedin/mappedin-js";
import "./styles.css";
async function init() {
//Fetch the MVFv3 file hosted in this CodeSandbox.
const response = await fetch("./demo-school-mvf-v3.zip");
const arrayBuffer = await response.arrayBuffer();
const zipBuffer = new Uint8Array(arrayBuffer);
const mapData = await hydrateMapData({ type: "binary", main: zipBuffer });
//Use the parsed MVF to show the map.
const mapView = await show3dMap(
document.getElementById("mappedin-map") as HTMLDivElement,
mapData,
{ shadows: "auto" }
);
}
init();
The code snippet above is implemented in the following example.
Debug Mode
Use Debug Mode to get a closer look at how various map components behave and interact. Here's how to enable it:
1. Enable Debug Mode
To activate the debug interface, call the following function in your code:
mapView.enableDebug();
enableDebug displays a panel on the right side of the map, revealing several tools and controls for direct interaction with the map's elements.
2. Navigating the Debug Panel
The debug panel provides access to a variety of controls:
Geometry Controls
- Adjust individual geometry settings, such as color, opacity, visibility. These controls make it easy to see how different elements respond to changes.
Interactivity
- Use toggles to turn interactivity on/off
- Change colors and hover effects to highlight specific areas
Scene Controls
- Manage the overall scene settings, such as scaling, positioning, and group management. Toggle the visibility of groups or containers within the scene
- Adjust padding, scale, and watermark positioning
- Markers & Labels — Add, remove, or edit markers and labels directly through the panel
Camera Controls
- Fine-tune camera settings, including zoom levels, pitch, and center position
- Set minimum and maximum zoom levels
- Adjust the focus to a specific area or level
