Embedding Interactive Maps

Beta Feature

Interactive maps are still in development. For customers with a package S (or higher), this function is available free of charge until the end of July 2025, after which usage-based billing will apply. The availability is currently limited and there may be errors. Give Feedback

Learn how to embed interactive maps in your website or application. mapstudio.ai offers flexible embedding options that work with any website or CMS.

Quick Embedding (Recommended)

The easiest way to embed an interactive map:

html

<head>
  <!-- Add script & CSS (for map display) to the head -->
  <link rel="preload" href="https://share.mapstudio.ai/embed.js" as="script" />
  <link rel="stylesheet" href="https://share.mapstudio.ai/embed.css">
</head>

<body>
  <!-- Map container -->
  <div id="my-map" style="width: 100%; height: 400px;"></div>


  <!-- JavaScript code for map initialization (at the end of the body) -->
  <script>
  mapstudio.createMap({
    containerId: "my-map", // Required: HTML element ID
    exportId: "your-export-id-here", // Required: Your map export ID from the mapstudio.ai export dialog
  });
  </script>
</body>

Replace your-export-id-here with your actual export ID from the mapstudio.ai editor (export dialog).

⚠️ Important: Allowed Domains

Maps only load on domains that you have explicitly allowed in your workspace settings. Configure allowed domains in your mapstudio.ai dashboard under Interactive Maps → Allowed Domains.

Additional Embedding Options

The mapstudio.createMap() function accepts these additional options:

javascript

mapstudio.createMap({
  containerId: "map-container",       // Required: HTML element ID
  exportId: "abc123",                // Required: Your map export ID
  display: {
    // Position of navigation control - Default: "top-right" - Options: false, "top-left", "top-right", "bottom-left", "bottom-right"
    showNavigationControl: "top-right",
    // Disable loading status overlay - Default: false - Options: true, false
    disableLoadingOverlay: false,
  }
});

(Optional) Fallback for Disabled JavaScript

Always add a fallback image for users without JavaScript:

html

<div id="map-container">
  <noscript>
    <img 
      src="https://share.mapstudio.ai/embed/<your-export-id-here>/fallback.webp" 
      alt="Interactive Map"
      style="width: 100%; height: 100%; object-fit: cover;"
    />
  </noscript>
</div>

Please replace <your-export-id-here> with your actual export ID from the mapstudio.ai editor (export dialog). In case the map cannot be loaded, the defined map viewport (set in the export) will be displayed as a static image.

(Optional) Content Security Policy (CSP)

For websites with Content Security Policy (CSP), add these directives to your CSP configuration:

text

script-src 'self' 'unsafe-inline' https://share.mapstudio.ai;
style-src 'self' 'unsafe-inline' https://share.mapstudio.ai;
img-src 'self' data: blob: https://map.cdn.mapstudio.ai https://share.mapstudio.ai;
connect-src 'self' https://map.cdn.mapstudio.ai https://fonts.mapstudio.ai https://share.mapstudio.ai;
worker-src 'self' data: blob:;
font-src 'self';

Responsive Design

Maps automatically adapt to the container size. It is mandatory to set a container size. Example for responsive design:

css

.map-container {
  width: 100%;
  height: 60vh;
  min-height: 300px;
  max-height: 600px;
}

@media (max-width: 768px) {
  .map-container {
    height: 40vh;
    min-height: 250px;
  }
}

Common Integration Issues

Map doesn't load

Check allowed domains in workspace settings
Verify export ID is correct and map exists
Check browser console for error messages (Is JavaScript loading?)

CSP blocks resources

Add mapstudio.ai domains to CSP directives
Check browser console for CSP violation messages
Test with disabled CSP or CSP-report-only to confirm the issue

Performance issues

Set appropriate container size (avoid very large maps)
Use CSS to optimize layout before map loads
Consider lazy loading for maps below the fold

Advanced Integration

Lazy Loading

Only load maps when they become visible:

javascript

// Intersection Observer for lazy loading
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      mapstudio.createMap({
        containerId: entry.target.id,
        exportId: "your-export-id"
      });
      observer.unobserve(entry.target);
    }
  });
});

observer.observe(document.getElementById("map-container"));

Multiple Maps

Embed multiple maps on the same page:

html

<div id="map-1" style="width: 100%; height: 400px; margin-bottom: 20px;"></div>
<div id="map-2" style="width: 100%; height: 400px;"></div>

<script>
mapstudio.createMap({
  containerId: "map-1",
  exportId: "first-export-id"
});

mapstudio.createMap({
  containerId: "map-2", 
  exportId: "second-export-id"
});
</script>

Next: Learn more about implementation examples for different platforms.