> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/llms.txt)

# Add a Mapbox map as a basemap in ArcMap Pro and QGIS with WMTS

You can use a [Mapbox map style](https://docs.mapbox.com/api/maps/styles/) as a layer in popular GIS software like ArcMap Pro and QGIS. The map style you add will appear as a *raster* tile layer that you can use as a basemap alongside other layers in your GIS projects.

This tutorial will guide you through the steps to add a style as a **WMTS layer** in both ArcMap Pro and QGIS. You can use a [Mapbox-hosted style](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) or a custom style you've created in [Mapbox Studio](https://studio.mapbox.com). When you finish this tutorial, you will be able to add Mapbox styles to your GIS projects.

### What is WMTS?

**WMTS** stands for **Web Map Tile Service**. It is a standard protocol for serving image-based map tiles over the internet. WMTS is a popular way to add custom maps to from third-party services to GIS software. You can learn more about this protocol on the [OGC WMTS standard page](https://www.ogc.org/standards/wmts/).

Mapbox provides a WMTS endpoint for all styles created in [Mapbox Studio](https://studio.mapbox.com). You can use this WMTS endpoint to add your custom Mapbox styles as layers in ArcMap Pro and QGIS.

### What do Mapbox maps look like in ArcMap Pro and QGIS?

The following images show the [Mapbox Streets](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) style added as a WMTS layer in both ArcMap Pro and QGIS.

![Screenshot of ArcMap Pro with a Mapbox WMTS layer added to the Map](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-final-map.f382129.480.png) ![completed QGIS map with Mapbox style](https://docs.mapbox.com/help/assets/ideal-img/qgis-wmts-layer.8ab867f.480.png)

## Prerequisites

Before proceeding, make sure you have the following ready to go:

-   **Mapbox account**: [Sign up](https://account.mapbox.com/auth/signup/) for free or [log in](https://console.mapbox.com/) if you already have an account.
-   **ArcMap Pro** or **QGIS** installed on your computer. You should be somewhat familiar with your mapping software's interface before starting this tutorial.
-   **A Mapbox style**. Head to your Mapbox Studio [Styles page](https://console.mapbox.com/studio/) to see a list of the styles in your account. The style must be [public](https://docs.mapbox.com/studio-manual/reference/styles/#make-public-or-private) or the mapping software will not be able to retrieve it. You may also use a style provided by Mapbox, such as [Streets](https://docs.mapbox.com/api/maps/styles/#mapbox-streets).

## Add Mapbox maps in ArcMap Pro

Create a new map project or open an existing one, then follow the steps below to add your Mapbox style as a WMTS layer.

### Get a WMTS endpoint URL

Use the following URL format to build a WMTS endpoint for any Mapbox style:

```
https://api.mapbox.com/styles/v1/{username}/{style_id}/wmts
```

For a [Mapbox classic style](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles), the username is `mapbox` and the style ID appears in the style's URL. For example, the WMTS endpoint for the Mapbox Streets style is:

```
https://api.mapbox.com/styles/v1/mapbox/streets-v11/wmts
```

For a custom style, replace `{username}` and `{style_id}` with your own values from a style in [Mapbox Studio](https://console.mapbox.com/studio/). For example:

```
https://api.mapbox.com/styles/v1/jsmith/cl2fg9the00ab1234xyz/wmts
```

The style you choose must be [public](https://docs.mapbox.com/studio-manual/reference/styles/#make-public-or-private). You can set your style to public by clicking the ** Make public** option in Mapbox Studio.

### Get your public access token

When configuring the WMTS layer in ArcMap Pro, you must provide a Mapbox access token to authenticate your requests to the Mapbox APIs.

You can retrieve your access token from the [Access Tokens page](https://console.mapbox.com/account/access-tokens/) of the Mapbox Developer Console.

Keep your access token handy for the next step.

### Add your style as a WMTS layer in ArcMap Pro

To add a Mapbox WMTS layer in ArcMap Pro, you must add a new WMTS server via the Catalog pane.

1.  Right click anywhere in the Catalog pane. In the context menu, choose **New** > **New Server** > **New WMTS Server**.

![Screenshot showing menus for adding a new server in the Catalog Pane](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-new-server.1406a4a.480.png)

2.  You will see the *Add WMTS Server Connection* dialog box. Add the WMTS endpoint URL that you customized in the previous step to the "Server URL" field.

![Screenshot showing the WMTS endpoint URL](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-add-wmts-server-1.3453d70.480.png)

3.  Add your access token as a custom request parameter. Expand the **Custom request parameters** section, then add `access_token` in the **Parameter** column, and paste your access token in the **Value** column.

![Screenshot showing the access token as a custom request parameter](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-add-wmts-server-2.49a4f32.480.png)

4.  Click **OK** to dismiss the dialog box. If the connection is successful, you will see the new WMTS server under the **Servers** list in the Catalog pane with the name *Mapbox on api.mapbox.com.wmts*. You can expand the server to see that it includes a WMTS service, and that service include a WMTS layer with the name of your style.

![Screenshot of the ArcMap Pro Catalog pane with the new WMTS server added](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-server-added.480.png)

5.  To add the WMTS layer to your map, right click on the WMTS server (*Mapbox on api.mapbox.com.wmts*), then select **Add To Current Map**, or drag and drop the layer onto the map canvas.

![Screenshot showing the menu for adding a WMTS layer to the map](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-add-to-map.480.png)

Your style will appear on the map. You can zoom in and out to see the map tiles load at different zoom levels. With your Mapbox style now added as a WMTS layer, you can use it alongside other layers in your ArcMap Pro project.

![Screenshot of ArcMap Pro with a Mapbox WMTS layer added to the Map](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--arcmap-pro-final-map.f382129.480.png)

> **Note (warning)**
> 
> If you try to add a *private* map style to ArcMap Pro or QGIS, you will see an error message like:
> 
> > "Failed to download capabilities: Download of capabilities failed: Error transferring [https://api.mapbox.com/styles/v1/YOUR_USERNAME/YOUR_STYLE_ID/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN&SERVICE=WMS&REQUEST=GetCapabilities](https://api.mapbox.com/styles/v1/YOUR_USERNAME/YOUR_STYLE_ID/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN&SERVICE=WMS&REQUEST=GetCapabilities) - server replied: Not Found"
> 
> If you see this error message, go to Mapbox Studio, set the style to [public](https://docs.mapbox.com/studio-manual/reference/styles/#make-public-or-private), then try to add the WMTS layer again.

## Add Mapbox maps in QGIS

QGIS can also load map tiles from a WMTS server. First, build a WMTS endpoint for the style you would like to add to QGIS. Next, add this WMTS endpoint to your QGIS project.

### Get a WMTS endpoint URL

Use the following URL format to build a WMTS endpoint for any Mapbox style. You must append your access token as a query parameter to the end of the URL for QGIS to authenticate requests to the Mapbox APIs.

```
https://api.mapbox.com/styles/v1/{username}/{style_id}/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN
```

For a [Mapbox classic style](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles), the username is `mapbox` and the style ID appears in the style's URL. For example, the WMTS endpoint for the Mapbox Streets style is:

```
https://api.mapbox.com/styles/v1/mapbox/streets-v11/wmts
```

For a custom style, replace `{username}` and `{style_id}` with your own values from a style in [Mapbox Studio](https://console.mapbox.com/studio/). For example:

```
https://api.mapbox.com/styles/v1/jsmith/cl2fg9the00ab1234xyz/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN
```

The style you choose must be [public](https://docs.mapbox.com/studio-manual/reference/styles/#make-public-or-private). You can set your style to public by clicking the ** Make public** option in Mapbox Studio.

### Add your map in QGIS

To add your Mapbox map to QGIS:

1.  In QGIS, click the **Layer** menu, then select **Add Layer**, then click on **Add WMS/WMTS layer...**.
    
    ![Screenshot showing the location of the QGIS WMS/WMTS dialog box.](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--qgis-add-layer-from-server.cc788d0.480.png)
2.  You will see the **Data Source Manager** dialog box. Make sure the *Layers* tab is selected, then click **New**.
    
    ![Screenshot showing the QGIS Data Source Manager dialog box.](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--qgis-data-source-manager.337911c.480.png)
3.  Give the layer a name and add the WMTS endpoint URL that you customized in the previous step. Press **OK**.
    
    ![Screenshot showing the QGIS WMS/WMTS create connection dialog box.](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--qgis-create-wmts-connection.6bdd0a7.480.png)
4.  Back in the **Data Source Manager** dialog box, the name of your layer should appear in the select input at the top. When you see this, click **Connect**.
    
    ![Screenshot showing the QGIS Data Source Manager dialog box.](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--qgis-data-source-manager-2.ae432a6.480.png)
5.  The *Tilesets* tab will open, showing your new WMTS layer.Click the layer to select it. Click **Add**, then click **Close** to close the dialog box.
    
    ![Screenshot showing the QGIS WMS/WMTS layer confirmation and add dialog box.](https://docs.mapbox.com/help/assets/ideal-img/tutorials--mapbox-arcgis-qgis--qgis-wmts-tileset.8b6d130.480.png) ![completed QGIS map with Mapbox style](https://docs.mapbox.com/help/assets/ideal-img/qgis-wmts-layer.8ab867f.480.png)

You should see your map as a layer inside your QGIS project. You can zoom in and out to see the map tiles load at different zoom levels. With your Mapbox style now added as a WMTS layer, you can use it alongside other layers in your QGIS project.

> **Note (warning)**
> 
> If you try to add a *private* map style to ArcMap or QGIS, you will see an error message like:
> 
> > "Failed to download capabilities: Download of capabilities failed: Error transferring [https://api.mapbox.com/styles/v1/YOUR_USERNAME/YOUR_STYLE_ID/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN&SERVICE=WMS&REQUEST=GetCapabilities](https://api.mapbox.com/styles/v1/YOUR_USERNAME/YOUR_STYLE_ID/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN&SERVICE=WMS&REQUEST=GetCapabilities) - server replied: Not Found"
> 
> If you see this error message, go to Mapbox Studio, set the style to [public](https://docs.mapbox.com/studio-manual/reference/styles/#make-public-or-private), then try to add the WMTS layer again.

## Next Steps

Congratulations on adding a Mapbox style as a WMTS layer in ArcMap Pro or QGIS! You can now use your custom Mapbox maps in your GIS projects.

### What we covered

-   How to build a WMTS endpoint for a Mapbox style.
-   How to add a Mapbox style as a layer in ArcMap Pro or QGIS.

### Learn More

-   Read the documentation for the [Mapbox Styles API WMTS endpoint](https://docs.mapbox.com/api/maps/styles/#retrieve-a-maps-wmts-document)
-   [Learn more about WMTS (Web Map Tile Service)](https://en.wikipedia.org/wiki/Web_Map_Tile_Service) on Wikipedia.