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

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
- Map doesn't display — the container or the
heightoption needs an explicit height.height: 100%won't work without a parent height. - Wrong bbox order — the area is passed as
min_lon,min_lat,max_lon,max_lat: longitude first, then latitude. - 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.embedagain 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.