Static Maps API

Using the API from JavaScript?

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 Cloud Maps.
Example: streets
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.
height
integer
Height of the image in pixels.
scale
string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
string
The value depends on the Map settings.
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/static/6.0288,44.3408,3/400x300.png?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 image/*
400

Out of bounds / Invalid format

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 Cloud Maps.
Example: streets
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.
height
integer
Height of the image in pixels.
scale
string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
string
The value depends on the Map settings.
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/static/-11.54,34.1,23.6,52.96/400x300.png?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 image/*
400

Out of bounds / Invalid format

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 Cloud Maps.
Example: streets
width
integer
Width of the image in pixels.
height
integer
Height of the image in pixels.
scale
string
Use “@2x” to get “retina”/HiDPI image.
Allowed values: @2x
format
string
The value depends on the Map settings.
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/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 the MapTiler Cloud.

Responses

Code Content Description
200 image/*
400

Out of bounds / Invalid format

403

Key is missing, invalid or restricted

404

The item does not exist

414

URI Too Long. Maximum allowed length is 8192 bytes.