Define area of static map image
This page explains in detail how the API URL for a static map is constructed. Using this knowledge, you can manually modify the output from our visual static map generator, or you can create the URL from scratch.
By center
To define your map image by its center, use this URL format:
https://api.maptiler.com/maps/{mapId}/static/{longitude},{latitude},{zoom}/{width}x{height}.{format}?key=YOUR_MAPTILER_API_KEY_HERE
Parameters
- mapId – The map ID identifies the map (style) that should be used. You can pick any ready-made MapTiler map or your own custom
map: Go to your MapTiler account, click on any map,
and copy its map ID from the address bar. For example, in the address
https://cloud.maptiler.com/maps/streets-v4/the map ID is “streets-v4”. Your custom maps will have IDs consisting of random letters and numbers. - lng, lat – Any location on Earth can be uniquely described by its coordinates: longitude and latitude. Get your coordinates here.
- zoom – Zoom level can range from 0 (whole world) to 22 (most detailed view).
- width, height – The image dimensions in pixels.
- format – The image format, for example
PNG. See the API reference for all supported formats. - key – Replace
YOUR_MAPTILER_API_KEY_HEREwith your own API key. Make sure to protect the key before you publish it!
Bearing and pitch aren’t supported at the moment.
Example
Get HiDPI resolution
For Retina and other high resolution displays, add @2x before the file extension to increase scale. This renders the map image in double resolution.
Example
By bounds
To define your map area by a bounding box, use this format:
https://api.maptiler.com/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}.{format}?key=YOUR_MAPTILER_API_KEY_HERE
Parameters are the same as in a center-based URL, except:
- minx, miny – Coordinates of the lower left corner of the bounding box.
- maxx, maxy – Coordinates of the upper right corner of the bounding box. The most convenient way to get the bounding box coordinates is to use the visual generator.
Example
Auto-fit
If you add at least one marker, line, or polygon to your static map, you can use auto instead of center or bounds. This will calculate the image area automatically so that all markers and paths in your query are visible. To learn more, see 👉 Static map with markers and Static map with lines or polygons.