Sign in
Back to documentation

MapHub API

Table of Contents

Introduction

The MapHub API allows you to programmatically interact with your maps and data. With the API, you can:

  • Upload and download maps
  • Manage folders and workspaces
  • Query map metadata and statistics
  • Access tiled map data
  • Automate workflows

Key Benefits: The MapHub API enables seamless integration with your existing tools and workflows, allowing you to automate processes and build custom applications on top of MapHub's infrastructure.

Whether you're building a custom application, integrating MapHub into your existing tools, or automating repetitive tasks, the API provides a powerful interface to MapHub's functionality.

API Documentation

The MapHub API is fully documented using OpenAPI (Swagger) specification. You can explore the interactive API documentation at:

The documentation provides detailed information about each endpoint, including:

  • Required parameters
  • Request and response formats
  • Authentication requirements
  • Example requests and responses

Python API Wrapper

For Python developers, we offer a Python API wrapper that simplifies interaction with the MapHub API.

Important: The Python API wrapper is currently in an early state of development and only supports a limited number of endpoints. We're actively working on expanding its capabilities.

To install the python library simply run: pip install maphub

# Example of using the Python API wrapper
from maphub import MapHubClient

# Create the authorized client
client = MapHubClient(api_key="your-api-key")

# Create an example project
example_project = client.create_project("Example Project")

# Upload some GIS data to MapHub
client.upload_map(
    map_name="Example Map",
    project_id=example_project['id'],
    public=False,
    path="path/to/GIS/data.gpkg"
)

We're actively working on expanding the wrapper's capabilities. Check our GitHub repository for the latest updates and documentation.

Command Line Interface (CLI)

The MapHub CLI provides a command-line interface for interacting with the MapHub API. It allows you to authenticate with an API key and upload maps to your folders.

Installation: The CLI is included in the Python package. Install it with: pip install maphub

Authentication

Before using the CLI, you need to authenticate with your MapHub API key:

maphub auth YOUR_API_KEY

This will save your API key to ~/.maphub/config.json for future use.

Uploading Maps

To upload a GIS file to your root folder:

maphub upload path/to/your/file.gpkg

To upload a GIS file to a specific folder:

maphub upload path/to/your/file.gpkg --folder-id YOUR_FOLDER_ID

If you don't specify a folder ID, the map will be uploaded to your root folder.

To upload a GIS file with a custom map name:

maphub upload path/to/your/file.gpkg --map-name "My Custom Map Name"

If you don't specify a map name, it will be extracted from the file name (without extension).

Authentication

The MapHub API uses an API Key as authentication method.

You can generate and manage API keys in your account section.

Common Use Cases

Here are some common use cases for the MapHub API:

Automated Map Processing

Set up automated workflows to process and update maps on a schedule:

  1. Download the latest data from your source
  2. Process and transform the data
  3. Upload the updated map to MapHub

Custom Applications

Build custom applications that leverage MapHub's infrastructure:

  1. Use the API to manage maps and folders
  2. Embed maps in your application using our embedding features
  3. Implement custom visualization and analysis tools

Data Integration

Integrate MapHub with your existing data systems:

  1. Sync data between your database and MapHub
  2. Trigger map updates when your data changes
  3. Pull map metadata into your reporting systems

Troubleshooting

If you encounter issues when using the MapHub API, try these common solutions:

IssuePossible Solution
Authentication failuresVerify your API key is valid and has not expired
Unexpected response formatCheck the API documentation for the expected request and response formats
Timeout errorsFor large file uploads or downloads, increase your client timeout settings
Python wrapper errorsEnsure you're using the latest version of the wrapper and check the GitHub repository for known issues

If problems persist, please contact us with details about the issue, including any error messages and the API endpoint you're trying to access.

Next Steps

Now that you're familiar with the MapHub API, you might want to explore:

MapHub QGIS Plugin