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 – Unique identifier of the map style. You can use any ready-made map or your own custom style: In your MapTiler account, click on a 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”. - lng, lat – Coordinates of the map image center (longitude and latitude). Get your coordinates here.
- zoom – Zoom level 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 publishing your map app!
Tilt 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.