What is Geocoding?

In order to display data on a map, the data needs to be geocoded. Geocoding in TIBCO Spotfire is the process of using some type of identifiers in a data table and matching those to similar identifiers in another set of data tables (a geocoding hierarchy) which contains latitude/longitude coordinates or geographic features. These coordinates or features are then used for correctly positioning the data in a map context.

If your data contains simple geographic elements such as country names, states, or similar, then Spotfire will attempt to automatically geocode your data. If no automatic geocoding can be performed, you can set up the geocoding manually instead.

Many parts of the user interface allow you to specify that a column in a data table should be used to match against a specific geocoding hierarchy. This will make the process of setting up a map chart with that data easier.

Automatic Geocoding and Hierarchies

A geocoding hierarchy is a collection of ordered geocoding tables that can give you the opportunity to drill down to a more detailed level when zooming in on the data. The hierarchy should contain all geocoding tables that the layer should be allowed to choose from when applying geocoding, and it should preferably be a geographic hierarchy with different level of detail, such as:

Table 1: US States (a table containing state geometries identified by state names (and/or codes).
Table 2: US Counties (a table containing county geometries identified by the full state/county hierarchy).

When selecting the best suited geocoding table, Spotfire checks the expression on the Geocode by/Marker by-axis and chooses the geocoding table to which the geocoding primary key columns can be matched using column matching. If only State is used on the axis, the US States table would be selected, but if both State and County are used on the axis, then the US Counties table is selected.

Once Spotfire has chosen a geocoding table, the visualization downloads and joins in that table in the map chart based on the found column matches.

For the cases where the column names in the data table do not match any of the columns in the available geocoding tables, you can try using the Auto-match button to match on the content of the column rather than on the column name.

Manual Geocoding

When you are manually setting up geocoding you need to consider which columns in your data can be used to identify the location of the data. For example, this could be a State column or a State/County hierarchy. Note that the level at which you select to display your data is the one that should be used for geocoding, since the Marker by axis and the Geocoding by axis are the same in marker layers. Hence, if you want to show data for different states you must geocode by state and not by counties.

You can specify the geocoding type and representation for a selected column in your analysis using the pop-up menu in the Data panel or in Column Properties.

Geocoding Hierarchies in the Library

A set of default geocoding hierarchies are shipped with TIBCO Spotfire Server as a zip archive which a library administrator can import into the library, as described under Importing to Library. Each hierarchy consists of a number of geocoding tables. Once imported, the geocoding hierarchies are normally located in the GeoAnalytics folder in the library. Since most of these geocoding tables contain geographic shapes they can also be used as feature layers in your map chart. The geocoding hierarchies located in the library will appear in the list when you click Add in the Marker Layer Settings – Positioning dialog and the Feature Layer Settings – Geocoding dialog.

You can also add your own geocoding tables to the library by following the instructions in Setting Up New Geocoding Tables.

Note: If you are using TIBCO Spotfire Desktop these geocoding tables are saved locally. For details, see below.

Locally Stored Geocoding Tables

It is possible to add locally stored geocoding tables to an analysis, if, for example, you do not have access to the library. To add a locally stored geocoding table follow these steps:

Open the properties page for the map chart.
Click Layers.
Select the marker or feature layer you want to use the geocoding for and click Settings.
Click Positioning in the Marker Layer Settings or Geocoding in the Feature Layer Settings.
For the Marker Layer, select Geocoding.
Select the column you want to geocode by.
Click Add > Add Data Tables... next to the Geocoding hierarchy list.
Click Add > File... in the Add Data Tables dialog.
Browse to the geocoding table, click Open and then OK.
Note: If you are using TIBCO Spotfire Desktop, the default geocoding tables are located in the folder
C:\Users\<your user>\AppData\Local\TIBCO\Spotfire Desktop\<version number>\Example Data\Geocoding Data\

Geocoding Data Table Properties

Similar to in previous versions of TIBCO Spotfire the loading of a Shape file automatically sets the required properties both on the data table and on the columns in the resulting data table. This means that Shape files can always be used for geocoding both marker and feature layers, provided they contain some identification column (such as State name or similar). It is worth noting that a single SHP file (without a DBF file) never contains such identification information since all column information is located in the corresponding DBF file (except for the geometry column and the numeric columns that are calculated at import, such as XMin, YMax etc.).

There are a number of data table properties that are required for geocoding tables:

The MapChart.IsGeocodingTable property determines if a saved SBDF file should be interpreted as a geocoding table or not. It is either True or False. This property datatype must be set to Boolean.
The MapChart.GeocodingHierarchyName property is used to group geocoding tables that belong in the same hierarchy. For example, USA 2013.
The MapChart.GeocodingHierarchyPriority property controls the priority of the hierarchy in which the table is included. A geocoding hierarchy with higher priority will be selected first if two hierarchies result in an equal number of column matches when automatic geocoding is applied. This property datatype must be set to Integer, and the Default Value must be between 0 and 100.
The MapChart.GeocodingAutoload property indicates whether or not the geocoding table should be allowed to be automatically downloaded to the analysis when Spotfire finds out that it can be used as a geocoding table for the current data table. This value can be used to prevent geocoding tables from being automatically downloaded. For example, this may be desired if a particular geocoding table is very large. Autoloading is ultimately also controlled by the AutoloadGeocodingTables preference in the map chart preferences. The MapChart.GeocodingAutoload property is either True or False. This property datatype must be set to Boolean.
The MapChart.GeocodingHierarchyVersion property specifies the version of the geocoding hierarchy in the form of a date (YYYYMMDD).
The MapChart.IsGeocodingEnabled property indicates if the geocoding table is currently enabled. It is either True or False. This property datatype must be set to Boolean. This property is important when geocoding tables are saved in the library. See also Details on Edit Properties – Geocoding.
The MapChart.GeometryType property is used to define the type of feature when the geocoding table contains a Geometry (shape) column. It can be either Point, Line or Polygon.
The MapChart.GeographicCrs property should be set to the coordinate reference system describing the data (e.g. “EPSG:4326” for WGS 84).

Geocoding Column Properties

There are also a number of column properties that should be set on the columns in a geocoding table:

The GeocodingType property specifies the type of geocoding identifiers in the column (such as Country or State).
The GeocodingRepresentation property specifies the representation of the geocoding identifiers (such as US-English or some ISO standard code).
The GeocodingHierarchyName property is used to group geocoding columns that belong in the same hierarchy.
The mapchart.columntypeid property specifies the type of a map chart column in a Shape file. For example, Geometry, XCenter or YCenter. See Configuration of Geographical Data for Map Charts for more information.

The "geocoding" keyword is automatically added when Exporting Data to Library. This makes it possible to quickly show only geocoding tables by setting the search expression to "keywords:geocoding".

Preferences

A Spotfire Administrator can disable auto-loading of geocoding tables completely for a group of users by setting the AutoloadGeocodingTables preference to False. This may be desired if the group is on a slow connection or if the system repeatedly makes unwanted geocoding matchings.