Static maps in MapTiler Server

If you need a static non-zoomable image of a map for your web or graphic design, you can generate it using one of the pre-defined styles or using your own design. MapTiler Server offers this feature to everybody running MapTiler Server on their own infrastructure, completely offline.

Screenshot 2023-08-01 at 16.49 1 (1).png

The Static maps interface in the MapTiler Server

MapTiler Server Static maps

There are two major ways to request a static map image from MapTiler Server:

1. The first is the center-based approach, where you define the center point of your polygon and then the size of the area covered by your desired static map. Here is a short example of a center-based request.
More info about format and values in MapTiler Server API.

Center-based URL:
http://localhost:3650/api/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}

Request example:http://localhost:3650/api/maps/streets/static/6.0288,44.3408,3/400x300.png

2. The second is the bounds-based approach, where you define the top left and lower right corner of your area, plus the zoom level of a static map. Here is a short example of the bounds-based request.
More info about format and values in MapTiler Server API.

Bounds-based URL:http://localhost:3650/api/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}

Request example:http://localhost:3650/api/maps/streets/static/-11.54,34.1,23.6,52.96/400x300.png

Autofitting the area

It is also possible to use the auto function instead of the region specification (center or bounds) in the URL. In such a case, the area will be automatically calculated based on a path from the query (at least one polygon or marker has to be specified). See the documentation of the format and possible values below.

Adding polygons and lines

The polygon or polyline can be passed in a path query parameter (it can be used more than once). Coordinates of the individual path vertices are comma-separated lng,lat pairs. The vertices are separated with a pipe symbol. Additionally, the following special “commands” can be used (in the form of key:value appended before the path coordinates):

  • fill - color to use as the fill (e.g. red, rgba(255,255,255,0.5), #0000ff, none, false)
  • stroke - the color of the path stroke
  • width - width of the stroke (in pixels)
  • enc - Path encoded according to Google Encoded Polyline Format
    • -e.g. _p~iF~ps|U_ulLnnqC_mqNvxq@ \- If used, the rest of the path` parameter is considered to be part of the encoded polyline string -- do not specify the coordinate pairs.
  • You can also use fill, stroke and width as separate query parameters to specify default styling for all the paths.

Examples:

  • path=5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8
    • a polygon with default colors
  • path=stroke:green|width:3|fill:none|5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8
    • the same polygon, but with 3px green stroke and no fill
  • path=stroke:red|fill:none|enc:_p~iF~ps|U_ulLnnqC_mqNvxq@`
    • draws a red line based on the encoded polyline

Adding markers

The markers can be passed in a markers query parameter (it can be used more than once). Each marker is a comma-separated lng,lat pair. Individual markers are separated with a pipe symbol. Each marker can also have a different color - specified as the 3rd parameter (e.g. 14.4,50.1,red|8.6,47.4,blue). Additionally, the following special “commands” can be used (in the form of key:value appended before the marker coordinates):

  • icon - URL to a remote image (URL-encoded)
    • You can use a URL shortener service to create more compact queries.
    • The icon has to be at most 64 kB and 4096 pixels (e.g., 64x64 image).
    • If used, the specified colors of the markers are ignored.
  • anchor - the anchor point of the custom icon, possible values:
    • top, left, bottom, right, center, topleft, bottomleft, topright, bottomright
    • the default value is bottom
  • scale - the scale of the image (useful if you want to provide a HiDPI image that scales down correctly), the default value is 1

Examples:

  • markers=14.4,50.1|8.6,47.4|2.4,48.9 - 3 separate markers will be displayed
  • markers=14.4,50.1,red|8.6,47.4,blue - 1 red and 1 blue marker
  • markers=icon:https://tinyurl.com/yakrjl3t|anchor:center|14.4,50.1|8.6,47.4
    • 2 markers with the specified custom icon centered at their positions

Other

  • attribution
    • change the location of the attribution text:topleft, bottomleft, topright, bottomright
    • attribution=false or attribution=0to disable attribution (make sure to display the correct attribution yourself in case you use this)
  • padding - “percentage” padding for fitted endpoints (bounds-based and auto)
    • e.g., value of 0.1 means “add 10% size to each side to make sure the area of interest is nicely visible”

Conclusion

Slippy maps are not the best option for all use cases. Sometimes you need to render a static map that shows the closest area surrounding a specific POI and place it to a website (a pizza spot or a car dealership). In such cases (if you run your maps on-prem) MapTiler Server static maps API is the best solution for you.

MapTiler Server API - Static maps
MapTiler Cloud API - Static maps