Scalar API Reference

v4.8.0

OpenAPI 3.0.2

MapTiler Server Admin API

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

Client Libraries

Shell Curl

Maps

Maps Operations

get/maps
get/maps/{id}
post/maps/{id}
delete/maps/{id}
post/maps/{id}/publish
post/maps/{id}/unpublish

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

get/maps

curl http://localhost:3650/api/v1/admin/maps \
  --header 'Authorization: Basic username:password'

Show Schema

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

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

get/maps/{id}

curl http://localhost:3650/api/v1/admin/maps/streets \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "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"
  }
}

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

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
}'

Show Schema

{
  "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"
  }
}

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

delete/maps/{id}

curl http://localhost:3650/api/v1/admin/maps/streets \
  --request DELETE \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "removed": [
    "streets"
  ]
}

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

post/maps/{id}/publish

curl http://localhost:3650/api/v1/admin/maps/streets/publish \
  --request POST \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "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"
  }
}

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

post/maps/{id}/unpublish

curl http://localhost:3650/api/v1/admin/maps/streets/unpublish \
  --request POST \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "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"
  }
}

Tiles

Tiles Operations

get/tiles
post/tiles/rescan
post/tiles/reload
post/tiles/add
get/tiles/{id}
post/tiles/{id}
delete/tiles/{id}
post/tiles/{id}/publish
post/tiles/{id}/unpublish

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

get/tiles

curl http://localhost:3650/api/v1/admin/tiles \
  --header 'Authorization: Basic username:password'

Show Schema

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

Rescan the tiles

Rescans tiles directory. Does NOT remove dead files.

Responses

application/json

post/tiles/rescan

curl http://localhost:3650/api/v1/admin/tiles/rescan \
  --request POST \
  --header 'Authorization: Basic username:password'

Show Schema

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

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

post/tiles/reload

curl http://localhost:3650/api/v1/admin/tiles/reload \
  --request POST \
  --header 'Authorization: Basic username:password'

Show Schema

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

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

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"
}'

Show Schema

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

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

get/tiles/{id}

curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97 \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "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}"
  }
}

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

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
}'

Show Schema

{
  "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}"
  }
}

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

delete/tiles/{id}

curl http://localhost:3650/api/v1/admin/tiles/b142543e-ffa2-4994-acbc-825012e75a97 \
  --request DELETE \
  --header 'Authorization: Basic username:password'

Show Schema

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

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

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'

Show Schema

{
  "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}"
  }
}

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

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'

Show Schema

{
  "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}"
  }
}

Tile Ingest

Tile Ingest Operations

post/tiles/ingest
get/tiles/ingest/{id}
put/tiles/ingest/{id}/upload
post/tiles/ingest/{id}/process

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

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
}'

Show Schema

{
  "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"
    }
  ]
}

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

get/tiles/ingest/{id}

curl http://localhost:3650/api/v1/admin/tiles/ingest/b4362feb-6573-451e-b707-cada462c37f7 \
  --header 'Authorization: Basic username:password'

Show Schema

{
  "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}"
  }
}

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

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

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'

Show Schema

{
  "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}"
  }
}