Join us online - 19th of November
Save your spot

Upload API

MapTiler’s Upload API adds new datasets or updates existing ones in your MapTiler account. You can call it directly, but we recommend using one of these tools instead. They handle the upload process for you:

  • CLI – works with any tech stack. It reads your service token from the --token option or the MAPTILER_TOKEN environment variable, so you don’t need to write any backend code.
  • Upload JS – a JavaScript and TypeScript library with extra features. It needs a backend of your own to keep the service token private.

See the complete guide: How to upload your data using API & CLI.

Upload API reference

Configure your environment settings below to update code samples:

  • Client Libraries – select your preferred programming language of the code examples.
Scalar API Reference
v1.0
OpenAPI 3.0.2

MapTiler Service API

Support
Terms of Service
Server:https://service.maptiler.com/v1

MapTiler Service API

Client Libraries
Shell Curl

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' \
  --header 'Authorization: Basic username:password' \
  --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' \
  --header 'Authorization: Basic username:password' \
  --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 \
  --header 'Authorization: Basic username:password'

{
  "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 \
  --header 'Authorization: Basic username:password'

{
  "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' \
  --header 'Authorization: Basic username:password' \
  --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

Was this helpful?