Was this page helpful?
Yes No
Have a comment? Please leave it here. Thanks for your feedback!
All Tableau Help > Tableau Help > 
Design Views and Analyze Data > Build and Use Maps > Bring Location Data into Tableau > Custom Geocode Your Data
Applies to: Tableau Desktop

Custom Geocode Data

If you have locations that Tableau can't map, such as street addresses, you can custom geocode those locations. Custom geocoding means that you assign latitude and longitude coordinates to your locations so Tableau can plot them accurately. It also allows you to create custom geographic roles that you can use as you create map views in Tableau.

For example, if your data contains country, state/province, and street address data, Tableau Desktop will geocode your data to the country and state/province level, but will not recognize the street address data. In this case, you can create a custom geographic role for the street address data so that you can plot it on a map view in Tableau.

Follow the steps below to learn how to custom geocode your data.

Here's what you need to do:

  1. Create one or more CSV files with your location data

  2. Create a schema.ini file (optional)

  3. Import the files into Tableau

  4. Assign geographic roles to your fields

Before you start: Custom geocoding your data can be tricky. We recommend that you check out the Format Geographic Fields in Tableau topic to learn more about geographic roles and the types of data Tableau recognizes before you get started.

Step 1 : Create a CSV file with your location data

The first step to custom geocoding your data is creating a CSV file to import into Tableau. The contents of this file differ depending on whether you are extending an existing geographic hierarchy, adding a new geographic role, or adding a new hierarchy to Tableau.

However, the following applies to all custom geocoding files:

Extend an Existing Role

The built-in geographic roles in Tableau contain hierarchies that can be extended to include locations relevant to your data. For example, the existing hierarchy of Country > State/Province may not contain all of the states or provinces in your data. You can extend this level to include missing states or provinces.

The import file for this type of geocoding should contain every level of the hierarchy above the level you are extending. For example, if you are extending (adding data to) the State/Province geographic role, the existing State/Province hierarchy has a column for Country and State/Province, along with Latitude and Longitude.

In the import file, the names of the columns define the geographic roles. When extending an existing role, the column names must match the existing geographic roles in the hierarchy that you are extending. This will ensure that the new locations are added to the proper roles and hierarchies.

See the table below for information on how to organize hierarchies in your import file.

Built-In Hierarchy Columns to include in the .csv file (in order; left to right)
Country (Name)

Country (Name)

Latitude

Longitude

Country (Name), State/Province

Country (Name)

State/Province

Latitude

Longitude

Country (Name), State/Province, City

Country (Name)

State/Province

City

Latitude

Longitude

Country (Name), State/Province, County

Country (Name)

State/Province

County

Latitude

Longitude

Country (Name), ZIP Code/Postcode

Country (Name)

ZIP Code/Postcode

Latitude

Longitude

Country (Name), Area Code

Country (Name)

Area Code

Latitude

Longitude

Country (Name), CBSA

Country (Name)

CBSA

Latitude

Longitude

In addition to the Country (Name) column, you can optionally include the following columns: Country 2 char (ISO 3166-1), Country 3 char (ISO 3166-1), and Country (FIPS 10). If you include these columns, they should be just to the right of the Country (Name) column in any order.

Note: The highest level in the hierarchy is Country and cannot be extended to include higher levels such as Continent, etc.

Add New Roles

To add new geographic roles to the existing geographic hierarchy in Tableau, format your import file to include the new roles along with their parent roles.

When adding new roles to an existing hierarchy, the import file for those roles needs to contain the columns for each level in the existing hierarchy. For more information on the columns to include in each geographic hierarchy, see the built in hierarchy table in the Extend An Existing Role section.

Below is an example of an import file containing the locations of crater impacts in North America. Importing the file below would add the geographic role Crater Name to the existing Country (Name), State hierarchy. Notice that the column name for country matches the existing Country (Name) geographic role.

Once you have created your import file, save the file as a Comma Delimited (.csv) file (Windows Comma Separated if on a Mac) in a folder on your computer.

(Back to top)


Step 2 (Optional): Create a schema.ini file

Sometimes when you attempt to import custom geographic information in Tableau using a .csv file, you may see a ".csv could not be used because it does not contain a unique column" error message.

This is because your .csv file might contain numerical data, such as numeric postcodes. Tableau will only accept text fields for new geographic roles. However, you can create a schema.ini file to tell Tableau that the numeric field you want to import should be treated as a text field.

To learn how to create a schema.ini file, see Create a schema.ini File .


Step 3 : Import custom geocoding file(s) into Tableau Desktop

Once you have created a .csv file with custom geocoding you can import that file into Tableau.

  1. Open Tableau Desktop and navigate to a new or existing worksheet.

  2. Select Map > Geocoding > Import Custom Geocoding.

  3. In the Import Custom Geocoding dialog box, click the button to the right of the text field to browse to the folder your import file is saved in. All files in the folder will be imported into Tableau.

  4. Click Import.

The custom geocoding data is imported into the workbook and the new geographic roles become available.

Where does Tableau store my custom geocoding data?

When you import custom geocoding, the data is stored in the Local Data folder in your Tableau Repository. To import custom geocoding, your Tableau Repository must be on a local hard drive. The custom geocoding is then available for all workbooks.

Save custom geocoding files in a separate folder on your local computer. If you have several different sets of custom geocoding files, save each of them under their own folder names.

You can remove the custom geocoding stored in your Tableau Repository by clicking Map > Geocoding > Remove Custom Geocoding. This will not remove the geocoding from a packaged workbook, but it will remove it from the Local Data folder in your My Tableau Repository.

What happens to my custom geocoding data when I save my workbook?

When you save your workbook as a packaged workbook, the custom geocoding data is packaged with the workbook. When you open a packaged workbook you can import the custom geocoding from that workbook into your own Tableau Repository.

Note: Importing a new custom geocoding file will replace any custom geographic roles previously imported into Tableau.

(Back to top)


Step 4 : Assign geographic roles to your fields

Once you import custom geocoding into your workbook, the custom geographic roles become available. The next step is to assign those geographic roles to fields in your data source.

For example, if you decided to add a new geographic role that lists the latitude and longitude coordinates of crater impacts in North America, you can assign that geographic role to a field in your data source that lists the names of craters so when you create a map view with that field, the crater impacts are plotted in the correct locations on the map view.

To assign a custom geographic role to a field, in the Data pane, click the data type icon next to the field and select Geographic Role. Next, select a custom geographic role from the list.

You're now ready to start building a map view with your custom geographic roles. For more information on how to build a map view, see Mapping in Tableau.

See also:

Data Blending vs. Custom Geocoding

Blend Geographic Data

(Back to top)