Scalar API Reference
v1.0
OpenAPI 3.0.2

MapTiler Service API

Support
Terms of Service

MapTiler Service API gives you full access to your account including write operations. You can use it for example to upload or delete data from your MapTiler account.

🔑 You need to authorize every request to the Service API with a service token. Get your service token in your MapTiler account, page Credentials.

All of the listed endpoints might return these error responses:

Code Description Note
400 Bad Request
401 Not Authorized
403 Forbidden Might be returned if storage limit was exceeded
404 Not Found
410 Gone The requested resource in longer available
Server:https://service.maptiler.com/v1

MapTiler Service API

Client Libraries
Shell Curl

tileset

​
tileset Operations

List tilesets belonging to your account

​
Query Parameters
  • cursor
    Type: string • base64

    Page cursor

  • limit
    Type: integer
    min:  
    10
    max:  
    100

    Page limit

Responses
  • application/json
Request Example for get/tiles
curl https://service.maptiler.com/v1/tiles

{
  "cursor": "aWQ9ImRlNzY0ZjE0LTRhMzktNGRhMS1iM2QxLTlhYmM5NzQyMzEzYSI=",
  "items": [
    {
      "id": "de764f14-4a39-4da1-b3d1-9abc9742313a",
      "title": "North America",
      "description": "Processed on 04.05.2021",
      "attribution": null
    },
    {
      "id": "b9d06d13-23e6-46ef-a54f-9279965d5761",
      "title": "South America",
      "description": "",
      "attribution": null
    }
  ]
}

Page of tilesets

Get tileset details

​
Path Parameters
  • document_id
    Type: string Format: uuid
    required
Responses
  • application/json
Request Example for get/tiles/{document_id}
curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000

{
  "id": "de764f14-4a39-4da1-b3d1-9abc9742313a",
  "title": "North America",
  "description": "Processed on 04.05.2021",
  "attribution": null
}

Tileset

Delete tileset

​
Path Parameters
  • document_id
    Type: string Format: uuid
    required
Responses
  • 200

    Resource marked for deletion.

Request Example for delete/tiles/{document_id}
curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000 \
  --request DELETE
No Body

Resource marked for deletion.

Change tileset metadata

​
Path Parameters
  • document_id
    Type: string Format: uuid
    required
Body·TilesetMetadataChange
application/json
  • attribution
    Type: string
    required
  • description
    Type: string
    required
  • title
    Type: string
    required
Responses
  • application/json
Request Example for post/tiles/{document_id}/change_metadata
curl https://service.maptiler.com/v1/tiles/123e4567-e89b-12d3-a456-426614174000/change_metadata \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "North America",
  "description": "Processed on 04.05.2021",
  "attribution": null
}'

{
  "id": "de764f14-4a39-4da1-b3d1-9abc9742313a",
  "title": "North America",
  "description": "Processed on 04.05.2021",
  "attribution": null
}

Tileset

dataset_ingest

​
dataset_ingest Operations

Ingest dataset container into a new dataset

​
Body·DatasetIngestCreate
application/json
  • filename
    Type: string
    required

    name of the file limited to 255 bytes

  • size
    Type: integer
    required

    size in bytes

  • output
    Type: object | null · DatasetIngestOutput

    Specify output properties

  • supported_upload_types
    Type: array string[] · UploadType[]enum
Responses
  • application/json
Request Example for post/datasets/ingest
curl https://service.maptiler.com/v1/datasets/ingest \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "supported_upload_types": [
    "s3_multipart"
  ],
  "output": {
    "type": "raster_tileset"
  }
}'

{
  "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8",
  "document_id": null,
  "state": "upload",
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "errors": null,
  "progress": 0,
  "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w"
}

Dataset ingest

Ingest dataset container into existing tileset

​
Path Parameters
  • document_id
    Type: string Format: uuid
    required
Body·DatasetIngestCreate
application/json
  • filename
    Type: string
    required

    name of the file limited to 255 bytes

  • size
    Type: integer
    required

    size in bytes

  • output
    Type: object | null · DatasetIngestOutput

    Specify output properties

  • supported_upload_types
    Type: array string[] · UploadType[]enum
Responses
  • application/json
Request Example for post/datasets/{document_id}/ingest
curl https://service.maptiler.com/v1/datasets/123e4567-e89b-12d3-a456-426614174000/ingest \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "supported_upload_types": [
    "s3_multipart"
  ],
  "output": {
    "type": "raster_tileset"
  }
}'

{
  "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8",
  "document_id": null,
  "state": "upload",
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "errors": null,
  "progress": 0,
  "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w"
}

Dataset ingest

Get dataset ingest details

​
Path Parameters
  • ingest_id
    Type: string Format: uuid
    required
Responses
  • application/json
Request Example for get/datasets/ingest/{ingest_id}
curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000

{
  "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8",
  "document_id": null,
  "state": "upload",
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "errors": null,
  "progress": 0,
  "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w"
}

Dataset ingest

Cancel dataset ingest

​
Path Parameters
  • ingest_id
    Type: string Format: uuid
    required
Responses
  • application/json
Request Example for post/datasets/ingest/{ingest_id}/cancel
curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000/cancel \
  --request POST

{
  "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8",
  "document_id": null,
  "state": "upload",
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "errors": null,
  "progress": 0,
  "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w"
}

Dataset ingest

Start dataset ingest processing

​
Path Parameters
  • ingest_id
    Type: string Format: uuid
    required
Body·DatasetIngestProcess
application/json
  • upload_result
    Type: object · UploadResult
    • type
      Discriminator
      Type: string · UploadTypeenum
      values
      • s3_multipart
      • google_drive_resumable
    • parts
      Type: array object[] · S3UploadResultItem[]
Responses
  • application/json
Request Example for post/datasets/ingest/{ingest_id}/process
curl https://service.maptiler.com/v1/datasets/ingest/123e4567-e89b-12d3-a456-426614174000/process \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "upload_result": {
    "type": "s3_multipart",
    "parts": [
      {
        "part_id": 1,
        "etag": "fad1c8150539"
      },
      {
        "part_id": 2,
        "etag": "94a6e2002464"
      }
    ]
  }
}'

{
  "id": "e3a507c3-f9dd-4786-8af3-b21f4ca2d9c8",
  "document_id": null,
  "state": "upload",
  "filename": "north-america.mbtiles",
  "size": 723000000,
  "errors": null,
  "progress": 0,
  "upload_url": "https://www.googleapis.com/upload/drive/v3/files/?uploadType=resumable&supportsTeamDrives=true&upload_id=ABg5-UzOoBea-789qB46gXPK7gGIOoTt5rvcGfzdJSxf_iCJ98ysr0WT9asddb-CpBPWFiR_u0DnCWj3oiD9UErtTdVj3w"
}

Dataset ingest

API keys

​
API keys Operations

List API keys belonging to account

​
Query Parameters
  • cursor
    Type: string • base64

    Page cursor

  • limit
    Type: integer
    min:  
    10
    max:  
    100

    Page limit

Responses
  • application/json
Request Example for get/api_keys
curl https://service.maptiler.com/v1/api_keys

{
  "cursor": null,
  "total_count": 1,
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "token": "string",
      "name": "string",
      "description": null,
      "user_agent": null,
      "origins": [
        "string"
      ],
      "created": "2026-08-24T13:18:41.244Z",
      "changed": "2026-08-24T13:18:41.244Z"
    }
  ]
}

Create new key

​
Body·APIKeySettings
application/json
  • description
    Type: string | null
  • name
    Type: string | null

    Will be generated automatically unless provided explicitly.

  • origins
    Type: array string[]

    Specifies which HTTP origins are allowed to access the API.

    For example [mydomain.com] will ensure, that only requests coming from mydomain.com will be processed. Use *.mydomain.com to allow all subdomains.

    Ensure your application sends the Origin or Referer header; otherwise, requests are treated as unknown and will be rejected if any origin is specified.

    Use ? placeholder to explicitly allow unknown origins.

  • user_agent
    Type: string | null

    Processes only requests where the User-Agent HTTP header contains this exact, case-sensitive substring.

    Wildcards are not supported; only a single string is allowed.

    Useful for increasing security of your key used in custom mobile or desktop applications.

    Leave empty to allow requests from any user-agent.

Responses
  • application/json
Request Example for post/api_keys
curl https://service.maptiler.com/v1/api_keys \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "name": null,
  "description": null,
  "user_agent": null,
  "origins": [
    ""
  ]
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "token": "string",
  "name": "string",
  "description": null,
  "user_agent": null,
  "origins": [
    "string"
  ],
  "created": "2026-08-24T13:18:41.244Z",
  "changed": "2026-08-24T13:18:41.244Z"
}

Get key

​
Path Parameters
  • key_id
Responses
  • application/json
Request Example for get/api_keys/{key_id}
curl 'https://service.maptiler.com/v1/api_keys/{key_id}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "token": "string",
  "name": "string",
  "description": null,
  "user_agent": null,
  "origins": [
    "string"
  ],
  "created": "2026-08-24T13:18:41.244Z",
  "changed": "2026-08-24T13:18:41.244Z"
}

Delete given key

​
Path Parameters
  • key_id
Responses
  • 200

    Successfully deleted

Request Example for delete/api_keys/{key_id}
curl 'https://service.maptiler.com/v1/api_keys/{key_id}' \
  --request DELETE
No Body

Successfully deleted

Update given key

​
Path Parameters
  • key_id
Body·APIKeySettings
application/json
  • description
    Type: string | null
  • name
    Type: string | null

    Will be generated automatically unless provided explicitly.

  • origins
    Type: array string[]

    Specifies which HTTP origins are allowed to access the API.

    For example [mydomain.com] will ensure, that only requests coming from mydomain.com will be processed. Use *.mydomain.com to allow all subdomains.

    Ensure your application sends the Origin or Referer header; otherwise, requests are treated as unknown and will be rejected if any origin is specified.

    Use ? placeholder to explicitly allow unknown origins.

  • user_agent
    Type: string | null

    Processes only requests where the User-Agent HTTP header contains this exact, case-sensitive substring.

    Wildcards are not supported; only a single string is allowed.

    Useful for increasing security of your key used in custom mobile or desktop applications.

    Leave empty to allow requests from any user-agent.

Responses
  • application/json
Request Example for post/api_keys/{key_id}/change_settings
curl 'https://service.maptiler.com/v1/api_keys/{key_id}/change_settings' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "name": null,
  "description": null,
  "user_agent": null,
  "origins": [
    ""
  ]
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "token": "string",
  "name": "string",
  "description": null,
  "user_agent": null,
  "origins": [
    "string"
  ],
  "created": "2026-08-24T13:18:41.244Z",
  "changed": "2026-08-24T13:18:41.244Z"
}

analytics

​
analytics Operations

Get usage analytics timeline

​
Query Parameters
  • period
    Type: string enum
    required
    • billing periods are based on account subscription
    • for classifiers api_keys and service_credentials are supported only daily periods: current_billing_period, last_billing_period, past_30_days, past_90_days
    values
    • current_billing_period
    • last_billing_period
    • past_30_days
    • past_90_days
    • past_12_billing_periods
    • past_12_months
    • all
  • classifier
    Type: string enum
    required

    classifies datasets

    values
    • services
    • api_keys
    • service_credentials
  • group
    Type: string enum

    group ID filter, mandatory for CSV format

    values
    • request
    • session
    • export
  • format
    Type: string enum

    response media type

    values
    • json
    • csv
Responses
  • 400
    • period_not_found: Selected time period does not exist (for example last_billing_period of new account)
    • account_over_limit: Account currently has too many entities (api_keys or service_credentials) to be queried.
    • response_too_large: There were too much data in the result (could be historical).
Request Example for get/analytics/api_usage/timeline
curl 'https://service.maptiler.com/v1/analytics/api_usage/timeline?period=current_billing_period&classifier=services'

{
  "since": "2026-08-24",
  "until": "2026-08-24",
  "datasets": [
    {
      "group_id": "request",
      "item_id": "string",
      "data": [
        {
          "date": "2026-08-24",
          "value": 1
        }
      ],
      "estimated_data": {
        "date": "2026-08-24",
        "value": 1
      }
    }
  ],
  "legend": [
    {
      "item_id": "string",
      "label": "string",
      "description": null
    }
  ]
}

Usage analytics timeline response, further description is within each media type schema.

Get top usage analytics

​
Query Parameters
  • period
    Type: string enum
    required
    • billing periods are based on account subscription
    • for classifiers api_keys and service_credentials are supported only daily periods: current_billing_period, last_billing_period, past_30_days, past_90_days
    values
    • current_billing_period
    • last_billing_period
    • past_30_days
    • past_90_days
    • past_12_billing_periods
    • past_12_months
    • all
  • classifier
    Type: string enum
    required

    classifies datasets

    values
    • services
    • api_keys
    • service_credentials
  • group
    Type: string enum

    group ID filter, mandatory for CSV format

    values
    • request
    • session
    • export
  • format
    Type: string enum

    response media type

    values
    • json
    • csv
  • limit
    Type: integer

    number of top items within response group

Responses
  • 400
    • period_not_found: Selected time period does not exist (for example last_billing_period of new account)
Request Example for get/analytics/api_usage/top
curl 'https://service.maptiler.com/v1/analytics/api_usage/top?period=current_billing_period&classifier=services'

{
  "since": "2026-08-24",
  "until": "2026-08-24",
  "datasets": [
    {
      "group_id": "request",
      "data": [
        {
          "item_id": "string",
          "value": 1
        }
      ]
    }
  ],
  "legend": [
    {
      "item_id": "string",
      "label": "string",
      "description": null
    }
  ]
}

Usage analytics top response, further description is within each media type schema.

Was this helpful?
MapTiler Service API Reference
MapTiler Service API