--- title: "Static Maps API" description: "Guide for generating static map images using MapTiler Server." --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Static Maps API ## Static Maps API reference Scalar API Reference - [ Introduction ](#description/introduction) - [ Static maps ](#tag/static-maps) Close Group - Static maps - [ Center\-based image HTTP Method:  GET](#tag/static-maps/GET/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}) - [ Bounds\-based image HTTP Method:  GET](#tag/static-maps/GET/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}) - [ Auto\-fitted image HTTP Method:  GET](#tag/static-maps/GET/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}) [Powered by Scalar](https://www.scalar.com) v4.9.0 OpenAPI 3.1.0 # MapTiler Server API [Support](mailto:support@maptiler.com) [](https://support.maptiler.com) [MapTiler Server License Agreement](https://www.maptiler.com/server/license/) [Terms of Service](https://www.maptiler.com/server/license/) Server Server:http://{host}/api host MapTiler Server API Client Libraries Shell Ruby Node.js PHP Python MoreSelect from all clients Shell Curl ## Static maps ​Copy link Generate static raster images of a map. Static maps Operations - get/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format} - get/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format} - get/maps/{mapId}/static/auto/{width}x{height}{scale}.{format} ### Center-based image ​Copy link Generates a raster image based on the specified center and zoom level. Path Parameters - mapIdCopy link to mapId Type: string required Example streets Identifier of the map. See MapTiler Server Maps `http://localhost:3650/admin/`. - lonCopy link to lon Type: number required Longitude of the center of the image. - latCopy link to lat Type: number required Latitude of the center of the image. - zoomCopy link to zoom Type: number required Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.) - widthCopy link to width Type: integer required Width of the image in pixels. - heightCopy link to height Type: integer required Height of the image in pixels. - scaleCopy link to scale Type: string enum required Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required The value depends on the Map settings. values - png - jpg - webp Query Parameters - pathCopy link to path Type: string Pattern `((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))` Define path(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - markersCopy link to markers Type: string Pattern `((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)+(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))` Define marker(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - attributionCopy link to attribution Type: string enum Default bottomright Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). values - bottomright - bottomleft - topleft - topright - false - shortestCopy link to shortest Type: boolean Default false Draw the shortest paths, allow to cross the dateline. Responses - 200 OK image/\* - 400 Out of bounds / Invalid format - 404 The item does not exist - 414 URI Too Long. Maximum allowed length is 8192 bytes. Request Example for get/maps/_{mapId}_/static/_{lon}_,_{lat}_,_{zoom}_/_{width}_x_{height}__{scale}_._{format}_ Shell Curl ```curl curl http://localhost:3650/api/maps/streets/static/1,1,1/1x1.png ``` Copy Copy Status: 200Status: 400Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy OK ### Bounds-based image ​Copy link Generates a raster image based on the given bounds. Path Parameters - mapIdCopy link to mapId Type: string required Example streets Identifier of the map. See MapTiler Server Maps `http://localhost:3650/admin/`. - minxCopy link to minx Type: number required Longitude of the left (west) edge. - minyCopy link to miny Type: number required Latitude of the bottom (south) edge. - maxxCopy link to maxx Type: number required Longitude of the right (east) edge. - maxyCopy link to maxy Type: number required Latitude of the top (north) edge. - widthCopy link to width Type: integer required Width of the image in pixels. - heightCopy link to height Type: integer required Height of the image in pixels. - scaleCopy link to scale Type: string enum required Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required The value depends on the Map settings. values - png - jpg - webp Query Parameters - paddingCopy link to padding Type: number Default 0.1 Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side. - pathCopy link to path Type: string Pattern `((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))` Define path(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - markersCopy link to markers Type: string Pattern `((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)+(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))` Define marker(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - attributionCopy link to attribution Type: string enum Default bottomright Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). values - bottomright - bottomleft - topleft - topright - false - shortestCopy link to shortest Type: boolean Default false Draw the shortest paths, allow to cross the dateline. Responses - 200 OK image/\* - 400 Out of bounds / Invalid format - 404 The item does not exist - 414 URI Too Long. Maximum allowed length is 8192 bytes. Request Example for get/maps/_{mapId}_/static/_{minx}_,_{miny}_,_{maxx}_,_{maxy}_/_{width}_x_{height}__{scale}_._{format}_ Shell Curl ```curl curl http://localhost:3650/api/maps/streets/static/1,1,1,1/1x1.png ``` Copy Copy Status: 200Status: 400Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy OK ### Auto-fitted image ​Copy link Generates a raster image based on the given features. The area is calculated so that all the paths and markers given in query are visible. Path Parameters - mapIdCopy link to mapId Type: string required Example streets Identifier of the map. See MapTiler Server Maps `http://localhost:3650/admin/`. - widthCopy link to width Type: integer required Width of the image in pixels. - heightCopy link to height Type: integer required Height of the image in pixels. - scaleCopy link to scale Type: string enum required Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required The value depends on the Map settings. values - png - jpg - webp Query Parameters - paddingCopy link to padding Type: number Default 0.1 Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side. - pathCopy link to path Type: string Pattern `((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))` Define path(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - markersCopy link to markers Type: string Pattern `((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)+(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))` Define marker(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](https://docs.maptiler.com/guides/self-hosting/map-server/static-maps-in-maptiler-server). - attributionCopy link to attribution Type: string enum Default bottomright Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). values - bottomright - bottomleft - topleft - topright - false - shortestCopy link to shortest Type: boolean Default false Draw the shortest paths, allow to cross the dateline. Responses - 200 OK image/\* - 400 Out of bounds / Invalid format - 404 The item does not exist - 414 URI Too Long. Maximum allowed length is 8192 bytes. Request Example for get/maps/_{mapId}_/static/auto/_{width}_x_{height}__{scale}_._{format}_ Shell Curl ```curl curl http://localhost:3650/api/maps/streets/static/auto/1x1.png ``` Copy Copy Status: 200Status: 400Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy OK ![](https://docs.maptiler.com/assets/img/open-api.png) Using the OpenAPI Specification? Get the [openapi.yaml](https://docs.maptiler.com/_data/server/api/openapi.yml)