On this page

    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.

    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

    Key

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

    Getting started

    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-v4
    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 Static map with lines or polygons.
    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 Static map with markers.
    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-v4/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-v4
    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 Static map with lines or polygons.
    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 Static map with markers.
    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-v4/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-v4
    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 Static map with lines or polygons.
    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 Static map with markers.
    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-v4/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

    Was this helpful?

    MapTiler API
    Static maps API
    Static maps API