Static maps API

Static maps API makes it possible to use our maps as non-interactive, non-zoomable images. Adding markers or lines to static maps is also supported.

Note

Static maps don’t work with a free plan. Get them with any paid plan, including our most affordable tier.

How to use the API

Directly
With the Static maps Client JS library

Key

You need a MapTiler API key to use this service. Get it here and learn how to secure it.

Getting started

Use our visual generator to test the API and quickly build your static map’s URL.
See the static maps guide to learn how to configure static maps and see practical usage examples.
Learn how to make a map non-interactive with MapTiler SDK JS.

Static maps API reference

Scalar API Reference

v1.0

OpenAPI 3.1.0

MapTiler API

Support

Server

MapTiler API

Client Libraries

Shell Curl

Static maps

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

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

Path Parameters

mapId
Type: string
required

Identifier of the map. See MapTiler Maps.
lon
Type: number
required

Longitude of the center of the image.
lat
Type: number
required

Latitude of the center of the image.
zoom
Type: number
required

Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.)
width
Type: integer
min:
1
max:
2048
required

Width of the image in pixels.
height
Type: integer
min:
1
max:
2048
required

Height of the image in pixels.
scale
enum
const:
@2x

Use "@2x" to get "retina"/HiDPI image.
values
- @2x
format
Type: string enum
required
values
- png
- jpg
- webp

Query Parameters

path
Type: string

Define path(s) to be drawn on top of the map. Can be used multiple times. See Static map with lines or polygons.
markers
Type: string

Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static map with markers.
latlng
Type: boolean

Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
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
fill
Type: string
deprecated

Color to use as a fill when drawing polygons. Deprecated, use "path" instead.
stroke
Type: string
deprecated

Color to use as a stroke when drawing polygons. Deprecated, use "path" instead.
width
Type: number
deprecated

Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead.
encodedpath
Type: string
deprecated

Path in Google Encoded Polyline Format. Deprecated, use "path" instead.
shortest
Type: boolean

Draw the shortest paths, allow to cross the dateline.

Responses

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.

get/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}

curl 'https://api.maptiler.com/maps/streets-v4/static/1,1,1/1x1@2x.png?key=YOUR_MAPTILER_API_KEY'

Show Schema

@filename

Bounds-based image

Generates a raster image based on the given bounds.

Path Parameters

mapId
Type: string
required

Identifier of the map. See MapTiler Maps.
minx
Type: number
required

Longitude of the left (west) edge.
miny
Type: number
required

Latitude of the bottom (south) edge.
maxx
Type: number
required

Longitude of the right (east) edge.
maxy
Type: number
required

Latitude of the top (north) edge.
width
Type: integer
min:
1
max:
2048
required

Width of the image in pixels.
height
Type: integer
min:
1
max:
2048
required

Height of the image in pixels.
scale
enum
const:
@2x

Use "@2x" to get "retina"/HiDPI image.
values
- @2x
format
Type: string enum
required
values
- png
- jpg
- webp

Query Parameters

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.
path
Type: string

Define path(s) to be drawn on top of the map. Can be used multiple times. See Static map with lines or polygons.
markers
Type: string

Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static map with markers.
latlng
Type: boolean

Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
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
fill
Type: string
deprecated

Color to use as a fill when drawing polygons. Deprecated, use "path" instead.
stroke
Type: string
deprecated

Color to use as a stroke when drawing polygons. Deprecated, use "path" instead.
width
Type: number
deprecated

Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead.
encodedpath
Type: string
deprecated

Path in Google Encoded Polyline Format. Deprecated, use "path" instead.
shortest
Type: boolean

Draw the shortest paths, allow to cross the dateline.

Responses

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.

get/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}

curl 'https://api.maptiler.com/maps/streets-v4/static/1,1,1,1/1x1@2x.png?key=YOUR_MAPTILER_API_KEY'

Show Schema

@filename

Auto-fitted image

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

mapId
Type: string
required

Identifier of the map. See MapTiler Maps.
width
Type: integer
min:
1
max:
2048
required

Width of the image in pixels.
height
Type: integer
min:
1
max:
2048
required

Height of the image in pixels.
scale
enum
const:
@2x

Use "@2x" to get "retina"/HiDPI image.
values
- @2x
format
Type: string enum
required
values
- png
- jpg
- webp

Query Parameters

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.
path
Type: string

Define path(s) to be drawn on top of the map. Can be used multiple times. See Static map with lines or polygons.
markers
Type: string

Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static map with markers.
latlng
Type: boolean

Use [latitude, longitude] order for coordinates instead of [longitude, latitude].
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
fill
Type: string
deprecated

Color to use as a fill when drawing polygons. Deprecated, use "path" instead.
stroke
Type: string
deprecated

Color to use as a stroke when drawing polygons. Deprecated, use "path" instead.
width
Type: number
deprecated

Width of the stroke line when drawing polygons (in pixels). Deprecated, use "path" instead.
encodedpath
Type: string
deprecated

Path in Google Encoded Polyline Format. Deprecated, use "path" instead.
shortest
Type: boolean

Draw the shortest paths, allow to cross the dateline.

Responses

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.

get/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}

curl 'https://api.maptiler.com/maps/streets-v4/static/auto/1x1@2x.png?key=YOUR_MAPTILER_API_KEY'

Show Schema

@filename

Using the OpenAPI Specification?

Get the openapi.yaml

Join us online - 19th of November

Static maps API

How to use the API

Getting started

Static maps API reference

MapTiler API

AuthenticationRequired

Static maps

Center-based image

Bounds-based image

Auto-fitted image