Embed API overview

The Embed API lets the page that hosts an embedded Icon Map drive the map from JavaScript, and hear back from it. If you have used the Power BI Embedded client library, this is the same idea for maps: a small SDK, a handle, promise-returning commands and subscribable events.

This section is written for the developers building the hosting page. If you are the map's author and want to publish or embed it, start with Publishing & sharing and Embedding maps.

const map = IconMapEmbed.embed(document.getElementById("map"), { publishId: "pub_..." });
await map.ready;

await map.flyTo({ center: [-0.12, 51.5], zoom: 11 });
await map.selectByKey({ layerId: "assets", field: "asset_id", keys: ["41B"], zoomTo: true });

map.on("featureClick", (feature) => feature && openAssetPanel(feature.fields));

What you can do

Area Examples
Camera Read the view, jump or fly to a place, frame a bounding box or a whole layer, limit panning to an area
Layers List the layers, show and hide them, read every toggle the reader has (labels, hillshade, charts and other visuals)
Filters Discover the filters the author declared, set them (including number ranges and "last 30 days"), refresh live data
Slicers Read and set the reader's slicers, list the values a slicer offers
Selection Select features by your own keys ("asset 41B"), highlight without selecting, cross-filter from a chart
Scenes Capture the whole view as one object, restore it later, apply the author's bookmarks, play tours
Presentation Switch between the published basemaps, hide the map's own controls, go dark, read the legend as data, export an image
Popup commands Add your own action to the feature popup ("Raise a job for this asset")
Analysis Run a layer's analysis engine and receive its results, on maps that have one
Events View changes, feature clicks, selection, filters, slicers, link clicks, data state, token expiry

The commands guide walks through these with examples; the API reference lists every command, event, error code and limit.

How it works

The SDK mounts the map as an <iframe> and talks to it with postMessage. Nothing of the map runs in your page, and nothing of your page runs in the map.

  1. Your page calls embed(). The SDK creates the frame and waits for it to say it is ready.
  2. The two sides agree a protocol version, and the map checks your page's origin against the list of sites its author allowed.
  3. If you are allowed, the map answers with a capability descriptor: the commands and events this map will answer. await map.ready resolves with it.
  4. From then on each method call is one message to the map and one answer back.

You do not need to time anything. Commands you call before the map has finished starting are held and answered as soon as the part of the map they need exists.

Two ways to embed, one API

Published map Embedding for your organization
Who views Anyone you give the page to - no Fabric account Colleagues, each signed in with their own work account
Data Frozen or live, through the publish Live, read as each viewer, so Fabric permissions and row-level security apply
Entry point embed(element, { publishId }) embedForOrganization(element, { mapItem })
Who may drive it Sites on the publish's allowed origins Sites on the item's Embedding for your organization origins

Both return the same handle with the same methods. A few groups exist only on published maps - declared filters and data refresh - because a live item has no publish to declare them on. capabilities.commands always tells you exactly what you have.

What the author controls

Embedding control is switched on per map, by its author, in the Publish dialog:

  • Allowed origins. Only pages on these sites can open a control session. A map with no allowed origins can still be displayed, but cannot be driven.
  • Command groups. Camera, layers, filters, slicers, selection, scenes, presentation, popup commands, data refresh, analysis, and read state and events. All are on by default; the author can switch any off.

Both settings are part of the signed publish, so they cannot be widened by editing files or by anything your page sends.

What the API will not do

These are deliberate, permanent limits - useful to know before you design around them:

  • Nothing a reader could not do by clicking. There is no command that takes a URL, a query, a style or a layer definition. To show a different map, publish a different map.
  • Nothing the reader cannot see. featureClick carries the layer's tooltip fields only. There is no bulk read of the data behind a layer, and no access to the map's configuration, data sources or queries.
  • Only declared filters. setFilters accepts the filters the author declared and nothing else; values are bound as parameters on the server, never pasted into a query.
  • Visibility, not styling. You can show and hide a layer. You cannot recolour or restyle one.
  • Sensitivity labels are honoured. exportImage and print are refused when a label on the map's data does not allow export.

Next steps