To display data on a map, the data must either be geocoded or directly contain coordinates such as longitude and latitude. Geocoding in Spotfire means that some identifiers in a data table are used to match against 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.
By specifying that a column in a data table should be used to match against a specific geocoding hierarchy you can make the process of setting up a map chart with that data easier.
In this example, the state column is automatically identified as US States and the data is correctly positioned on the map.
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).
Spotfire automatically adds (hidden) geocoding data tables if you add a map chart for a data table where geographical names can be found. 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.
Manual Geocoding
When you are manually setting up geocoding you must 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 in map charts 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 by choosing a suitable Geocoding property or hierarchy under Geocoding in the expanded Data in analysis flyout or in Column Properties.
When using the Geocoding settings in the expanded flyout, you can easily specify that a column contains either longitude or latitude values, geometries, or some hierarchical location.
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 in the visualization properties (or under Hierarchy in the Geocoding settings in the Data in analysis flyout) to match on the content of the column rather than on the column name.
Geocoding Hierarchies in the Library
A set of default geocoding hierarchies are shipped with 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. Because 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 Spotfire Analyst without a server, 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 next to the Geocoding hierarchy list.
In the flyout that is opened, browse to the geocoding table to add, click Open and then OK.
Note: If you are using Spotfire Analyst without a server, you must install the default geocoding tables using a separate installer, as described in the readme file available with your installation kit. After installation, the geocoding tables are by default located in the folder C:\Users\<your user>\AppData\Local\Spotfire\<version number>\Example Data\Geocoding Data\
Geocoding Data Table Properties
The loading of a shapefile or GeoJSON file automatically sets the required properties both on the data table and on the columns in the resulting data table. This means that shapefiles and GeoJSON files can always be used for geocoding both marker and feature layers, provided that the files contain some identification column (such as State name or similar). It is worth noting that a single SHP file (without a DBF file), or a GeoJSON file without 'properties' JSON object, never contain such identification information because all column information is located in the corresponding DBF file for shapefiles, and in the 'properties' JSON object for the GeoJSON 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 applicable to 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 data type 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 data type must be set to Integer, and the Default Value must be between 0 and 100 (100 being the highest priority).
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 data type 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 data type 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 (for example “EPSG:4326” for WGS 84).
The MapChart.ExternalGeographicCrs property stores 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.
The MapChart.ExternalGeographicProj4Def property stores 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.
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 shapefile or GeoJSON 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".
Disabling Automatic Geocoding
A Spotfire Administrator can disable auto-loading of geocoding tables completely for a group of users by setting the AutoloadGeocodingTables preference to False. This preference is found by selectingTools > Administration Manager, go to the Preferences tab, and look in the MapChartPreferences group. This may be desired if the group is on a slow connection or if the system repeatedly makes unwanted geocoding matchings.