How to upload MBTiles or GeoPackage into MapTiler Cloud using API

This tutorial shows how to securely upload tiles in GeoPackage or MBTiles to MapTiler Cloud using the command-line utility. All requests are authorized by a token, which is much more secure than an API key.

Using tokens for secure authentication

To successfully upload your resources using the command-line utility, you must acquire your own token for authentication. Navigate to the "Credentials" section of your account administration pages and click on New Credentials if you haven't set any up already.

After creating the credentials, you will be able to copy the token:

The documentation has more information about securely signing requests to the MapTiler Cloud API.

Using the CLI utility

You will need a Python 3 environment on your machine to use this utility. We will start with an empty project, but the steps will be similar if you integrate this utility into an existing project.

We will be using standard Python tools; virtual environment and pip, alternatively you can use a different package manager like Poetry.

1. Creating a virtual environment

Let's make sure you are using the correct version of python by running python -V, the output should indicate Python 3.6 or above, in our case it's Python 3.8.9.

If not, please install a more up-to-date version, follow the instructions on the Python web.

Some distributions split it into a separate distribution package, like python3-venv on Ubuntu/Debian. In these cases, you will have to install the python3-venv package to create the virtual environment.

Now we are going to create our project folder and make a virtual environment inside of it:

mkdir test_cli; cd test_cli
python -m venv test_cli_venv

You should be able to see the newly created folder test_cli_venv inside the project folder.

2. Installing the maptiler-cloud-cli

We are going to source the virtual environment and install maptiler-cloud-cli inside of it.

source test_cli_venv/bin/activate
pip install maptiler-cloud-cli

3. Uploading a new tileset

This code snippet assumes that your desired file is placed in the project directory however, you could use an absolute path to reference files outside the project folder. 

maptiler-cloud --token=MY_TOKEN tiles ingest ISLANDS.mbtiles

The GeoPackage must have a tile matrix set. Read the Vector tiles generating (basic) article to learn how to create a valid GeoPackage or MBTiles from the MapTiler Engine application.

If you reach the tileset limit for your account, you will not be able to upload new tilesets, and you will get an error. Check out our plans to increase the number of tilesets you can have.

4. Update a tileset

You can use the tileset ID to upload a new file to the same tileset.

maptiler-cloud --token=MY_TOKEN tiles ingest --document-id=EXISTING_TILESET_ID ISLANDS_v2.mbtiles

This option replaces the tileset data with the data from the new file. It does NOT add the new data to the existing tileset.

Conclusion

If you want to automate the uploading of your assets to MapTiler Cloud or just don't want to bother with using the browser interface, we have developed a maptiler-cloud-cli utility to serve your needs.

For more control over tileset management, you can use the Admin API. The admin API allows you to create, update or delete a tileset, among other actions.

Useful Links

Admin API documentation
MapTiler Support - Admin API
MapTiler Cloud CLI