For developers · EmbeddingAs of 28 September 2026

Embed and control SovAtlas

SovAtlas maps can be embedded via iframe in your own portals, intranets and control centre dashboards, and controlled from the embedding page through a JavaScript API (postMessage): camera flights, 2D/3D switching, screenshots and camera events.

iframe embedding

Each project URL has an access mode, set in the administration under Projekt › Embed. The ready-to-use embed snippet is also generated there.

HTML

<iframe
  src="https://viewer.sovatlas.com/p/YOUR-ORGANISATION/YOUR-MAP"
  width="100%"
  height="600"
  style="border:0"
  allow="fullscreen"
  loading="lazy"
></iframe>

Access modes

public: freely accessible, can be embedded on any domain.
iframe: can only be embedded on the domains you have approved (allowlist). The restriction is enforced server-side with the frame-ancestors CSP directive; on other domains the browser refuses to load it.
password: opens only with a password; cannot be embedded externally.
magic_link: opens only with a valid signed link token; cannot be embedded externally.

JavaScript Embed API

The helper package has not been released publicly. Use the postMessage protocol directly, as in the example below, or ask us for the package.

API reference

Method	Description
`flyTo({lon, lat, height?, durationSec?})`	Flies the camera to a position. `durationSec: 0` jumps there without animation.
`getCamera()`	Returns `{lon, lat, height, sceneMode2D}`.
`setSceneMode2D(enabled)`	Switches between the 3D globe and the 2D situation map.
`screenshot({mimeType?, quality?})`	Captures the scene as a data URL. `image/png` (default) or `image/jpeg` with quality 0–1.
`onCameraMoveEnd(handler)`	Subscribes to the end of every camera movement; the return value unsubscribes.
`destroy()`	Removes all listeners; pending requests are rejected.

Raw protocol (no SDK)

The API is based on window.postMessage with messages in the sovatlas:* namespace and can also be used without the SDK – e.g. from non-JavaScript environments that control a WebView. Each command carries a requestId, which comes back in the response (sovatlas:result) for correlation.

JavaScript

// Send a command to the iframe
iframe.contentWindow.postMessage(
  { type: "sovatlas:flyTo", requestId: "req-1",
    lon: 11.0328, lat: 50.9787, height: 2500 },
  "https://viewer.sovatlas.com",
);

// Receive the response
window.addEventListener("message", (event) => {
  if (event.origin !== "https://viewer.sovatlas.com") return;
  const msg = event.data;
  if (msg?.type === "sovatlas:result" && msg.requestId === "req-1") {
    console.log(msg.ok ? "OK" : msg.error);
  }
});

Available commands: sovatlas:hello, sovatlas:flyTo, sovatlas:getCamera, sovatlas:setSceneMode2D, sovatlas:screenshot. After booting, the viewer sends sovatlas:ready (with protocolVersion) to the embedding page; sovatlas:hello can repeat the handshake at any time. Camera events arrive as {type: "sovatlas:event", event: "cameraMoveEnd", camera}.

Security

The Embed API respects the access mode of the project URL: with iframe, the viewer answers postMessage commands only from the approved domains; with password and magic_link, only from its own origin.
Responses are always addressed to the sender’s origin (no "*" broadcast carrying payload data).
In your own listeners, always check event.origin against the viewer domain – the SDK does this automatically.

Questions or further requirements? Get in touch.