Define a geospatial lookup in Splunk Web

Use geospatial lookups to create queries that return results that Splunk software can use to generate a choropleth map visualization. Choropleth maps cannot be rendered without the data generated by corresponding geospatial lookups.

A geospatial lookup matches location coordinates in your events to location coordinate ranges in a geographic feature collection known as a Keyhole Markup Zipped (KMZ) or Keyhole Markup Language (KML) file and outputs fields to your events that provide corresponding geographic feature information that is encoded in the feature collection. This information represents a geographic region that shares borders with geographic regions of the same type, such as a country, state, province, or county.

Splunk provides two geospatial lookups; one for the United States and one for world countries, enabling you to render choropleth maps:

The USA, divided into states

The world, divided into countries

This topic shows you how to create additional geospatial lookups that break up choropleth maps into other types of regions, such as counties, provinces, timezones, and so on.

For information about choropleth maps and geographic data visualizations, see Mapping data in the Dashboards and Visualizations manual.

The workflow to create a geospatial lookup in Splunk Web is to upload a file, share the lookup table file, and then create the lookup definition from the lookup table file.

The FeatureId and featureCollection fields

Geospatial lookups differ from other lookup types in that they are designed to output these two fields: featureId and featureCollection. The featureId is the name of the feature, such as California or CA or whatever name is encoded in the feature collection. The featureCollection field provides the name of the lookup in which the feature was found.

If you pipe the output of a geospatial lookup into a geom command, the command does not need to be given the lookup name. The geom command detects the featureId and featureCollection fields in the event and uses the lookup to generate the geographic data structures that the Splunk software requires to generate a choropleth map. However, geographic data structures can be large. It is strongly discouraged to pipe events into the geom command, because geographic data structures are attached to every event. Instead, first perform stats on the results of your geographic lookup, and only perform geom on an aggregated statistic like count by featureId.

The Feature Id Element field

The Feature Id Element field is an XPath expression that defines a path from a Polygon element in the KML file to some other XML element that contains the name of the feature. Splunk software calls these Polygon elements a "feature". This is needed in cases where the typical style of named Placemark element is not in use.

The Feature Id Element field may be required in cases where the featureID field generated by the lookup is an empty string, or when the feature collection returns incorrect features by default. In the latter case, the feature may be a peer of the default feature or is located relative to the default feature.

To determine what path you need, review the geographic feature collection. Each feature in the collection is tagged with <Placemark>, and each <Placemark> contains a name that the lookup writes out as featureId fields. For an example, see feature_id_element.

The default setting for Feature Id Element is /Placemark/name.

XPath and feature id element example

The following is an example <Placemark> element extracted from a KML file.

The <Placemark> element contains both a <name> element and a <Polygon> element. A <Placemark> can have multiple <Polygons>. <Placemark> associates a name to a set of <Polygons>, called a "feature." However, different KML files may organize their data differently, so we need to tell Splunk software where to find the name, relative to the <Placemark> element. We can do this with the Feature Id Element field. By default, Feature Id Element contains the XPath expression /Placemark/name.

Let's take a look at another <Placemark> element extracted from a KML file.

An XPath expression that defines a path from a Polygon element in the KML file to another XML element or attribute that contains the name of the feature. Required when named Placemark elements are not in use.

Click Save.

Your lookup is defined as a geospatial lookup and appears in the list of Lookup definitions.

Share the lookup definition

Now that you have created the lookup definition, you need to specify in which apps you want to use the definition.

In the Lookup definitions list, for the lookup definition you created, click Permissions.

In the Permissions dialog box, under Object should appear in, select All apps to share globally or the app that you want to share it with.

Click Save.

In the Lookup definitions page, your lookup now has the permissions you have set.

Permissions for lookup table files must be the same or larger than those of the lookup definitions that use those files.

You can use this field lookup to add information from the lookup table file to your events. You can use the field lookup by specifying the lookup command in a search string. Or, you can set the field lookup to run automatically.

Make the lookup automatic

Instead of using the lookup command in your search when you want to apply a field lookup to your events, you can set the lookup to run automatically. See Define an automatic lookup for more information.

Enter your email address, and someone from the documentation team will respond to you:

Send me a copy of this feedback

Please provide your comments here. Ask a question or make a suggestion.

Feedback submitted, thanks!

You must be logged into splunk.com in order to post comments.
Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic.
If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk,
consider posting a question to Splunkbase Answers.

0
out of 1000 Characters

Your Comment Has Been Posted Above

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website.
Learn more (including how to update your settings) here »