Scalar API Reference
v4.8.0
OpenAPI 3.0.2

MapTiler Server Admin API

Support
Terms of Service

Reference for MapTiler Server Admin API. 🔑 You are required to authorize every request using your Credentials token in the request header. The token can be acquired in the "Credentials" section of settings. Through the Admin API, you can run maps' and tiles' operations, such as get list, get detail, publish, remove, and more.

Server:http://localhost:3650/api/v1/admin

MapTiler Server Admin API

Client Libraries
Shell Curl

Maps

​
Maps Operations

List maps

​

Lists maps from maps directory. It can be paginated with offset and limit parameters, otherwise first 50 items are returned.

Query Parameters
  • offset
    Type: integer

    The starting position of returned list of items.

  • limit
    Type: integer

    Maximum number of items which will be returned.

Responses
  • application/json
  • application/json
Request Example for get/maps
curl http://localhost:3650/api/v1/admin/maps \
  --header 'Authorization: Basic username:password'

{
  "items": [
    {
      "id": "streets",
      "name": "streets",
      "title": "Streets",
      "published": true,
      "format": "jpeg"
    }
  ]
}

OK

Detail of the map

​

Gets information about the given map.

Path Parameters
  • id
    Type: string
    required

    Identifier of the map.

Responses
  • application/json
  • application/json
  • application/json
Request Example for get/maps/{id}
curl http://localhost:3650/api/v1/admin/maps/streets \
  --header 'Authorization: Basic username:password'

{
  "id": "streets",
  "name": "streets",
  "title": "Streets",
  "published": true,
  "format": "jpeg",
  "quality": 92,
  "urls": {
    "embeddable": "http://localhost:3650/api/maps/streets",
    "ogcTiles": "http://localhost:3650/api/maps/streets/tiles",
    "stylejson": "http://localhost:3650/api/maps/streets/style.json",
    "tilejson": "http://localhost:3650/api/maps/streets/tiles.json",
    "tilejson256": "http://localhost:3650/api/maps/streets/256/tiles.json",
    "wms": "http://localhost:3650/api/maps/streets/wms?service=WMS&request=GetCapabilities",
    "wmts": "http://localhost:3650/api/maps/streets/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/maps/streets/{z}/{x}/{y}.jpg",
    "xyz256": "http://localhost:3650/api/maps/streets/256/{z}/{x}/{y}.jpg"
  }
}

OK

Change metadata of the map

​

Changes metadata (format, quality, published) of the given map.

Path Parameters
  • id
    Type: string
    required

    Identifier of the map.

Body·MapChange
application/json

A JSON object containing metadata information

  • format
    Type: string enum

    New format

    values
    • jpeg
    • png
    • webp
  • published
    Type: boolean

    New state of the map serving

  • quality
    Type: integer
    min:  
    0
    max:  
    100

    New quality in percent

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/maps/{id}
curl http://localhost:3650/api/v1/admin/maps/streets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "format": "jpeg",
  "quality": 92,
  "published": true
}'

{
  "id": "streets",
  "name": "streets",
  "title": "Streets",
  "published": true,
  "format": "jpeg",
  "quality": 92,
  "urls": {
    "embeddable": "http://localhost:3650/api/maps/streets",
    "ogcTiles": "http://localhost:3650/api/maps/streets/tiles",
    "stylejson": "http://localhost:3650/api/maps/streets/style.json",
    "tilejson": "http://localhost:3650/api/maps/streets/tiles.json",
    "tilejson256": "http://localhost:3650/api/maps/streets/256/tiles.json",
    "wms": "http://localhost:3650/api/maps/streets/wms?service=WMS&request=GetCapabilities",
    "wmts": "http://localhost:3650/api/maps/streets/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/maps/streets/{z}/{x}/{y}.jpg",
    "xyz256": "http://localhost:3650/api/maps/streets/256/{z}/{x}/{y}.jpg"
  }
}

OK

Delete the map

​

Deletes the given map. Before deleting, it is automatically unpublished and cannot be served anymore.

Path Parameters
  • id
    Type: string
    required

    Identifier of the map.

Responses
  • application/json
  • application/json
  • application/json
Request Example for delete/maps/{id}
curl http://localhost:3650/api/v1/admin/maps/streets \
  --request DELETE \
  --header 'Authorization: Basic username:password'

{
  "removed": [
    "streets"
  ]
}

OK

Publish the map

​

Publishes the given map. Does nothing, if the map is already published.

Path Parameters
  • id
    Type: string
    required

    Identifier of the map.

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/maps/{id}/publish
curl http://localhost:3650/api/v1/admin/maps/streets/publish \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "id": "streets",
  "name": "streets",
  "title": "Streets",
  "published": true,
  "format": "jpeg",
  "quality": 92,
  "urls": {
    "embeddable": "http://localhost:3650/api/maps/streets",
    "ogcTiles": "http://localhost:3650/api/maps/streets/tiles",
    "stylejson": "http://localhost:3650/api/maps/streets/style.json",
    "tilejson": "http://localhost:3650/api/maps/streets/tiles.json",
    "tilejson256": "http://localhost:3650/api/maps/streets/256/tiles.json",
    "wms": "http://localhost:3650/api/maps/streets/wms?service=WMS&request=GetCapabilities",
    "wmts": "http://localhost:3650/api/maps/streets/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/maps/streets/{z}/{x}/{y}.jpg",
    "xyz256": "http://localhost:3650/api/maps/streets/256/{z}/{x}/{y}.jpg"
  }
}

OK

Unpublish the map

​

Unpublishes the given map. Does nothing, if the map is already unpublished.

Path Parameters
  • id
    Type: string
    required

    Identifier of the map.

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/maps/{id}/unpublish
curl http://localhost:3650/api/v1/admin/maps/streets/unpublish \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "id": "streets",
  "name": "streets",
  "title": "Streets",
  "published": true,
  "format": "jpeg",
  "quality": 92,
  "urls": {
    "embeddable": "http://localhost:3650/api/maps/streets",
    "ogcTiles": "http://localhost:3650/api/maps/streets/tiles",
    "stylejson": "http://localhost:3650/api/maps/streets/style.json",
    "tilejson": "http://localhost:3650/api/maps/streets/tiles.json",
    "tilejson256": "http://localhost:3650/api/maps/streets/256/tiles.json",
    "wms": "http://localhost:3650/api/maps/streets/wms?service=WMS&request=GetCapabilities",
    "wmts": "http://localhost:3650/api/maps/streets/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/maps/streets/{z}/{x}/{y}.jpg",
    "xyz256": "http://localhost:3650/api/maps/streets/256/{z}/{x}/{y}.jpg"
  }
}

OK

Tiles

​
Tiles Operations

List the tiles

​

Lists the tilesets from the tiles directory. Can be paginated with offset and limit parameters, otherwise first 50 items are returned.

Query Parameters
  • offset
    Type: integer

    The starting position of returned list of items.

  • limit
    Type: integer

    Maximum number of items which will be returned.

Responses
  • application/json
Request Example for get/tiles
curl http://localhost:3650/api/v1/admin/tiles \
  --header 'Authorization: Basic username:password'

{
  "items": [
    {
      "id": "b142543e-ffa2-4994-acbc-825012e75a97",
      "name": "maptiler-osm",
      "title": "Maptiler OSM Data",
      "fileName": "maptiler-osm.mbtiles",
      "published": true,
      "type": "mbtiles",
      "tileType": "vector"
    }
  ]
}

OK

Rescan the tiles

​

Rescans tiles directory. Does NOT remove dead files.

Responses
  • application/json
Request Example for post/tiles/rescan
curl http://localhost:3650/api/v1/admin/tiles/rescan \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "items": [
    {
      "id": "b142543e-ffa2-4994-acbc-825012e75a97",
      "name": "maptiler-osm",
      "title": "Maptiler OSM Data",
      "fileName": "maptiler-osm.mbtiles",
      "published": true,
      "type": "mbtiles",
      "tileType": "vector"
    }
  ]
}

OK

Reload the tiles

​

Rescans the tiles directory and automatically removes dead files. Optionally may remove remote tile records.

Query Parameters
  • removeRemote
    Type: boolean

    Removes remote tile records. Does not remove files from the remote server.

Responses
  • application/json
Request Example for post/tiles/reload
curl http://localhost:3650/api/v1/admin/tiles/reload \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "removed": [
    "maptiler-osm"
  ]
}

OK

Add remote tile

​

Adds MTPKG remote tile record.

Body·TileAdd
application/json

A JSON object containing storage and url for remote tile

  • storage
    Type: string enum

    Storage type of remote server

    values
    • http
    • s3
  • url
    Type: string

    URL of remote file

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/add
curl http://localhost:3650/api/v1/admin/tiles/add \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "storage": "http",
  "url": "https://data.maptiler.com/downloads/tileset/europe/switzerland/zurich.mtpkg"
}'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector"
}

OK

Detail of the tileset

​

Gets information about the given tileset.

Path Parameters
  • id
    Type: string
    required

    Identifier of the tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for get/tiles/{id}
curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97 \
  --header 'Authorization: Basic username:password'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Change metadata of the given tileset

​

Changes metadata (name, published) of the given tileset.

Path Parameters
  • id
    Type: string
    required

    Identifier of the tileset

Body·TileChange
application/json

A JSON object containing metadata information

  • name
    Type: string

    New name

  • published
    Type: boolean

    New state of the tile serving

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/{id}
curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "name": "maptiler-osm",
  "published": true
}'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Delete the tileset

​

Deletes the given tileset. Before deleting, it is automatically unpublished and cannot be served anymore.

Path Parameters
  • id
    Type: string
    required

    Identifier of the tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for delete/tiles/{id}
curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97 \
  --request DELETE \
  --header 'Authorization: Basic username:password'

{
  "removed": [
    "maptiler-osm"
  ]
}

OK

Publish the tileset

​

Publishes the given tileset. Does nothing, if the tileset is already published.

Path Parameters
  • id
    Type: string
    required

    Identifier of the tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/{id}/publish
curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97/publish \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Unpublish the tileset

​

Unpublishes the given tileset. Does nothing, if the tileset is already unpublished.

Path Parameters
  • id
    Type: string
    required

    Identifier of the tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/{id}/unpublish
curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97/unpublish \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Tile Ingest

​
Tile Ingest Operations

Create new tileset ingest

​

Creates a new tileset ingest.

Body·TileIngestCreate
application/json

JSON containing file name and file size for new tile ingest

  • filename
    Type: string

    Tileset file name

  • size
    Type: integer

    Size of the uploading file

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/ingest
curl http://localhost:3650/api/v1/admin/tiles/ingest \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "filename": "maptiler-osm.mbtiles",
  "size": 6930432
}'

{
  "id": "b4362feb-6573-451e-b707-cada462c37f7",
  "document_id": "86e2836d-d30e-4767-85f0-12a33bed2393",
  "filename": "maptiler-osm.mbtiles",
  "size": 6930432,
  "state": "upload",
  "upload_url": "http://localhost:3650/api/v1/admin/tiles/ingest/b4362feb-6573-451e-b707-cada462c37f7/upload",
  "errors": [
    {
      "message": "Error message"
    }
  ]
}

OK

Detail of the given tileset ingest

​

Gets information about the given tileset ingest.

Path Parameters
  • id
    Type: string
    required

    Identifier of the ingesting tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for get/tiles/ingest/{id}
curl http://localhost:3650/api/v1/admin/tiles/ingest/b4362feb-6573-451e-b707-cada462c37f7 \
  --header 'Authorization: Basic username:password'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Upload data to tileset ingest

​

Uploads sent data to the given tileset ingest.

Path Parameters
  • id
    Type: string
    required

    Identifier of the ingesting tileset

Body
application/json

A binary file

Responses
  • 200

    OK, file is completely uploaded

  • application/json
  • application/json
Request Example for put/tiles/ingest/{id}/upload
curl http://localhost:3650/api/v1/admin/tiles/ingest/b4362feb-6573-451e-b707-cada462c37f7/upload \
  --request PUT
No Body

OK, file is completely uploaded

Process tileset ingest

​

Processes the data of given tileset ingest and creates a tileset with given document_id

Path Parameters
  • id
    Type: string
    required

    Identifier of the ingesting tileset

Responses
  • application/json
  • application/json
  • application/json
Request Example for post/tiles/ingest/{id}/process
curl http://localhost:3650/api/v1/admin/tiles/ingest/b4362feb-6573-451e-b707-cada462c37f7/process \
  --request POST \
  --header 'Authorization: Basic username:password'

{
  "id": "b142543e-ffa2-4994-acbc-825012e75a97",
  "name": "maptiler-osm",
  "title": "Maptiler OSM Data",
  "fileName": "maptiler-osm.mbtiles",
  "published": true,
  "type": "mbtiles",
  "tileType": "vector",
  "urls": {
    "embeddable": "http://localhost:3650/api/tiles/maptiler-osm",
    "ogcTiles": "http://localhost:3650/api/tiles/maptiler-osm/tiles",
    "tilejson": "http://localhost:3650/api/tiles/maptiler-osm/tiles.json",
    "wmts": "http://localhost:3650/api/tiles/maptiler-osm/WMTSCapabilities.xml",
    "xyz": "http://localhost:3650/api/tiles/maptiler-osm/{z}/{x}/{y}"
  }
}

OK

Was this helpful?
MapTiler Server Admin Reference
MapTiler Server Admin