Specifying new geocoding tables

Spotfire comes with a selection of geocoding hierarchies that are either stored in the library (for on-premises environments) or saved locally. You can also define your own geocoding tables using shapefiles (.shp), GeoJSON files (.geojson), or data tables with categorical (usually string) hierarchies, and save them in the library, or locally, for future use. This is accomplished by setting a number of data table and column properties on the geocoding table in Spotfire.

Before you begin

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

About this task

Tip: You can also specify some geocoding properties for a column from the Data in analysis flyout. Click on the column, make sure that Column settings

is selected in the expanded flyout and choose suitable options under Geocoding, Settings.

In most cases, your analysis will already contain the column properties or data table properties needed, because they are automatically added when opening geographical data. However, if a property that you want to specify is missing, you can add it from the Data tables overview in the data canvas. See Adding a new data table or column property for more information.

Note: Different types of geographical data requires a different set of properties and you usually only require some of the properties mentioned below.

Procedure

Load the data containing the coordinates and/or geometries along with the identifying columns (such as state name or state code) in your Spotfire client.
On the authoring bar, click Data canvas .
Make sure the data table of interest is selected, click on the final node of the graphical structure and, in the lower right part of the data canvas, click Column properties.
Here, you can specify the necessary column properties to identify columns as geocoding columns.
Locate each column that should be used to geocode data in the drop-down list (you can type to search for a column name) and double-click on a property name to open a dialog where you can specify the property value (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 (Binary or BLOB), an X column and a Y column (Real), 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 can be 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 and edit their values, 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.
When you have specified the required column properties, click Data table properties to specify one or more of 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", and so on.
- MapChart.GeocodingAutoload is used to indicate whether 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 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 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 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. The data type must be 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 (for example, "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 the Spotfire 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 the Spotfire list of projections.
Either export the data table to the library as an SBDF using File > Export > Data to library to make it available for other users and for use in other analyses, or use File > Export > Data to file to save a local SBDF file.
The data table is saved as a geocoding data table and can be used in all places where a geocoding hierarchy can be selected.