Diesen Artikel gibt es noch nicht auf Deutsch — Sie lesen ihn auf Englisch.

How to Embed an OSM Map on Your Website: Embed SDK Guide

2026-03-106 min read
EmbedSDKJavaScriptiframewidget
How to Embed an OSM Map on Your Website: Embed SDK Guide

An interactive map is one of the most sought-after elements for business websites, travel blogs, real estate platforms, and logistics dashboards. You can embed an OpenStreetMap in two ways: a simple iframe or a small JavaScript SDK that builds that iframe for you from options. Let's explore both approaches.

Why Embed an OSM Map

Google Maps API costs money after a certain request threshold. OpenStreetMap is a completely free alternative with open data. An embedded OSM map:

  • Requires no Google API key and is independent of Google's pricing policies
  • Shows up-to-date data maintained by a community of 10 million mappers
  • Is configurable: six base maps to choose from, a marker with a label, a display area, a caption
  • Works without display count limitations

Method 1: iframe — Quick and Simple

The simplest option is to insert an iframe code into your page. No JavaScript required.

<iframe
  src="https://osm2cdr.com/embed?lat=55.7558&lon=37.6173&zoom=14&style=standard"
  width="100%"
  height="400"
  frameborder="0"
  allowfullscreen>
</iframe>

iframe Parameters

Parameter Description Example
lat, lon Map center (latitude, longitude) lat=48.8566&lon=2.3522
zoom Zoom level (1-18), default 14 zoom=14
style Base map: standard, voyager, dark_matter, positron, hot, topo style=positron
bbox Area min_lon,min_lat,max_lon,max_lat — overrides center and zoom bbox=37.60,55.74,37.64,55.76
marker Marker: lat,lon or lat,lon,popup text marker=55.7539,37.6208,Red%20Square
title Caption in the map corner (up to 200 characters) title=Our%20office
controls Zoom buttons, default true controls=false
scrollwheel Mouse wheel zoom, default true scrollwheel=false
branding osm2cdr.com badge, default true branding=false

The six base maps: standard is classic OSM, voyager is a light CARTO map with labels, dark_matter is dark, positron is light and minimal, hot is the Humanitarian OSM style, topo is OpenTopoMap topography. You can also pass a style name from the wizard (for example vintage or dark_pro) and the widget picks the closest base map by tone. An unknown name falls back to standard.

Method 2: JavaScript SDK

The SDK is a thin wrapper: OSM2CDR.embed builds the /embed URL from your options and inserts an iframe into your container. The map can do exactly what the iframe can, but options are passed as an object and are easy to fill from your own data.

Setup

<script src="https://osm2cdr.com/sdk.js"></script>
<div id="map" style="width: 100%; height: 400px;"></div>

Embedding a Map

OSM2CDR.embed('map', {
  lat: 55.7558,   // Moscow
  lon: 37.6173,
  zoom: 14,
  style: 'standard',
  title: 'Central Moscow',
  width: '100%',
  height: '400px'
});

The first argument is an element id or the DOM element itself. The function returns the created iframe (or null if the container is not found). Instead of a center you can pass an area: bbox: [37.60, 55.74, 37.64, 55.76] (min_lon, min_lat, max_lon, max_lat).

Marker

OSM2CDR.embed('map', {
  lat: 55.7539,
  lon: 37.6208,
  zoom: 16,
  marker: { lat: 55.7539, lon: 37.6208, popup: 'Red Square' }
});

The widget shows one marker with a text popup. If you need many points, clustering, or custom HTML popups, use Leaflet or MapLibre directly; the SDK is not meant for that.

Choosing a Style

The style is set with the style option when embedding. There are six base maps: standard, voyager, dark_matter, positron, hot, topo:

OSM2CDR.embed('map', { lat: 55.7558, lon: 37.6173, zoom: 13, style: 'dark_matter' });

To change the style, call OSM2CDR.embed again on the same container; the old iframe is replaced with a new one.

Controls and Scrolling

OSM2CDR.embed('map', {
  lat: 55.7558,
  lon: 37.6173,
  controls: false,     // no zoom buttons
  scrollwheel: false,  // the mouse wheel scrolls the page, not the map
  branding: false      // no osm2cdr.com badge
});

Responsiveness and Mobile Devices

The iframe width and height come from the width and height options (default 100% and 400px). For mobile devices, a percentage width and a viewport-based height work well:

OSM2CDR.embed('map', { lat: 55.7558, lon: 37.6173, width: '100%', height: '50vh' });

To keep the map from capturing page scrolling, disable wheel zoom: scrollwheel: false.

A Static Image Instead of a Map

If you don't need interactivity (emails, product cards, previews), use OSM2CDR.staticMap: it inserts an <img> from /api/staticmap:

OSM2CDR.staticMap('preview', {
  lat: 55.7558,
  lon: 37.6173,
  zoom: 14,
  width: 600,      // pixels
  height: 400,
  style: 'positron',
  format: 'png'    // or 'jpeg'
});

Need just the URL without inserting anything? OSM2CDR.url('embed', opts) and OSM2CDR.url('static', opts) return a ready link.

Exporting the Area to a File

The embedded widget only displays the map; it has no export button. To get the same area as a file (PDF, SVG, DXF, CDR, GeoJSON and 60+ other formats), select it in the wizard at osm2cdr.com; you can put a plain link to the site next to the map.

Use Case Examples

Real Estate Website

OSM2CDR.embed('property-map', {
  lat: property.lat,
  lon: property.lon,
  zoom: 16,
  style: 'positron',
  marker: { lat: property.lat, lon: property.lon, popup: property.address }
});

Travel Blog

<iframe
  src="https://osm2cdr.com/embed?lat=41.9028&lon=12.4964&zoom=13&style=voyager"
  width="100%" height="450" frameborder="0">
</iframe>

Logistics Dashboard

OSM2CDR.embed('logistics', {
  bbox: [37.30, 55.55, 37.95, 55.95],
  style: 'dark_matter',
  scrollwheel: false
});

Performance and Lazy Loading

The sdk.js file is under 10 KB even uncompressed. The iframe the SDK creates is already marked loading="lazy", so the browser loads the map only when it approaches the viewport. If a page has many maps and you prefer not to call the SDK up front, embed them as the user scrolls:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      OSM2CDR.embed(entry.target, { lat: 55.75, lon: 37.62, zoom: 14 });
      observer.unobserve(entry.target);
    }
  });
});
document.querySelectorAll('.lazy-map').forEach(el => observer.observe(el));

Common Mistakes

  1. Map doesn't display — the container or the height option needs an explicit height. height: 100% won't work without a parent height.
  2. Wrong bbox order — the area is passed as min_lon,min_lat,max_lon,max_lat: longitude first, then latitude.
  3. Expecting map events and methods — the SDK inserts an iframe and gives no programmatic access to the map inside it. To update the map, call OSM2CDR.embed again with new options.

Embedding an OSM map on your website takes 5 minutes with an iframe and only slightly longer with the SDK. Both options are free and require no third-party API keys.

← All articles