Scalar API Reference
v1.0
OpenAPI 3.1.0

MapTiler API

Support
Terms of Service

MapTiler API allows you to programmatically access all the data, maps, services, and resources available in your MapTiler account.

Access to your resources via MapTiler API is read-only, and therefore safe and well suited for public end-user applications. You can use it to add a map directly to your website, request map tiles, create an image with a location map for your business, search for addresses, and more.

The universal public API request format is:

https://api.maptiler.com/{METHOD}/{QUERY}.json?{PARAMS}&key=YOUR_MAPTILER_API_KEY_HERE

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

Server:https://api.maptiler.com

MapTiler API

Client Libraries
Shell Curl

Maps

​
Maps Operations

Embeddable HTML viewer

​
Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

Responses
  • text/html
Request Example for get/maps/{mapId}/
curl 'https://api.maptiler.com/maps/streets-v4/?key=YOUR_SECRET_TOKEN'
No Body

Style JSON of the map

​

Style JSON describing the map cartography. Can be used with various libraries to display a vector map (e.g. Mapbox GL JS, OpenLayers, ...).

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

Responses
  • application/json
Request Example for get/maps/{mapId}/style.json
curl 'https://api.maptiler.com/maps/streets-v4/style.json?key=YOUR_SECRET_TOKEN'

{}
deprecated

Map symbols (sprites)

​

Map symbols (sprites) required to display the vector map.
Deprecated: use Sprites API.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

  • scale
    enum
    const:  
    @2x
    values
    • @2x
  • format
    Type: string enum
    required
    values
    • png
    • json
Responses
Request Example for get/maps/{mapId}/sprite{scale}.{format}
curl https://api.maptiler.com/maps/streets-v4/sprite@2x.png
No Body

Raster XYZ tiles

​

Rasterized tiles (XYZ) of the map. Can be used with various libraries to display a raster map (e.g. Leaflet, OpenLayers, ...). It's usually better (if possible) to use the TileJSON rather than using the tile URL directly.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

  • tileSize/
    enum
    const:  
    256

    Integer numbers.

    values
    • 256
  • z
    Type: integer
    required

    Zoom level. Specifies the tile's zoom level. See Tiles à la Google Maps

  • x
    Type: integer
    required

    Column. Specifies the tile's column. See Tiles à la Google Maps

  • y
    Type: integer
    required

    Row. Specifies the tile's row. See Tiles à la Google Maps

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required
    values
    • png
    • jpg
    • webp
    • basis
Responses
  • image/*
  • 400

    Out of bounds / Invalid format

Request Example for get/maps/{mapId}/{tileSize/}/{z}/{x}/{y}{scale}.{format}
curl 'https://api.maptiler.com/maps/streets-v4/256/1/1/1@2x.png?key=YOUR_SECRET_TOKEN'

@filename

TileJSON

​

TileJSON describing the metadata of the map as well as link to the XYZ tiles. Can be used with various libraries to display a raster map (e.g. Leaflet, OpenLayers, ...).

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

  • tileSize/
    enum
    const:  
    256

    Integer numbers.

    values
    • 256
Responses
  • application/json
Request Example for get/maps/{mapId}/{tileSize/}/tiles.json
curl 'https://api.maptiler.com/maps/streets-v4/256/tiles.json?key=YOUR_SECRET_TOKEN'

{}

OGC API - Tiles

​

Tileset landing page of the rasterized tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

Responses
  • application/json
Request Example for get/maps/{mapId}/tiles
curl 'https://api.maptiler.com/maps/streets-v4/tiles?key=YOUR_SECRET_TOKEN'

string

OGC API TileMatrixSets

​

Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

Responses
  • application/json
Request Example for get/maps/{mapId}/tileMatrixSet
curl 'https://api.maptiler.com/maps/streets-v4/tileMatrixSet?key=YOUR_SECRET_TOKEN'

string

WMTS Capabilities

​

WMTS Capabilities XML document describing the metadata of the map as well as link to the XYZ tiles. Can be used with various GIS software (e.g. QGIS) to display the map.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Maps.

Responses
  • text/xml
Request Example for get/maps/{mapId}/WMTSCapabilities.xml
curl 'https://api.maptiler.com/maps/streets-v4/WMTSCapabilities.xml?key=YOUR_SECRET_TOKEN'

string

Static maps

​
Static maps Operations

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.

Request Example for 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_SECRET_TOKEN'

@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.

Request Example for 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_SECRET_TOKEN'

@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.

Request Example for 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_SECRET_TOKEN'

@filename

Tiles

​
Tiles Operations

Embeddable HTML viewer

​
Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

Responses
  • text/html
Request Example for get/tiles/{tilesId}/
curl 'https://api.maptiler.com/tiles/satellite-v4/?key=YOUR_SECRET_TOKEN'
No Body

XYZ tiles

​

The individual tiles. Can be used with various libraries to display the tiles (e.g. Leaflet, OpenLayers, ...). It's usually better (if possible) to use the TileJSON rather than using the tile URL directly.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

  • z
    Type: integer
    required

    Zoom level. Specifies the tile's zoom level. See Tiles à la Google Maps

  • x
    Type: integer
    required

    Column. Specifies the tile's column. See Tiles à la Google Maps

  • y
    Type: integer
    required

    Row. Specifies the tile's row. See Tiles à la Google Maps

Responses
  • *
  • 204

    Tile not present -- presumed empty (empty response)

  • 400

    Out of bounds

  • 403

    Key is missing, invalid or restricted

  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/{z}/{x}/{y}
curl 'https://api.maptiler.com/tiles/satellite-v4/1/1/1?key=YOUR_SECRET_TOKEN'
No Body

TileJSON

​

TileJSON describing the metadata of the tiles as well as link to the XYZ tiles. Can be used with various libraries to display the tiles (e.g. Leaflet, OpenLayers, ...).

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

Responses
  • application/json
Request Example for get/tiles/{tilesId}/tiles.json
curl 'https://api.maptiler.com/tiles/satellite-v4/tiles.json?key=YOUR_SECRET_TOKEN'

{}

OGC API - Tiles

​

Tileset landing page of the tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

Responses
  • application/json
Request Example for get/tiles/{tilesId}/tiles
curl 'https://api.maptiler.com/tiles/satellite-v4/tiles?key=YOUR_SECRET_TOKEN'

string

OGC API TileMatrixSets

​

Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

Responses
  • application/json
Request Example for get/tiles/{tilesId}/tileMatrixSet
curl 'https://api.maptiler.com/tiles/satellite-v4/tileMatrixSet?key=YOUR_SECRET_TOKEN'

string

WMTS Capabilities

​

WMTS Capabilities XML document describing the metadata of the tiles as well as link to the XYZ tiles. Can be used with various GIS software (e.g. QGIS) to display the tiles.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Tiles.

Responses
  • text/xml
Request Example for get/tiles/{tilesId}/WMTSCapabilities.xml
curl 'https://api.maptiler.com/tiles/satellite-v4/WMTSCapabilities.xml?key=YOUR_SECRET_TOKEN'

string

Data

​
Data Operations

GeoJSON

​

GeoJSON containing the vector features.

Path Parameters
  • dataId
    Type: string
    required

    Identifier of the data. See MapTiler Datasets.

Responses
  • application/json
Request Example for get/data/{dataId}/features.json
curl 'https://api.maptiler.com/data/{dataId}/features.json?key=YOUR_SECRET_TOKEN'

{}

Images

​
Images Operations

ImageJSON

​

JSON describing the metadata of the image. Can be used with MapTiler SDK to display the image.

Path Parameters
  • imageId
    Type: string
    required

    Identifier of the image.

Responses
  • application/json
Request Example for get/images/{imageId}/image.json
curl 'https://api.maptiler.com/images/{imageId}/image.json?key=YOUR_SECRET_TOKEN'

{
  "id": "string",
  "description": "string",
  "attribution": "string",
  "width": 1,
  "height": 1,
  "minzoom": 1,
  "maxzoom": 1,
  "tileSize": 1
}

XYZ tiles

​

The individual tiles. Can be used with various libraries to display the image. It's better to use the ImageJSON with MapTiler SDK rather than using the tile URL directly.

Path Parameters
  • imageId
    Type: string
    required

    Identifier of the image.

  • z
    Type: integer
    required

    Zoom level. Specifies the tile's zoom level. See Tiles à la Google Maps

  • x
    Type: integer
    required

    Column. Specifies the tile's column. See Tiles à la Google Maps

  • y
    Type: integer
    required

    Row. Specifies the tile's row. See Tiles à la Google Maps

Responses
  • *
  • 204

    Tile not present -- presumed empty (empty response)

  • 400

    Out of bounds

  • 403

    Key is missing, invalid or restricted

  • 404

    The item does not exist

Request Example for get/images/{imageId}/{z}/{x}/{y}
curl 'https://api.maptiler.com/images/{imageId}/1/1/1?key=YOUR_SECRET_TOKEN'
No Body

Geocoding

​
Geocoding Operations

Search by name (forward)

​

Forward geocoding (search by place name).

Path Parameters
  • query
    Type: string
    required

    Place name to search. You can also use bare POI category or mix it with a name to search for POIs of desired category, unless poi index is excluded.

Query Parameters
  • bbox
    Type: array · bbox

    A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.

  • proximity

    A [lon, lat] array to use for biasing search results or the string ip to do server-side IP based geolocation. Specify to prefer results close to a specific location - features closer to the proximity value will be given priority over those further from the proximity value.

    • Type: array · Coordinates
  • language
    Type: array string[] …20 unique!enum

    Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • country
    Type: array string[] unique!

    Limit search to specific country/countries.

  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

  • types
    Type: array string[] · PlaceType[] unique!enum

    Filter types of which features to return. If not specified, default configuration of API is used (see PlaceTypeValues for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single type can be returned, otherwise single feature for every specified type (or default types) can be returned.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • fuzzyMatch
    Type: boolean

    Set to false to disable fuzzy search.

  • autocomplete
    Type: boolean

    Set to true to use autocomplete, false to disable autocomplete.

  • worldview
    Type: string enum

    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

  • 403

    Key is missing, invalid or restricted

Request Example for get/geocoding/{query}.json
curl 'https://api.maptiler.com/geocoding/Zurich.json?key=YOUR_SECRET_TOKEN'

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

Search by coordinates (reverse)

​

Reverse geocoding (search by coordinates).

Path Parameters
  • longitude
    Type: number
    min:  
    -180
    max:  
    180
    required
  • latitude
    Type: number
    min:  
    -90
    max:  
    90
    required
Query Parameters
  • language
    Type: array string[] …20 unique!enum

    Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

  • types
    Type: array string[] · PlaceType[] unique!enum

    Filter types of which features to return. If not specified, default configuration of API is used (see PlaceTypeValues for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single type can be returned, otherwise single feature for every specified type (or default types) can be returned.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • worldview
    Type: string enum

    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

  • 403

    Key is missing, invalid or restricted

Request Example for get/geocoding/{longitude},{latitude}.json
curl 'https://api.maptiler.com/geocoding/8.528509,47.3774434.json?key=YOUR_SECRET_TOKEN'

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

Search by feature ID

​

Search feature by its ID (id) as returned in forward or reverse geocoding response and return its full geometry. Note that the feature ID is not stable and it changes when the database is re-indexed.

Path Parameters
  • id
    Type: string
    required

    Feature ID (found in response of forward or reverse geocoding)

Query Parameters
  • language
    Type: array string[] …20 unique!enum

    Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • worldview
    Type: string enum

    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

  • 403

    Key is missing, invalid or restricted

Request Example for get/geocoding/{id}.json
curl 'https://api.maptiler.com/geocoding/country.26561650.json?key=YOUR_SECRET_TOKEN'

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

Batch geocoding API

​

Perform geocoding of more than one request in a single API call. Check out the Batch Geocoding guide for an example.

Path Parameters
  • queries
    Type: string
    required

    Semicolon-separated list of queries. Semicolon ; must be provided verbatim and not be URL-encoded. Each query may be forward, reverse or by feature ID. Maximum of 50 queries are supported.

Query Parameters
  • bbox
    Type: array · bbox

    A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.

  • proximity

    A [lon, lat] array to use for biasing search results or the string ip to do server-side IP based geolocation. Specify to prefer results close to a specific location - features closer to the proximity value will be given priority over those further from the proximity value.

    • Type: array · Coordinates
  • language
    Type: array string[] …20 unique!enum

    Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • country
    Type: array string[] unique!

    Limit search to specific country/countries.

  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

  • types
    Type: array string[] · PlaceType[] unique!enum

    Filter types of which features to return. If not specified, default configuration of API is used (see PlaceTypeValues for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single type can be returned, otherwise single feature for every specified type (or default types) can be returned.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • fuzzyMatch
    Type: boolean

    Set to false to disable fuzzy search.

  • autocomplete
    Type: boolean

    Set to true to use autocomplete, false to disable autocomplete.

  • worldview
    Type: string enum

    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (e.g., US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

  • 403

    Key is missing, invalid or restricted

Request Example for get/geocoding/{queries}.json
curl 'https://api.maptiler.com/geocoding/Paris;Berlin.json?key=YOUR_SECRET_TOKEN'

[
  {
    "type": "FeatureCollection",
    "features": [
      {
        "id": "municipality.46425",
        "text": "Paris",
        "language": "en",
        "^text_(\\w\\w)": "string",
        "^language_(\\w\\w)": "string",
        "additionalProperty": "anything",
        "type": "Feature",
        "properties": {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            8.528509,
            47.3774434
          ]
        },
        "bbox": [
          5.9559,
          45.818,
          10.4921,
          47.8084
        ],
        "center": [
          8.528509,
          47.3774434
        ],
        "place_name": "string",
        "matching_place_name": "string",
        "matching_text": "string",
        "place_type": [
          "continental_marine"
        ],
        "place_type_name": [
          "string"
        ],
        "relevance": 1,
        "context": [
          {
            "ref": "osm:r71525",
            "country_code": "fr",
            "kind": "road",
            "categories": [
              "restaurant"
            ],
            "feature_tags": {
              "additionalProperty": "string"
            },
            "place_designation": "city",
            "additionalProperty": "anything",
            "id": "municipality.46425",
            "text": "Paris",
            "language": "en",
            "^text_(\\w\\w)": "string",
            "^language_(\\w\\w)": "string"
          }
        ],
        "address": "string",
        "^place_name_(\\w\\w)": "string"
      }
    ],
    "query": [
      "string"
    ],
    "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
  }
]

Array of geocoding results where items are matching order of queries in the request. Every result is represented as FeatureCollection where every item is represented as a GeoJSON Feature

Geolocation

​
Geolocation Operations

IP Geolocation

​

Obtain information about visitor's location based on IP address of the incoming request.

Query Parameters
  • elevation
    Type: boolean

    Include elevation (in meters) in the results.

Responses
  • application/json
  • 403

    Key is missing, invalid or restricted

Request Example for get/geolocation/ip.json
curl 'https://api.maptiler.com/geolocation/ip.json?key=YOUR_SECRET_TOKEN'

{
  "country": "Switzerland",
  "country_code": "CH",
  "country_bounds": [
    5.95538,
    45.818852,
    10.490936,
    47.809357
  ],
  "country_languages": [
    "de",
    "fr",
    "it"
  ],
  "continent": "Europe",
  "continent_code": "EU",
  "eu": false,
  "city": "Zurich",
  "latitude": 47.36667,
  "longitude": 8.55,
  "postal": "8000",
  "region": "Zurich",
  "region_code": "ZH",
  "timezone": "Europe/Zurich",
  "elevation": 433
}

Coordinates

​
Coordinates Operations

Search coordinate systems

​
Path Parameters
  • query
    Type: string
    required

    Query string used to search the catalog. It accepts plain terms such as names of locations and key:value pairs for filtering.

    Following parameter values can be used:

    • kind
      • * (All kinds)
      • CRS (All coordinate reference systems - default)
        • CRS-PROJCRS (Projected coordinate systems)
        • CRS-GEOGCRS (Geodetic coordinate systems)
        • CRS-GEOG3DCRS (Geodetic 3D coordinate systems)
        • CRS-GCENCRS (Geocentric coordinate systems)
        • CRS-VERTCRS (Vertical coordinate systems)
        • CRS-ENGCRS (Engineering coordinate systems)
        • CRS-COMPOUNDCRS (Compound coordinate systems)
        • CRS-DRVDCRS (Derived coordinate systems)
      • COORDOP (All operations)
        • COORDOP-COPTRAN (Transformations)
        • COORDOP-COPCONO (Compound operations)
        • COORDOP-POIMOTO (Point motion operations)
        • COORDOP-COPCON (Conversions)
      • DATUM (All datums)
        • DATUM-VERTDAT (Vertical datums)
        • DATUM-ENGDAT (Engineering datums)
        • DATUM-GEODDAT (Geodetic datums)
        • DATUM-DYNGEODDA (Dynamic geodetic datums)
        • DATUM-ENSEMDAT (Ensemble datum)
      • ELLIPSOID (Ellipsoid)
      • PRIMEM (Prime meridian)
      • METHOD (Method / Projection)
      • CS (Coordinate systems)
        • CS-VERTCS (Vertical coordinate system)
        • CS-SPHERCS (Spherical coordinate system)
        • CS-CARTESCS (Cartesian coordinate system)
        • CS-ELLIPCS (Ellipsoidal coordinate system)
        • CS-AFFINE (Affine coordinate system)
        • CS-ORDINAL (Ordinal coordinate system)
      • AXIS (Axis)
      • AREA (Area)
      • UNIT (Unit)
        • UNIT-ANGUNIT (Angle unit)
        • UNIT-SCALEUNIT (Scale unit)
        • UNIT-LENUNIT (Length unit)
        • UNIT-TIMEUNIT (Time unit)
    • code
      • Full code of the resource
    • trans
      • Code of the transformation
    • deprecated
      • * (Both active and deprecated)
      • 0 (active only - default)
      • 1 (deprecated only)
Query Parameters
  • limit
    Type: integer
    min:  
    1
    max:  
    50

    Maximum number of results returned

  • offset
    Type: integer
    min:  
    0

    The starting position of returned list of results

  • transformations
    Type: boolean

    Show detailed transformations for each CRS

  • exports
    Type: boolean

    Show exports in WKT and Proj4 notations

Responses
  • application/json
Request Example for get/coordinates/search/{query}.json
curl 'https://api.maptiler.com/coordinates/search/finland deprecated:* kind:*.json?key=YOUR_SECRET_TOKEN'

{
  "results": [
    {
      "accuracy": 1,
      "area": "string",
      "bbox": [
        1
      ],
      "default_transformation": {
        "authority": "string",
        "code": 1
      },
      "deprecated": true,
      "exports": {
        "proj4": "string",
        "wkt": "string"
      },
      "id": {
        "authority": "string",
        "code": 1
      },
      "kind": "string",
      "name": "string",
      "transformations": [
        {
          "accuracy": 1,
          "area": "string",
          "bbox": [
            1
          ],
          "deprecated": true,
          "exports": {
            "proj4": "string",
            "wkt": "string"
          },
          "grids": [
            {
              "path": "string"
            }
          ],
          "id": {
            "authority": "string",
            "code": 1
          },
          "name": "string",
          "reversible": true,
          "target_crs": {
            "authority": "string",
            "code": 1
          },
          "unit": "string",
          "usable": true
        }
      ],
      "unit": "string"
    }
  ],
  "total": 1
}

Transform coordinates

​
Path Parameters
  • coordinates
    Type: string
    required

    List of coordinate pairs seperated by ; delimeter (Max 50 pairs).

Query Parameters
  • s_srs
    Type: integer

    Source CRS

  • t_srs
    Type: integer

    Target CRS

  • ops
    Type: string

    List of codes of operations seperated by a | (pipe) operator

Responses
  • application/json
Request Example for get/coordinates/transform/{coordinates}.json
curl 'https://api.maptiler.com/coordinates/transform/17,50;17,50,300.json?key=YOUR_SECRET_TOKEN'

{
  "results": [
    {
      "x": 1,
      "y": 1,
      "z": 1
    }
  ],
  "transformer_selection_strategy": "string"
}

Elevation

​
Elevation Operations

Get elevation

​

Get the elevation at given locations. If unit is omitted, elevation values are in meters.

Path Parameters
  • locations
    Type: string
    required

    List of lng,lat WGS 84 positions seperated by ; delimeter (Max 50 positions). Longitude values must be > -180 < 180. Latitudes must be >= -85 <= 85.

Query Parameters
  • unit
    Type: string enum

    Unit of the elevation.

    values
    • meters
    • feet
Responses
  • application/json
  • 400

    Out of bounds

Request Example for get/elevation/{locations}.json
curl 'https://api.maptiler.com/elevation/17,50;-133.5,58.39.json?key=YOUR_SECRET_TOKEN'

[
  [
    17,
    50,
    364.20001220703125
  ],
  [
    -133.5,
    58.39,
    1323.800048828125
  ]
]

Weather

​
Weather Operations

Weather catalog

​

List current weather-related variables, their metadata and individual keyframes

Responses
  • application/json
  • 403

    Key is missing, invalid or restricted

Request Example for get/weather/latest.json
curl 'https://api.maptiler.com/weather/latest.json?key=YOUR_SECRET_TOKEN'

{
  "variables": [
    {
      "spatial_ref_sys": {
        "auth_name": "EPSG",
        "auth_srid": "3857",
        "wkt": "PROJCRS[\"WGS 84 / Pseudo-Mercator\",BASEGEOGCRS[\"WGS 84\",ENSEMBLE[\"World Geodetic System 1984 ensemble\",MEMBER[\"World Geodetic System 1984 (Transit)\"],MEMBER[\"World Geodetic System 1984 (G730)\"],MEMBER[\"World Geodetic System 1984 (G873)\"],MEMBER[\"World Geodetic System 1984 (G1150)\"],MEMBER[\"World Geodetic System 1984 (G1674)\"],MEMBER[\"World Geodetic System 1984 (G1762)\"],MEMBER[\"World Geodetic System 1984 (G2139)\"],ELLIPSOID[\"WGS 84\",6378137,298.257223563,LENGTHUNIT[\"metre\",1]],ENSEMBLEACCURACY[2.0]],PRIMEM[\"Greenwich\",0,ANGLEUNIT[\"degree\",0.0174532925199433]],ID[\"EPSG\",4326]],CONVERSION[\"Popular Visualisation Pseudo-Mercator\",METHOD[\"Popular Visualisation Pseudo Mercator\",ID[\"EPSG\",1024]],PARAMETER[\"Latitude of natural origin\",0,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8801]],PARAMETER[\"Longitude of natural origin\",0,ANGLEUNIT[\"degree\",0.0174532925199433],ID[\"EPSG\",8802]],PARAMETER[\"False easting\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8806]],PARAMETER[\"False northing\",0,LENGTHUNIT[\"metre\",1],ID[\"EPSG\",8807]]],CS[Cartesian,2],AXIS[\"easting (X)\",east,ORDER[1],LENGTHUNIT[\"metre\",1]],AXIS[\"northing (Y)\",north,ORDER[2],LENGTHUNIT[\"metre\",1]],USAGE[SCOPE[\"Web mapping and visualisation.\"],AREA[\"World between 85.06°S and 85.06°N.\"],BBOX[-85.06,-180,85.06,180]],ID[\"EPSG\",3857]]"
      },
      "bounds": [
        -20037481.18083349,
        -20037508.342789244,
        20008180.55502281,
        20037508.342789244
      ],
      "tile_format": "png",
      "tile_matrix_set": {
        "bounds": [
          -20037481.18083349,
          -20037508.342789244,
          20008180.55502281,
          20037508.342789244
        ],
        "items": [
          {
            "zoom_level": 1,
            "matrix_width": 1,
            "matrix_height": 1,
            "tile_width": 1,
            "tile_height": 1,
            "pixel_x_size": 1,
            "pixel_y_size": 1
          }
        ]
      },
      "metadata": {
        "weather_variable": {
          "name": "Wind",
          "description": "Wind at 10 m above ground [m/s]",
          "attribution": "GFS",
          "variable_id": "wind-10m:gfs",
          "decoding": {
            "channels": "rg",
            "min": -75,
            "max": 75
          },
          "unit": "ms",
          "release_timestamp": "2023-03-01T06:00:00+00:00",
          "timestamp": "2023-03-01T11:00:00+00:00"
        }
      },
      "keyframes": [
        {
          "id": "string",
          "timestamp": "string"
        }
      ]
    }
  ]
}

Other

​
Other Operations

Sprites (icon sets)

​

Map icons (sprites) used to display the vector map.

Path Parameters
  • spriteId
    Type: string
    required

    Identifier of the sprite.

  • scale
    enum
    const:  
    @2x
    values
    • @2x
  • format
    Type: string enum
    required
    values
    • png
    • json
Responses
Request Example for get/sprites/{spriteId}/sprite{scale}.{format}
curl 'https://api.maptiler.com/sprites/{spriteId}/sprite@2x.png'
No Body

Fonts (glyphs)

​

Generates the glyphs for the requested fonts. Used when displaying vector maps.

Path Parameters
  • fontstack
    Type: string
    required

    Font name, or more comma-separated names.

  • start
    Type: integer
    multiple of:  
    256
    required

    Start of the glyph range.

  • end
    Type: integer
    required

    End of the glyph range (last glyph index).

Responses
  • application/x-protobuf
  • 400

    Invalid glyph range

Request Example for get/fonts/{fontstack}/{start}-{end}.pbf
curl 'https://api.maptiler.com/fonts/Roboto Medium,Noto Sans Regular/1-255.pbf?key=YOUR_SECRET_TOKEN'
No Body

OGC API conformance classes

​

Declaration of the implemented conformance classes.

Responses
  • application/json
Request Example for get/ogc/conformance
curl 'https://api.maptiler.com/ogc/conformance?key=YOUR_SECRET_TOKEN'

string
Was this helpful?
MapTiler API Reference
MapTiler API