Embeds

An embed puts one of your maps inside a page on your own site. Your site carries a short snippet; everything else, including the basemap, loads from Sarkoa. There is no DNS setup, nothing to install, and no build step.

Getting the snippet

  1. Build the map, and set every layer on it to public. A private layer will not draw for your visitors.
  2. Set the map's access to public.
  3. On the Custom Maps page, open the map's menu and choose Copy embed code.

Paste that into your page. It is an iframe, so it works in a CMS block, a static site, a React component, or a plain HTML file.

From a script or an agent, ask for the snippet rather than assembling it:

sarkoa map embed MAP_ID --height 520 --title "Site survey, March 2026"
sarkoa map embed MAP_ID --url-only

MCP exposes the same thing as get_embed_code, which also warns you when the map is not public yet.

<iframe
  src="https://maps.sarkoa.com/map/embed/<map-id>"
  width="100%"
  height="520"
  style="border:0"
  loading="lazy"
  title="Site survey, March 2026"
></iframe>

Two things to set yourself, because they depend on your page rather than on the map:

  • A title. Screen readers announce it, and an untitled iframe is announced as nothing useful.
  • loading="lazy" if the map is below the fold. A map is a real application, and there is no reason to boot it before someone scrolls to it.

Leave the rest of the URL alone. The embed path is /map/embed/<map-id>, and a bare maps.sarkoa.com/<map-id> is not it: that form is read as an organization address and redirected away from the map host, so the frame comes back empty with nothing in it to explain why.

Sizing

Give the iframe a height. An iframe with no height collapses to almost nothing, which is the most common reason an embed looks broken on first paste.

For a fixed banner, a pixel height is fine. For a responsive block, wrap it in an element with an aspect ratio:

<div style="position:relative;aspect-ratio:16/9">
  <iframe
    src="https://maps.sarkoa.com/map/embed/<map-id>"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    loading="lazy"
    title="Site survey, March 2026"
  ></iframe>
</div>

On phones, a 16:9 map is short. Something nearer 4:3 or 1:1 usually reads better on a narrow screen.

What visitors can do

By default an embedded map pans, zooms, and shows the legend and layer list you configured. Visitors do not need a Sarkoa account and are never asked to sign in.

What they see is what you set in the map builder: the opening camera position, zoom limits, pan bounds, and whether the layers panel and legend start open. If an embed opens somewhere unexpected, that is the map's default view, not the embed.

Filters you added to the map work inside the embed too, which is what makes an embedded map worth more than a screenshot.

Branding

  • Free: the map carries Sarkoa attribution.
  • Community: add your own theme, accent colour, and attribution alongside Sarkoa's.
  • Essential: white-label embeds, with Sarkoa branding removed.
  • Pro: serve embeds from your own domain.

Cost

Every tile an embed loads counts against the organization that hosts the data, which is yours. Visitors are never billed.

That matters most when the same map is embedded across many pages, or when a page auto-refreshes. Both raise tile volume without raising visitor count. See Tile requests for how to estimate the traffic, and the Fair Use Policy for the guidelines on paid unlimited plans.

Updating a published embed

Edit the map and the change is live. The snippet on your site points at the map, not at a copy of it, so you never re-paste anything.

The same is true of the data. Replacing a file updates every map and every embed that uses it.

When it does not work

The map is blank. Its access is probably still set to organization. Set it to public.

The frame loads something that is not your map. Check the URL is /map/embed/<map-id> and not a bare map id. Copying the snippet from the app, sarkoa map embed, or get_embed_code avoids this entirely.

Some layers are missing. Those layers are still private. Public map access and public file access are separate settings, and both have to be on. See Sharing and access.

The iframe is a thin strip. No height is set. See Sizing above.

It works for you but not for a colleague. You are signed in and they are not. Open the embed URL in a private window to see what a visitor sees.