--- title: "Static maps API" description: "API for generating non-interactive static map images." --- > 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** makes it possible to use our maps as non-interactive, non-zoomable images. Adding [markers](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-markers/) or [lines](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-lines/) to static maps is also supported. Note Static maps **don’t work with a free plan**. Get them with [any paid plan](https://www.maptiler.com/cloud/pricing/), including our most affordable tier. ## How to use the API - Directly - With the [Static maps Client JS](https://docs.maptiler.com/client-js/#%EF%B8%8F-static-maps) library Key You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/) and [learn how to secure it](https://docs.maptiler.com/guides/credentials/api-key/#secure-key). ### Getting started - Use our [visual generator](https://www.maptiler.com/cloud/static-maps/generator/) to test the API and quickly build your static map’s URL. - See the [static maps guide](https://docs.maptiler.com/guides/maps-apis/static-maps/static-maps-for-your-web/) to learn how to configure static maps and see practical usage examples. - Learn how to [make a map non-interactive](https://docs.maptiler.com/sdk-js/examples/interactive-false/) with MapTiler SDK JS. * * * ## 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) v1.0 OpenAPI 3.1.0 # MapTiler API [Support](mailto:support@maptiler.com) [](https://docs.maptiler.com/support/requests/) [Terms of Service](https://www.maptiler.com/terms/) Server Server:https://api.maptiler.com MapTiler API ## AuthenticationRequired Selected Auth Type: key

Your own API key from https://cloud.maptiler.com/

Name :

Value :

Client Libraries Shell Ruby Node.js PHP Python MoreSelect from all clients Shell Curl ## Static maps Copy link 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 Auth Required Generates a raster image based on the specified center and zoom level. Path Parameters - mapIdCopy link to mapId Type: string required Example streets-v4 Identifier of the map. See [MapTiler Maps](https://cloud.maptiler.com/maps/). - 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 min: 1 max: 2048 required Width of the image in pixels. - heightCopy link to height Type: integer min: 1 max: 2048 required Height of the image in pixels. - scaleCopy link to scale enum const: @2x Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required 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 map with lines or polygons](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-lines/). - 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 map with markers](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-markers/). - latlngCopy link to latlng Type: boolean Use \[latitude, longitude\] order for coordinates instead of \[longitude, latitude\]. - attributionCopy link to attribution Type: string enum 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 - fillCopy link to fill Type: string deprecated Color to use as a fill when drawing polygons. Deprecated, use "path" instead. - strokeCopy link to stroke Type: string deprecated Color to use as a stroke when drawing polygons. Deprecated, use "path" instead. - widthCopy link to width Type: number deprecated Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead. - encodedpathCopy link to encodedpath Type: string deprecated Path in [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). Deprecated, use "path" instead. - shortestCopy link to shortest Type: boolean Draw the shortest paths, allow to cross the dateline. Responses - 200 image/\* - 400 Out of bounds / Invalid format / Invalid image size - 403 Key is missing, invalid or restricted - 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 'https://api.maptiler.com/maps/streets-v4/static/1,1,1/1x1@2x.png?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}) Status: 200Status: 400Status: 403Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy ### Bounds-based image Copy link Auth Required Generates a raster image based on the given bounds. Path Parameters - mapIdCopy link to mapId Type: string required Example streets-v4 Identifier of the map. See [MapTiler Maps](https://cloud.maptiler.com/maps/). - 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 min: 1 max: 2048 required Width of the image in pixels. - heightCopy link to height Type: integer min: 1 max: 2048 required Height of the image in pixels. - scaleCopy link to scale enum const: @2x Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required values - png - jpg - webp Query Parameters - paddingCopy link to padding Type: number 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 map with lines or polygons](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-lines/). - 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 map with markers](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-markers/). - latlngCopy link to latlng Type: boolean Use \[latitude, longitude\] order for coordinates instead of \[longitude, latitude\]. - attributionCopy link to attribution Type: string enum 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 - fillCopy link to fill Type: string deprecated Color to use as a fill when drawing polygons. Deprecated, use "path" instead. - strokeCopy link to stroke Type: string deprecated Color to use as a stroke when drawing polygons. Deprecated, use "path" instead. - widthCopy link to width Type: number deprecated Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead. - encodedpathCopy link to encodedpath Type: string deprecated Path in [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). Deprecated, use "path" instead. - shortestCopy link to shortest Type: boolean Draw the shortest paths, allow to cross the dateline. Responses - 200 image/\* - 400 Out of bounds / Invalid format / Invalid image size - 403 Key is missing, invalid or restricted - 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 'https://api.maptiler.com/maps/streets-v4/static/1,1,1,1/1x1@2x.png?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}) Status: 200Status: 400Status: 403Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy ### Auto-fitted image Copy link Auth Required 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-v4 Identifier of the map. See [MapTiler Maps](https://cloud.maptiler.com/maps/). - widthCopy link to width Type: integer min: 1 max: 2048 required Width of the image in pixels. - heightCopy link to height Type: integer min: 1 max: 2048 required Height of the image in pixels. - scaleCopy link to scale enum const: @2x Use "@2x" to get "retina"/HiDPI image. values - @2x - formatCopy link to format Type: string enum required values - png - jpg - webp Query Parameters - paddingCopy link to padding Type: number 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 map with lines or polygons](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-lines/). - 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 map with markers](https://docs.maptiler.com/guides/maps-apis/static-maps/static-map-with-markers/). - latlngCopy link to latlng Type: boolean Use \[latitude, longitude\] order for coordinates instead of \[longitude, latitude\]. - attributionCopy link to attribution Type: string enum 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 - fillCopy link to fill Type: string deprecated Color to use as a fill when drawing polygons. Deprecated, use "path" instead. - strokeCopy link to stroke Type: string deprecated Color to use as a stroke when drawing polygons. Deprecated, use "path" instead. - widthCopy link to width Type: number deprecated Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead. - encodedpathCopy link to encodedpath Type: string deprecated Path in [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). Deprecated, use "path" instead. - shortestCopy link to shortest Type: boolean Draw the shortest paths, allow to cross the dateline. Responses - 200 image/\* - 400 Out of bounds / Invalid format / Invalid image size - 403 Key is missing, invalid or restricted - 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 'https://api.maptiler.com/maps/streets-v4/static/auto/1x1@2x.png?key=YOUR_MAPTILER_API_KEY' ``` Copy Copy Test Request(get /maps/{mapId}/static/auto/{width}x{height}{scale}.{format}) Status: 200Status: 400Status: 403Status: 404Status: 414 Show Schema ```json @filename ``` Copy Copy ![](https://docs.maptiler.com/assets/img/open-api.png) Using the OpenAPI Specification? Get the [openapi.yaml](https://docs.maptiler.com/_data/cloud/api/openapi.yml)