Skip to main content

Embed in HTML

A maproll map is a plain image URL. The simplest embed is a single <img> tag. This page covers the common patterns: basic embed, SVG/PNG fallback, and Open Graph / Twitter card meta tags for social previews.

Basic <img> embed​

For most pages, this is everything you need:

<img
  src="https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,DE:95,FR:40&theme=light"
  alt="World choropleth — GDP index"
  width="800"
/>

Use .svg when the map will be displayed at multiple sizes or on high-DPI screens — the SVG scales losslessly. Use .png when you need pixel-exact output or when the embedding context does not support SVG (email clients, some CMSs).

The width attribute should match the actual display width. The API generates an SVG at width=1200 by default; scaling it down via CSS is fine for SVG but will cause resampling artefacts for PNG. If you display a PNG at 600 px, request it at 600 px:

<img
  src="https://api.maproll.io/map.png?scope=world&data=US:200,CN:150&theme=light&width=600"
  alt="World choropleth"
  width="600"
/>

Add loading="lazy" for images that appear below the fold:

<img
  src="https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150&theme=light"
  alt="World choropleth"
  width="800"
  loading="lazy"
/>

SVG with PNG fallback (<picture>)​

Browsers that support <picture> can serve SVG to modern clients and PNG to older ones. This is rarely necessary but useful when embedding in a context where SVG support is uncertain:

<picture>
  <source
    srcset="https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,DE:95&theme=light"
    type="image/svg+xml"
  />
  <img
    src="https://api.maproll.io/map.png?scope=world&data=US:200,CN:150,DE:95&theme=light&width=800"
    alt="World choropleth"
    width="800"
  />
</picture>

The <img> inside <picture> is the fallback — it loads when the browser does not support <source type="image/svg+xml">. Make sure its width matches your intended display width to avoid resampling.

Open Graph and Twitter card meta tags​

To show a map preview when a page is shared on social platforms, add Open Graph and Twitter meta tags pointing to a PNG render. Use a fixed width of 1200 px — the canonical Open Graph image size — and keep the URL short enough to fit under the 2048-character browser limit.

<head>
  <meta property="og:title" content="Q2 2025 Market Coverage" />
  <meta property="og:description" content="Countries covered by our distribution network." />
  <meta
    property="og:image"
    content="https://api.maproll.io/map.png?scope=world&regions=US,CA,MX,GB,DE,FR,IT,ES&theme=light-blue&width=1200"
  />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="526" />
  <meta property="og:image:type" content="image/png" />

  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content="Q2 2025 Market Coverage" />
  <meta
    name="twitter:image"
    content="https://api.maproll.io/map.png?scope=world&regions=US,CA,MX,GB,DE,FR,IT,ES&theme=light-blue&width=1200"
  />
</head>

A few things to keep in mind:

  • Use PNG, not SVG, for social previews. Most social crawlers (Facebook, Twitter/X, LinkedIn, Slack) do not render SVG in unfurl previews. Request .png explicitly.
  • Set og:image:height correctly. The height depends on the scope and projection. For scope=world with the default Natural Earth projection, width=1200 produces height=526. For subnational scopes the aspect ratio varies. You can discover the height by requesting the map once and reading the rendered SVG height attribute, or by leaving og:image:height unset and letting crawlers detect it.
  • The URL is a cache key. The API returns Cache-Control: public, max-age=31536000, immutable, so social crawlers and CDNs will cache the image by URL. If your data changes, update the URL (add a version query param or change a value) to get a fresh crawl.
  • <iframe> is not recommended. An iframe creates a separate browsing context, adds scrollbars unless explicitly sized, and gives you less control over layout. Use <img> for static embeds.

Caching and ETags​

The API returns an ETag header. Browsers and CDNs send If-None-Match on the next request; if the map hasn't changed, the server responds 304 Not Modified with no body. This means repeated embeds of the same map URL are effectively free after the first load.

For more detail on caching behavior, see Response headers.