maptilersdk.config.apiKey = 'YOUR_MAPTILER_KEY'; const img = document.createElement('img'); img.src = 'https://api.maptiler.com/maps/streets-v4/static/12.4964,41.9028,13/600x400.png?key=YOUR_MAPTILER_KEY'; img.alt = 'Static map of Rome'; 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 maptilersdk.Map({ container: 'map', style: maptilersdk.MapStyle.STREETS, center: [12.4964, 41.9028], zoom: 13 });

How it works

The MapTiler Static Maps API produces a PNG image from a simple URL: https://api.maptiler.com/maps/{style}/static/{lng},{lat},{zoom}/{width}x{height}.png?key=YOUR_MAPTILER_KEY. This image loads without JavaScript, making it ideal for email templates, social media cards, and lightweight previews.

Here the static image is inserted before the map container, showing Rome. The interactive MapTiler SDK map loads below using the same style and coordinates. You can use the static image as a placeholder while the WebGL map initializes, or as a standalone image where interactivity is not needed.

Key APIs

API	Description	Docs
MapTiler Static Maps API	Generate map images via URL	docs.maptiler.com/cloud/api/static-maps
`maptilersdk.Map`	Create an interactive map	docs.maptiler.com/sdk-js/api/
`maptilersdk.MapStyle`	Built-in style constants	docs.maptiler.com/sdk-js/api/

FAQ

Can I use MapStyle constants for the static image URL?

No. The static API is a REST endpoint: use the style name string (e.g., streets-v4) directly in the URL path. The maptilersdk.MapStyle constants are for the interactive map only.

What is the maximum image size?

2048x2048 pixels. For retina displays, request double the display size and use CSS to scale the image down.

Common mistakes

Using maptilersdk.MapStyle.STREETS in the static URL: use the string streets-v4 instead
Swapping latitude and longitude in the static URL: the API expects lng,lat order
Forgetting to set maptilersdk.config.apiKey before creating the interactive map

Static Map Image with MapTiler SDK

How it works

Key APIs

FAQ

Common mistakes

Build maps using MapTiler SDK with AI

Related Examples