Specifying new geocoding tables

TIBCO Spotfire comes with a selection of geocoding hierarchies that are normally stored in the library (for on-premises and TIBCO Cloud Spotfire users). You can also define your own geocoding tables using shapefiles (.shp), GeoJSON files (.geojson), or data tables and save them in the library for future use. This is accomplished by setting a few data table and column properties on the geocoding table in Spotfire and then exporting the file to the library. It is also possible to use locally stored geocoding tables.

Before you begin

Some of the functionality described here can only be authored or accessed using the installed Spotfire client.

You should have a basic understanding of the concepts in Geographic location and geocoding. See also Configuring WKB data for use with maps.

Procedure

Load the data containing the coordinates and/or geometries along with the identifying columns (such as state name or state code) in TIBCO Spotfire Analyst.
Select Data > Column properties and go to the Properties tab, to specify the necessary column properties for the identifying columns.

Tip: You can also specify some geocoding properties for a column from the Data in analysis flyout. Click on the column, make sure that Details on selected column is selected in the expanded flyout and choose suitable options under Geocoding, Settings.
Click on each geographic column that will be used to geocode data and specify the applicable properties (note that there might be several different columns in your data table that need one or more of these properties specified. For example, if you have a Geometry column, an X column and a Y column, all of those need different values on the mapchart.columntypeid property, as indicated below):
- GeocodingType is used to specify the type of geocoding identifiers in the column (such as Country, State or City).
- GeocodingRepresentation is used to specify the representation of the geocoding identifiers. It can be a language code (such as en-us, US-English) or a standard identifier, such as ISO3166-2:us, or some other ISO standard code.
- GeocodingHierarchyName is used to group geocoding columns that belong in the same hierarchy.
If the data originates from an ESRI shapefile or a GeoJSON file, the coordinates and geometry columns will automatically be tagged correctly, otherwise you must add the following column properties, as specified below (or see Configuring WKB data for use with maps):
- A longitude column should have the property mapchart.columntypeid with the value XCenter.
- A latitude column should have property mapchart.columntypeid with the value YCenter.
- A geometry column should have property mapchart.columntypeid with the value Geometry.
- A geometry column should also have the property ContentType with the value application/x-wkb.
These property values are what will be matched with the same property values of the data that should be geocoded later, so choose wisely.
Select Data > Data table properties and go to the Properties tab and add the following data table properties:
- MapChart.IsGeocodingTable is used to determine whether a saved SBDF file should be interpreted as a geocoding table or not. The data type for this property must be set to Boolean . Set the value for this property to True. The export will then pick up that it is a geocoding table and automatically transfer the properties to library properties.
- MapChart.GeocodingHierarchyName is used to group geocoding tables that belong in the same hierarchy. The data type is normally a String. Values are, for example, "USA 2022", "Belgium", etc.
- MapChart.GeocodingAutoload is used to indicate 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 large geocoding tables from being automatically downloaded. The data type must be set to Boolean. The value must be either True or False.
- MapChart.IsGeocodingEnabled is used to indicate whether the geocoding table is currently enabled. The data type must be set to Boolean. The value must be either True or False. This property is important when geocoding tables are saved in the library.
- MapChart.GeometryType is used to define the type of feature when the geocoding table contains a Geometry (shape) column. The data type must be set to String. The values can be either Point, Line or Polygon.
There are also a number of additional properties that you can specify for geocoding tables. These properties are not mandatory:
- MapChart.GeocodingHierarchyPriority is used to control 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 data type must be set to Integer, and the default value must be between 0 and 100 (100 being the highest priority).
- MapChart.GeocodingHierarchyVersion is used to specify the version of the geocoding hierarchy in the form of a date (YYYYMMDD).
- MapChart.GeographicCrs is used to specify the coordinate reference system describing the data (e.g., "EPSG:4326" for WGS 84).
- MapChart.ExternalGeographicCrs is used to store the EPSG code of the projection identified by the shapefile projection web service. The MapChart.ExternalGeographicCrs property is in use when the identified projection already exists in Spotfire's list of projections.
- MapChart.ExternalGeographicProj4Def is used to store the Proj4 definition generated by the shapefile projection web service. The value stored in this property is used by Spotfire to create a Generated CRS. The MapChart.ExternalGeographicProj4Def property is in use when the shapefile’s projection does not already exist in Spotfire’s list of projections.
Export the table to the library as SBDF using File > Export > Data to library to make it available for other users and for use in other analyses.
The data table is saved as a file in the library and will be available in all places where a geocoding hierarchy can be selected.
Restart Spotfire for changes to take effect.