Static maps API

Please note that Static maps API is a paid feature.

Static maps API makes it possible to use our maps as static, non-zoomable images. Use our static maps generator to test the API and see how it works, or read the static maps guide to learn how to configure your static maps.

Using the API from JavaScript?
Client Libraries

Center-based image

GET https://api.maptiler.com/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}

Generates a raster image based on the specified center and zoom level.

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
mapId
 string
Identifier of the map. See MapTiler Maps.
Example: streets-v2
lon
 number
Longitude of the center of the image.
lat
 number
Latitude of the center of the image.
zoom
 number
Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.)
width
 integer
Width of the image in pixels.
>= 1<= 2048
height
 integer
Height of the image in pixels.
>= 1<= 2048
scale
 string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
 string
Allowed values: png jpg webp

Query Parameters

Parameters Type Description
path
 string
Define path(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))
markers
 string
Define marker(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)*(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))
latlng
 boolean
Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
Default: false
attribution
 string
Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).
Allowed values: bottomright bottomleft topleft topright false
Default: bottomright
fill
 string
Color to use as a fill when drawing polygons. Deprecated, use “path” instead.
Default: rgba(255,255,255,0.4)
stroke
 string
Color to use as a stroke when drawing polygons. Deprecated, use “path” instead.
Default: rgba(0,64,255,0.7)
width
 number
Width of the stroke line when drawing polygons (in pixels). Deprecated, use “path” instead.
Default: 1
encodedpath
 string
Path in Google Encoded Polyline Format. Deprecated, use “path” instead.
shortest
 boolean
Draw the shortest paths, allow to cross the dateline.
Default: false
Request example

  https://api.maptiler.com/maps/streets-v2/static/6.0288,44.3408,3/400x300.png?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in your MapTiler account.

Responses

Code Content Description
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.

Bounds-based image

GET https://api.maptiler.com/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}

Generates a raster image based on the given bounds.

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
mapId
 string
Identifier of the map. See MapTiler Maps.
Example: streets-v2
minx
 number
Longitude of the left (west) edge.
miny
 number
Latitude of the bottom (south) edge.
maxx
 number
Longitude of the right (east) edge.
maxy
 number
Latitude of the top (north) edge.
width
 integer
Width of the image in pixels.
>= 1<= 2048
height
 integer
Height of the image in pixels.
>= 1<= 2048
scale
 string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
 string
Allowed values: png jpg webp

Query Parameters

Parameters Type Description
padding
 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.
Default: 0.1
path
 string
Define path(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))
markers
 string
Define marker(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)*(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))
latlng
 boolean
Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
Default: false
attribution
 string
Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).
Allowed values: bottomright bottomleft topleft topright false
Default: bottomright
fill
 string
Color to use as a fill when drawing polygons. Deprecated, use “path” instead.
Default: rgba(255,255,255,0.4)
stroke
 string
Color to use as a stroke when drawing polygons. Deprecated, use “path” instead.
Default: rgba(0,64,255,0.7)
width
 number
Width of the stroke line when drawing polygons (in pixels). Deprecated, use “path” instead.
Default: 1
encodedpath
 string
Path in Google Encoded Polyline Format. Deprecated, use “path” instead.
shortest
 boolean
Draw the shortest paths, allow to cross the dateline.
Default: false
Request example

  https://api.maptiler.com/maps/streets-v2/static/-11.54,34.1,23.6,52.96/400x300.png?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in your MapTiler account.

Responses

Code Content Description
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.

Auto-fitted image

GET https://api.maptiler.com/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}

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.

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
mapId
 string
Identifier of the map. See MapTiler Maps.
Example: streets-v2
width
 integer
Width of the image in pixels.
>= 1<= 2048
height
 integer
Height of the image in pixels.
>= 1<= 2048
scale
 string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
 string
Allowed values: png jpg webp

Query Parameters

Parameters Type Description
padding
 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.
Default: 0.1
path
 string
Define path(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))
markers
 string
Define marker(s) to be drawn on top of the map. Can be used multiple times. See https://support.maptiler.com/i26-static-maps-for-your-web.
Match pattern: ((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)*(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))
latlng
 boolean
Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
Default: false
attribution
 string
Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).
Allowed values: bottomright bottomleft topleft topright false
Default: bottomright
fill
 string
Color to use as a fill when drawing polygons. Deprecated, use “path” instead.
Default: rgba(255,255,255,0.4)
stroke
 string
Color to use as a stroke when drawing polygons. Deprecated, use “path” instead.
Default: rgba(0,64,255,0.7)
width
 number
Width of the stroke line when drawing polygons (in pixels). Deprecated, use “path” instead.
Default: 1
encodedpath
 string
Path in Google Encoded Polyline Format. Deprecated, use “path” instead.
shortest
 boolean
Draw the shortest paths, allow to cross the dateline.
Default: false
Request example

  https://api.maptiler.com/maps/streets-v2/static/auto/400x300.png?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&key=YOUR_MAPTILER_API_KEY

Get your FREE API key in your MapTiler account.

Responses

Code Content Description
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.
Using the OpenAPI Specification?
Get the openapi.yaml