Static Map Image with Leaflet
LeafletDisplay a non-interactive map image using the MapTiler Static Maps API: perfect for thumbnails, emails, and social previews.
const img = document.createElement('img');
img.src = 'https://api.maptiler.com/maps/streets-v4/static/2.3522,48.8566,13/600x400.png?key=YOUR_MAPTILER_KEY';
img.alt = 'Static map of Paris';
img.style.cssText = 'width:100%;max-width:600px;display:block;margin:0 auto 20px;border:2px solid #2a2a2a;';
document.getElementById('map').before(img);
const map = L.map('map').setView([48.8566, 2.3522], 13);
L.tileLayer('https://api.maptiler.com/maps/streets-v4/256/{z}/{x}/{y}.png?key=YOUR_MAPTILER_KEY', {
tileSize: 256,
attribution: '© <a href="https://www.maptiler.com/">MapTiler</a> © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap contributors</a>'
}).addTo(map);How it works
The MapTiler Static Maps API returns a plain PNG image for any location, zoom level, and size. The URL pattern is https://api.maptiler.com/maps/{style}/static/{lng},{lat},{zoom}/{width}x{height}.png?key=YOUR_MAPTILER_KEY. This is ideal for contexts where JavaScript cannot run: email newsletters, social media previews, or lightweight thumbnails.
In this example, a static image is inserted above the map container using document.createElement('img'). Below it, a standard interactive Leaflet map loads the same area for comparison. This pattern works well for progressive enhancement: show the static image first, then load the interactive map when resources allow.
Key APIs
| API | Description | Docs |
|---|---|---|
| MapTiler Static Maps API | Generate map images via URL | docs.maptiler.com/cloud/api/static-maps |
L.map() |
Create an interactive map | leafletjs.com/reference.html#map |
L.tileLayer() |
Add raster tile layer | leafletjs.com/reference.html#tilelayer |
FAQ
What image sizes are supported by the Static Maps API?
The maximum size is 2048x2048 pixels. Common choices are 600x400 for cards and 1200x630 for Open Graph social previews.
Can I add markers to the static image?
Yes. Append marker parameters to the URL, for example &markers=2.2945,48.8584. See the MapTiler Static Maps documentation for the full marker syntax.
How does the coordinate order work in the static URL?
The Static Maps API uses lng,lat order in the URL path: the same as GeoJSON. This is the opposite of Leaflet’s [lat, lng] JavaScript convention.
Common mistakes
- Using
lat,lngorder in the static URL: the API expectslng,lat - Requesting images larger than 2048x2048: the API will return an error
- Forgetting the API key parameter: the image request will fail with a 403 response
Build maps using Leaflet with AI
Generate code like this static map image with leaflet example using the Leaflet skill in your IDE.
Related Examples
- Initialize a Leaflet Map with MapTiler Tiles
- See how to do this in MapLibre GL JS, MapTiler SDK or OpenLayers