Creating a Custom Map Connection

The easiest way to use your own maps in Tableau is by connecting to a WMS server or MapBox map. See Use WMS (Web Map Service) Servers and Use Mapbox Maps for more information.

If your map server does not support the WMS standard and is not a Mapbox map, you may still be able to connect to your map server by creating a connection from the Tableau Map Service (TMS). To connect to the TMS, create a .tms file. 

Note: While a .tms file may be helpful in connecting to your map server, Tableau does not test or support .tms files, and success may vary. 

Requirements for a TMS Connection

To connect to your map server using a .tms, your map server must have the following features:

• Maps are returned as a collection of tiles
• Tiles are in Web Mercator projection
• Tiles can be addressed by URL using the same numbering scheme as common web mapping services. 

Create a Simple TMS File

 A .tms file is a simple text file that you can create in a text editor.

1. Open a text editor.

2. Copy and paste the following XML into the text editor.

   <?xml version="1.0" encoding="utf-8"?>
<mapsource inline="<boolean>" version="8.1">
<connection class="OpenStreetMap" port="80" server="<server-url>" url-format="<url-format>" />
<layers>
<layer display-name='Base' name='base' show-ui='false' type='features' request-string='/' />
</layers>
</mapsource>

3. Replace <boolean>, <server-url>, and <url-format> variables as described in the "Required Variables in the TMS File" section in this article.

4. Save the TMS file with a .tms extension to the Mapsources folder of Tableau Desktop or Tableau Server.

   The default location for the Mapsources folder:

   • For Tableau Desktop on the Mac - /Users/<user>/Documents/My Tableau Repository/Mapsources

   • For Tableau Desktop on Windows - C:\Users\<user>\Documents\My Tableau Repository\Mapsources

   • For Tableau Server - C:\ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Mapsources OR /var/opt/tableau/tableau_server/data/tabsvc/vizqlserver/Mapsources

5. Open Tableau Desktop.

6. Connect to a workbook that contains location information.

7. Select Map > Background Maps, and then select the background map from the map server you configured in the TMS file.

8. (Optional) If you added the TMS file to the Mapsources folder in Tableau Server, publish the workbook to Tableau Server and see the background map you configured in the TMS file.

Required Variables in the TMS File

Only the following variables can be changed in the XML:

• <boolean>: Replace the <boolean> with either a true or false value.
  • A true value allows Tableau Desktop to save the configuration specified in the TMS file with the workbook. Use this value if your workbook is being published to Tableau Cloud or Tableau Public.
  • A false value requires Tableau Desktop or Tableau Server to have access to the TMS file saved in the Mapsources folder to display the maps from your map server.
• <server-url>: Replace <server-url> with the URL of your map server.
• <url-format>: Replace <url-format> with additional URL fragments that your map server requires. This might include the following tags:
  • {Z}: The {Z} tag indicates the zoom level. A zoom level of 0 displays the entire world in one map tile. The TMS will fetch map tiles up to level 16.
  • {X} and {Y}: The {X} and {Y} tags indicate the map tile coordinates. For more information about map tiles, refer to the following web pages:
    • OpenStreetMaps wiki page
    • Bing Maps web page

Example XML

Suppose you want to connect to a sample map server provided by OpenStreetMaps. The TMS file may look like the following:

<?xml version="1.0" encoding="utf-8"?>
<mapsource inline="true" version="8.1">
<connection class="OpenStreetMap" port="80" server="http://a.tile.openstreetmap.org" url-format="/{Z}/{X}/{Y}.png" />
<layers>
<layer display-name='Base' name='base' show-ui='false' type='features' request-string='/' />
</layers>
</mapsource>

Advanced TMS Settings

You can use the advanced TMS file format for special handling of API keys, and controlling the stretch, shrink, and washout of the map tiles.

Note: In the Mapsources folder you will find the TMS files that come with Tableau Desktop and Tableau Server. Settings that are configured in those files are not supported for connections to other map servers.

API key

If your map server expects the API key in the server URL, you can use the {K} tag in the <url-format> section of the connection element.

You can also separate the API key from your <url-format> string by using the {K} tag in your string and placing the API key in the username attribute.

The following example demonstrates how to use the {K} tag with the API key in the username attribute.

<?xml version="1.0" encoding="utf-8"?> 
<mapsource inline="true" version="8.1"> 
<connection class="OpenStreetMap" port="80" server="http://a.tile.mapbox.com" url-format="/v4/base.mapbox-streets+bg-e8e0d8_landuse_water_buildings_streets/{Z}/{X}/{Y}.png?access_token={K}" username="<your-api-key>"/> 
<layers> 
<layer display-name='Base' name='base' show-ui='false' type='features' request-string='/' /> 
</layers> 
</mapsource>

Maximum stretch and minimum shrink

By default, Tableau will take the map tiles it receives from the map server and stretch the map tiles to match your data. If you need more control over how your map tiles are displayed, you can set the maximum stretch, max-stretch, and the minimum shrink, min-shrink, attributes in the connection element.

If you set the maximum stretch and the minimum shrink to 1, Tableau does not stretch or shrink the map tiles. Instead, Tableau will snap the map zoom to the tiles. You can also set maximum stretch and minimum shrink attributes to values near 1 to allow some stretching or shrinking, as well as some snapping, depending on the zoom.

The following example demonstrates how to use the max-stretch and min-shrink attributes.

<?xml version="1.0" encoding="utf-8"?> 
<mapsource inline="true" version="8.1"> 
<connection class="OpenStreetMap" port="80" server="http://a.tile.openstreetmap.org" url-format="/{Z}/{X}/{Y}.png" max-stretch="1.2" min-shrink="0.667"/> 
<layers> 
<layer display-name='Base' name='base' show-ui='false' type='features' request-string='/' /> 
</layers> 
</mapsource>

Washout

By default Tableau will slightly wash out the map tiles it receives from the map server to make the data stand out. To control the level of washout of the map tiles, add the following section of XML directly before the closing tag of the root element, </mapsource> . You can change the washout value to any number from 0.0 to 1.0.

The following XML is an example of what can be placed before the closing tag of the root element, </mapsource>.

<mapsource-defaults version="8.1"> 
<style> 
<style-rule element="map"> 
<format attr="washout" value="0.0"/> 
</style-rule> 
</style> 
</mapsource-defaults>