Mergin Maps

Appearance

Python API Client ​

Do you want to integrate Mergin Maps? Mergin Maps is an open platform that aims to be developer friendly and it has been designed to allow easy integration with other software.

Installation ​

The Python client module is the easiest way to programmatically use Mergin Maps. You can use Python API or a command-line tool to easily work with your projects, such as to get project status, push and pull changes. You can also create user accounts and manage their roles.

Python client is available in the PyPI repository and can be installed with pip:

pip3 install mergin-client

Command line interface ​

For those who prefer using terminal, there is mergin command line tool shipped with the Python client. With several built-in commands, it is possible to download Mergin Maps projects, push/pull changes, create or delete projects and more.

For example, to download a Mergin Maps project to a local folder:

mergin download john/project1 ~/mergin/project1

For more details, visit MerginMaps/python-api-client.

Python module ​

To use Mergin Maps from Python, just create MerginClient object and then use it. Here, for instance, to download a project:

python
import mergin

client = mergin.MerginClient(login='john', password='T0p_secret')
client.download_project('lutraconsulting/Basic survey', '/tmp/basic-survey')

If you have Mergin Maps QGIS plugin installed and you want to use it from the QGIS' Python console

python
import Mergin.mergin as mergin
client = mergin.MerginClient(login='john', password='T0p_secret')

API reference - users ​

You can create new users and manage their roles using the following methods.

API availability

The following methods are available for Python API Client versions 0.10.0 or higher, using server versions 2025.2.0 or higher.

Create a user ​

python
client.create_user(<email>, <password>, <workspace_id>, <workspace_role>, [username], [notify_user])

The caller must be a workspace admin, owner or server administrator.

Arguments:

email (string): Must be a unique email.

password (string): Must meet security requirements.

workspace_id (int) ℹ️ : The workspace ID where the user will be added.

workspace_role (string) ℹ️ : The user’s role in the workspace. See the roles options.

username (string, optional): If not provided, it will be automatically generated from the email address.

notify_user (Boolean, optional): If true, confirmation email and other email communication will be sent to the email address (invitations, access requests etc.). Default is False.

Example:

python
client.create_user("jill@example.com", "T0p_secret", 1, "editor", notify_user=True)

ℹ️ workspace_id and workspace_role arguments are ignored on Community edition servers.

Workspace members methods ​

These methods are available for Cloud and Enterprise edition servers.

API availability

The following methods are available for Python API Client versions 0.10.0 or higher, using server versions 2025.2.0 or higher.

The caller of the following methods must be a workspace admin, owner or server administrator.

List members ​

python
client.list_workspace_members(<workspace_id>)

Arguments:

workspace_id (int): ID of the workspace.

Get member detail ​

python
client.get_workspace_member(<workspace_id>, <user_id>)

Arguments:

workspace_id (int): ID of the workspace.

user_id (int): ID of the user.

Update member role ​

python
client.update_workspace_member(<workspace_id>, <user_id>, <workspace_role>, [reset_projects_roles])

Arguments:

workspace_id (int): ID of the workspace.

user_id (int): ID of the user.

workspace_role (string): New role. See the roles options.

reset_projects_roles (Boolean, optional): If true, overridden project roles (explicitly shared projects access) will be reset. Default is False.

Remove member ​

python
client.remove_workspace_member(<workspace_id>, <user_id>)

Arguments:

workspace_id (int): ID of the workspace.

user_id (int): ID of the user.

The user account is not removed. This method only removes their access to the workspace.

Project collaborators methods ​

These methods are available for all server types.

API availability

The following methods are available for Python API Client versions 0.10.0 or higher, using server versions 2025.2.0 or higher.

The caller of the following methods must be a workspace admin, owner, project owner or server administrator.

The following methods accept project ids (of type uuid). You can find project id via projects_list and project_info methods.

List project collaborators ​

python
client.list_project_collaborators(<project_id>)

Arguments:

project_id (string): ID of the project.

Add project collaborator ​

Adds a user as project collaborator. This method is good for sharing projects with guests or upgrading roles of members for specific projects. On Cloud, the user must be a in the workspace where the project belongs.

python
client.add_project_collaborator(<project_id>, <user>, <project_role>)

Arguments:

project_id (string): ID of the project.

user (string): Email or username of the user to be added to the project.

project_role: (string): Role of the user in the project. See the roles options

Update project collaborator role ​

python
client.update_project_collaborator(<project_id>, <user_id>, <project_role>)

Arguments:

project_id (string): ID of the project.

user_id (int): ID of the user.

project_role: (string): New role. See the roles options

The user must be first added to the project (via Add project collaborator) before calling this method, even if he/she is already a workspace member or guest.

Remove project collaborator ​

python
client.remove_project_collaborator(<project_id>, <user_id>)

Arguments:

project_id (string): ID of the project.

user_id (int): ID of the user.

The user account is not removed, only the project access.

Further details ​

The MerginMaps/python-api-client repository contains the source code and more information on how to use it.