const img = document.createElement('img'); img.src = 'https://api.maptiler.com/maps/streets-v4/static/14.42,50.08,13/600x400.png?key=YOUR_MAPTILER_KEY'; img.alt = 'Static map of Prague'; 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 = new maplibregl.Map({ container: 'map', style: 'https://api.maptiler.com/maps/streets-v4/style.json?key=YOUR_MAPTILER_KEY', center: [14.42, 50.08], zoom: 13 });

How it works

The MapTiler Static Maps API generates a PNG image from a URL with the pattern https://api.maptiler.com/maps/{style}/static/{lng},{lat},{zoom}/{width}x{height}.png?key=YOUR_MAPTILER_KEY. This produces a map snapshot without any JavaScript: useful for emails, thumbnails, and Open Graph images.

This example places a static image above the MapLibre map container. The static image loads instantly as a simple <img> tag, while the interactive WebGL map initializes below. Both show the same area of Prague for comparison. This is a common progressive enhancement pattern.

Key APIs

API	Description	Docs
MapTiler Static Maps API	Generate map images via URL	docs.maptiler.com/cloud/api/static-maps
`maplibregl.Map`	Create a WebGL map	maplibre.org docs

FAQ

Can I match the static image style to the interactive map?

Yes. Use the same style name in both the static URL path and the MapLibre style JSON URL. For example, streets-v4 in both places.

What is the maximum resolution for the static image?

Up to 2048x2048 pixels. For HiDPI displays, request a larger image and scale it down with CSS.

Common mistakes

Using lat,lng order in the static URL: the API expects lng,lat (same as MapLibre)
Forgetting the API key: the static image request returns a 403 error
Using a vector style name that does not have a raster static endpoint: stick to standard MapTiler styles

Static Map Image with MapLibre GL JS

How it works

Key APIs

FAQ

Common mistakes

Build maps using MapLibre GL JS with AI

Related Examples