Enhanced Coordinate Map

The Enhanced Coordinate Map visualization (beta) displays a geographic area overlaid with circles keyed to the data determined by the buckets you specify.

By default, Siren Investigate uses a demonstration Siren tilemap server Open Street Maps service to display map tiles. This server has limited features and you should update the tilemap settings to another tilemap provider that you have configured, especially in a production setting. To use other tile service providers, configure the tilemap settings in investigate.yml.


Configuring external tilemap providers

You can use existing free or paid tilemap providers or build and serve your own tilemap tiles.

After you have setup your own tilemap provider, configure these settings in investigate.yml to have map visualizations render these tiles.

For example, to use an OpenStreetMap default provider, the configuration YAML settings would look like:

  url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
    attribution: '© [OpenStreetMap]("http://www.openstreetmap.org/copyright")'
      - a

The Data Tab


The default metrics aggregation for a coordinate map is the Count aggregation. You can select any of the following aggregations as the metrics aggregation:

  • Count (total number of documents present in the aggregation)

  • Average

  • Sum

  • Min

  • Max

  • Unique Count (total number of unique values present in the specified field within the aggregation)

When you select any of the above aggregations except Count, a Field dropdown is displayed from which you can select a field that is valid for the selected aggregation).

For more information, see Y-axis aggregations.

Enter a string in the Custom Label field to change the display label.

Clicking Advanced opens a field where you can enter a viable JSON input that acts on the field selected for the metrics aggregation. For example, the following JSON multiplies the number of employees by 1,000:

{"script" : "doc['number_of_employees'].value * 1000"}


Coordinate maps use the geohash aggregation. Select a field, typically coordinates, from the box.

  • The Change precision on map zoom check box is selected by default. Clear the check box to switch off this behavior. The Precision slider determines the granularity of the results displayed on the map. See the documentation for the geohash grid aggregation for details on the area specified by each precision level.

Higher precision increases memory usage for the browser displaying Siren Investigate as well as for the underlying Elasticsearch cluster.
  • The place markers off grid (use geocentroid) box is checked by default. When this box is checked, the markers are placed in the center of all the documents in that bucket. When cleared, the markers are placed in the center of the geohash grid cell. Leaving this checked generally results in a more accurate visualization.

You can customize your visualization. For more information, see Customizing aggregations.

The Options Tab

Map Collar Scale

A scaling factor for selecting which documents to use for the aggregation. A setting of 1 will select documents within the map extent, 2 will select documents within 2 times the size of the map extent, while a value of 0.9 will scale the selection to be 0.9 times the size of the map extent. The purpose of this feature is to avoid excessive fetches to Elasticsearch or slower performance due to too many results being fetched.

Map type

Select one of the following options from the box.

  • Scaled Circle Markers - Scale the size of the markers based on the metric aggregation’s value.

  • Shaded Circle Marker - Displays the markers with different shades based on the metric aggregation’s value.

  • Shaded Geohash Grid - Displays the rectangular cells of the geohash grid instead of circular markers, with different shades based on the metric aggregation’s value.

  • Heatmap - A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. Heatmaps have the following options:

    • Radius: Sets the size of the individual heatmap dots.

    • Blur: Sets the amount of blurring for the heatmap dots.

    • Maximum zoom: Tilemaps in Siren Investigate support 18 zoom levels. This slider defines the maximum zoom level at which the heatmap dots appear at full intensity.

    • Minimum opacity: Sets the opacity cutoff for the dots.

    • Show Tooltip: Check this box to have a tooltip with the values for a given dot when the cursor is on that dot.

Tooltip Formatter

Select from the following options:

  • Metric Value - A tooltip containing the coordinates and the metric value specified on the Data tab

  • Visualization - The option to add a Visualization as a tooltip. The contents of the visualization will be an aggregation based on the aggregation the tool tip is being applied to.

Close tooltip on mouseout

When mouse is hovered over aggregation a tooltip will appear. When the mouse is moved away from aggregation, the tool tip will disappear if this box is ticked; it will remain if unticked.

Legend Scale

Configuration settings for how the aggregation is displayed on legend +

  • Dynamic - Linear - Each class in the legend has the same size (e.g. values from 0 to 16 and 4 classes, each class has a size of 4)

  • Dynamic - Uneven - Each class will have the same number of documents inside, useful when data is unevenly distributed between the maximum and minimum ranges

  • Static - Manual specification of colors, values and number of classes for the legend scale

Scroll Wheel Zoom

When ticked, it is possible to use the mouse scroll wheel to toggle map zoom level. (+ and - work toggle zoom regardless of this)

Desaturate map tiles

Desaturates the map’s color to make the markers stand out more clearly.

Synchronize map

Synchronize the map canvas of this visualization with all other visualizations present on a dashboard that also have this option selected

Auto-fit map to data

Automatic zoom to include all Aggregations when filters are altered. This includes time filter. Disabled when panning or zooming.

WMS compliant map server

Check this box to enable the use of a third-party mapping service that complies with the Web Map Service (WMS) standard. Specify the following elements: +

  • WMS url: The URL for the WMS map service.

  • WMS layers: A comma-separated list of the layers to use in this visualization. Each map server provides its own list of layers.

  • WMS version: The WMS version used by this map service.

  • WMS format: The image format used by this map service. The two most common formats are image/png and image/jpeg.

  • WMS attribution: An optional, user-defined string that identifies the map source. Maps display the attribution string in the lower right corner.

  • WMS styles: A comma-separated list of the styles to use in this visualization. Each map server provides its own styling options.

If you need to display custom layers for the Region Map visualization, a geospatial server may provide the solution. See [Getting started with GeoServer].
Point of Interest layers

Add any elasticsearch index with a geo_point or geo_shape field as a marker or polygons:

  • Geo_point type POI layers can be viewed and can include popups activated and deactivated on mouseover and mouseout.

  • Geo_shape type POI layers are suitable for viewing, popups and creating geo-filters which are applied to aggregations, other POI layers and other visualizations when on the dashboards (see Apply filters below).

    To render a geo_shape field on the map, it is required for an index to also have a geo_point field type


Configuration options for POI layers:

  • Saved Search - Select any elasticsearch index from the dropdown menu. Note - will need a geo point field

  • Geospatial Field -  Select a geo point field within the Saved Search

  • Styling

    • For geo_point - Set the set the size of the marker to appear for each document

    • For geo_shape - Set color in Hex value form

  • Popup Content - Selecting fields to appear on popup tooltip

  • Limit - The number of markers that are allowed to appear for this Point of Interest layer. The default is 100

  • Apply Filters - Whether or not to include filters from Selection tools or geo_shape type POI layers, a different visualization on the same Dashboard or filters from other Dashboards applied through relational Navigator

Drag and drop POI Layers

You can also create a POI Layer when in Dashboard view. Simply drag and drop a dashboard that has a main search with a geo_point field. If the main search has multiple spatial fields, a modal will appear prompting you to select one.

The filters from the other dashboard will be applied and can be viewed by hovering over the filter icon in the layer control. Drag and drop layers will not be saved and can be removed at any point by clicking the remove layer button in the layer control


Configuration options for the use of a third-party mapping service that complies with the Web Map Service standard. Multiple layers (or layer groups) can be loaded. Many third party mapping services are available, and some of these are described in [Getting started with GeoServer].

  • Layer Name - A customizable label to appear in the map’s layer view (image)

  • Url - The URL for the WMS map service

  • WMS Layers - This is where layers (or layer groups) can be specified from a WMS server. There are two options:

    • If you have added a URL to a CORS-enabled WMS server - Investigate will internally run a WMS getCapabilities request and will populate a list of layers that can be added by clicking ①. These can be ordered, by clicking and dragging ② as below. The layer at the top of the list is drawn furthest in the background.

    • If your URL is not a CORS-enabled WMS server - The UI will remain the same. You can order your layers, separated by a comma. The first layer you specify will be drawn the furthest in the background.


      You can still see the available layers for the WMS by running a getCapabilities request. Below is an example from a local instance of Geoserver:


  • CQL Filter - Allows you to query your spatial layers as parameters in WMS requests

  • Min Zoom Level - The minimum zoom level that the WMS request will be visible

  • Max Zoom Level - The maximum zoom level that the WMS request will be visible

  • Max Features - The maximum number of features, up to a maximum of 10,000, to be rendered per tile from the specified layer(s). Note - Max features can be configured in the WMS, which overrides this setting

  • Styles - A comma-separated list of the styles for your layer. If you have access to the WMS server, you can assign defaults for these and it is possible for this field to be left blank. Otherwise, each map server provides its own styling options

  • Output Format - The image format to be returned by the WMS. The two most common formats are image/png and image/jpeg. Default is image/png

  • Non Tiled - The option to send the WMS request as one complete image to fit the map extent, or to send it in multiple tiles

  • Visible On Load - Check this option to draw the layer when the visualization is loaded. Note - this will be over ridden if a user saves their dashboard state

  • Elasticsearch WMS Options - Configuration options for WMS request

    • Aggregation - Allows for the customization of geohash request from WMS using elasticgeo. Example of aggregation WMS request using the company index in Siren’s classic demo (“location” has a Geo_Point field type): { "agg": { "geohash_grid": { "field": "location" } } }

    • Sync Filters - When ticked, the WMS response includes the filters made using Selection tools, visualizations in the same and visualizations from other dashboards.


This allows for point and polygon (including multipolygon) types to be rendered onto the the Enhanced Coordinate Map. Polygons can be clicked on for geo filter creation See image section above for description on Layer Name, Url and WFS Layers fields. For details on setting up a WFS server, see the [Getting started with GeoServer] guide. Additional fields specific for editing WFS layers:

  • Styling - Set color in Hex value form and specify the size of the marker to display on map

  • Output Format - The format that your spatial server is capable of responding with. The format for ArcGis Server is GeoJSON, and the format for Geoserver is JSON.

  • Popup Content - To configure a pop-up tooltip, create a comma-separated list of fields in the properties object of your GeoJSON features. For example, the parameter City_name,Pop_est adds the city name and the estimated population fields to each feature that is added to the map. Note: This parameter is case-sensitive.

Configuring Stored Layers

Before you begin, ensure that you have ingested the data for stored layers. For more information about ingesting stored layer data, see Loading Stored Layers into Elasticsearch. You can configure the stored layers by modifying the following parameters:

  • Spatial path - Defines the path that corresponds to a layer, for example, continents/europe/ireland.

The default configuration does not require the spatial_path attribute to be defined. Values will be taken from it if they are not found within the [Cascading Configuration Process].
  • Icon - Defines the favicon that is displayed for points on a map and layer control.

  • Color - Defines the color that is displayed on a map and in the Layer Control dialog.

  • Size - Defines the display size of points on a map.

  • Popup Fields - Defines the content of the tooltips that appear when the cursor moves over features.

  • Min Visible Zoom - The minimum map zoom a layer will be visible on the map

  • Max Visible Zoom - The maximum map zoom a layer will be visible on the map

It is important to consider the levels of zoom that you want to configure in your maps. For more information about Zoom levels, see this explanation on the LeafletJS website.

The cascading configuration process

A cascading process, which is similar to CSS, is used to assign configurations to each layer. Using this process, the most specific spatial_path to the given layer is checked for the presence of the configuration parameters first. After this check is complete, the spatial_path chain is followed and default values are assigned if a parameter is missing a configuration.

For more information, see the Detailed example of a stored layer configuration.

Configurations by parameter or field

You can configure some parameters by using one of the following methods: * The parameter method outlines the exact parameter to use on the map. Parameters are configured by a string. * The field method relies on configuring a field that exists within the documents of each layer. Fields are configured by using a single element array.

Table 1. Example: Values for configuring by parameter or field
Parameter Parameter examples Field examples


"World Countries"



"fas fa-arrow-alt-circle-down"



"#7CBFFA", "blue"



"xs", "s", "m", "l", "xl",



"is constant for all features"

["fields", "mustbein", "afeatures","propertiesobject"]







When a new Enhanced Coordinate Map visualization is created, the Stored Layer Configuration will be populated with a default object: Default stored layers configuration

Feature-level configurations

If any of the icon, size, color, or popupField parameters are specified in a document’s properties object, this field will take precedence. This can be useful if you want to assign different icons within the same layer.

After changing options, click Apply changes to update your visualization, or Discard changes to keep your visualization in its current state.

Navigating the map

After your tilemap visualization is ready, you can explore the map in several ways using various tools:

Panning the map

  • Click and drag anywhere on the map to move the map center

  • Hold Shift to drag a bounding box across the map to zoom in on a desired extent

  • Viewing extent

    • Click Zoom In/Out (image) to change the zoom level manually.

    • Click Fit Data Bounds (image) to automatically crop the map boundaries to the geohash buckets that have at least one result.

  • Click Set View Location (image) to manually specify:

    • Whether latitude and longitude are in decimal degrees (dd) or degrees/minutes/seconds (dms) ①

    • The latitude ② and longitude ③ of the centroid of the canvas you would like to display

    • The desired level of zoom ④

    • Whether changes are applied ⑤ or cancelled ⑥


Selection tools - used to create geo filters

  • Click Draw a Polygon (image), then

    • Click on the map canvas and add vertices; if you add a vertex that you don’t want, click the Delete last point option on the menu that opens to the right when you clicked Draw a Polygon tool.

    • When complete, either click on the first vertex or double click and the polygon will autocomplete. Elasticsearch documents within the drawn polygon will be filtered.

  • Click Latitude/Longitude Filter (image), then drag a bounding box across the map, to create a filter for the box coordinates. Elasticsearch documents within the drawn polygon will be filtered.

  • Click Draw a Circle (image), then drag a circle and release to select documents. Elasticsearch documents within the drawn polygon will be filtered.

For all selection tools, a geo filter is created. This will appear above the map canvas:

+ image

Multiple geo filters

If exactly one geo filter (i.e. a pill similar to the above image) exists, and you create another geo filter for the same map visualization, you will be prompted by the modal below:

  • Overwrite existing filter - Replaces the exising geo filter with the new one you have created

  • Create new filter - Creates a new filter and will keep the existing one, use this option to create an AND

  • Combine with existing filters - Merges the new filter with the existing one, use this option to create an OR

Note - You can cancel filter creation from this modal by clicking the X in the top right


Marking tools

  • Click Draw a Marker (image), and select any point on the map to place a marker. You can add multiple markers.

  • After adding at least one marker, the Delete Marker(s) option becomes available

    • Point and click to delete individual markers

    • Remove all of them by clicking Clear All

Viewing detailed information

For information on displaying the raw data, see Visualization Spy.

Loading Stored Layers into Elasticsearch

Loading methods

There are two methods for loading the GeoJSON files into Elasticsearch. These are the Folder Structure and the Spatial Path methods. Both will accept files of type json or geojson. The methods differ in how their spatial_path is determined.

Folder structure

This method requires all GeoJSONs to be contained in a folder structure, that will determine scope/layer of each GeoJSON file.

Folder structure

Spatial path

This method requires all GeoJSON features to have a spatial_path property in their properties object. This will determine its scope/layer, example.

Spatial path

File validation

Each file need to meet the following criteria:

  • Can not be empty

  • Must be of geometry type Polygon and MultiPolygon OR Point NOTE: Polygons and Points must be in a separate file. A spatial path must be either Point OR Polygon, not a mixture of both

  • If using the spatial path loading method, each GeoJSON feature must contain the spatial_path property

If these requirements are not met, the validation process will fail without loading the GeoJSONs.

Spatial path

Spatial path is the scope/layer of a feature. Documents that have the same Spatial path, will be part of the same layer when used in Investigate.

Folder structure

When using the folder structure loading method the spatial path will be constructed based on the folder structure the GeoJSON file is in.

Here is an example of a spatial path for Continents/Europe/Poland/counties.geojsoncontinents/europe/poland

The file …​/Poland/counties.geojson contains 34 counties that make up Poland while …​/counties 2.json` contains the other 8 Polish counties. The spatial path of both GeoJSONs when ingested is specified below. They will be loaded as one layer on Enhanced Coordinate Map Visualization, i.e. one 42 county layer: continents/europe/poland

Spatial Path

The spatial path loading method requires each feature to contain a spatial_path property in the properties object of each GeoJSON feature. This is checked for during initial validation.

  "type": "Feature",
  "properties": {
    "county": "Galway",
    "population": 86000,
    "spatial_path": "continents/europe/ireland"
  "geometry": {
    "type": "Polygon",
    "coordinates": []


To load files into Elasticsearch go to siren-investigate/bin folder and run load_map_reference_indices script with appropriate arguments.

Make sure a user that has Elasticsearch write permissions is used for authorization.


  • -p/--path/--inputdir specifies a path to the folder containg files

  • -y/--yml allows for using a custom investigate.yml. If omitted, the default configuration from /config/investigate.yml will be used

  • --username <username> --password <password> allows for specification of Elasticsearch authorization credentials. If <username> and <password> are left blank, environmental variables LOAD_LAYERS_ES_USERNAME, LOAD_LAYERS_ES_PASSWORD will be used. If not used at all, credentials specified in /config/investigate.yml will be used instead

  • --dryrun will run the validation stage of the script, but will not connect to Elasticsearch

  • --delete deletes all .map__ prefixed indices before loading new ones, useful for reloading files

  • --structure/--spatialpath determines the loading method

  • -n specifies the maximum number of documents per single request - higher number will result in heavier requests (default 500)

  • -r/--simrequests specifies the number of simultaneous requests made to Elasticsearch (default 40)

  • --debug outputs additional debug information, including Elasticsearch autorization credentials


./bin/load_map_reference_indices.sh -p "/home/siren/geoJsonFolder" --structure

./bin/load_map_reference_indices.sh -p /home/siren/geoJsonFolder -y /home/siren/config.yml --username admin --password password --structure

./bin/load_map_reference_indices.sh -p /home/siren/geoJsonFolder --username --password --spatialpath

The console output below is a successful file load (with --debug) to Elasticsearch Console output

Loading stored layers from Elasticsearch into the Enhanced Coordinate Map

In this section, you can learn how to load stored layers into the map.

You will need to have layers stored in elasticsearch in indices that have a .map__ prefix. See [Loading map layers into Elasticsearch] for details on our recommended way to load these.

In top right click of an Enhanced Coordinate Map visualization, click on the Layer Control to toggle it open. When the ‘Add Layers’ button is clicked, a modal (below) will appear displaying Stored Layers (e.g. Irish Counties) and the group they are in (i.e. World Countries).

Add Layers Modal

It is possible to add a layer type corresponding to a group and we will explain with the aid of an example below, using the US states layer:

  • If the US states group checkbox is toggled, all layers and groups in that group will also be toggled

    • If the US States layer checkbox is toggled, only the layer will be affected

    • If the California nested group is toggled, only the checkboxes within that group will be toggled

  • If either a nested group or a layer box is unticked, the group will become indeterminate indicating that some of the boxes in that group are unchecked

  • Finally, if no items in a group a checked, the group checkbox will be unchecked

To add the selected layers to the map but keep them hidden for now, click Add. To add the layers to the map and also make them visible, click Add and Enable.

You can configure the stored layers when your visualization is in edit mode. For more information, see when in Visualization edit mode.

Stored layers and the map

If a Polygon is clicked when loaded on the map, Geo Filter(s) will be created

Layer control

The Layers function is located in the top-right corner of any Enhanced Coordinate Map. It allows you to select which layers that you want to display on the map. The following image shows multiple layers that can be selected and displayed as needed. You can load stored layers into the map from Elasticsearch. For more information, see Loading stored layers from Elasticsearch.

The Layers function

Layer Ordering

Layers are drawn on the map in the same order they are in the Layer Control. Layers can be ordered by clicking the drag handle to the left of any checkbox and dragging them to the desired position.

Layers will be automatically positioned at the top or bottom of their type in the event that they are dropped out of order. The precedence is:
  • Markers

  • Point Layers

  • Polygon Layers

  • Tile Layers

Layer Visibility

Layers can be toggled on and off by clicking the checkboxes

Features Omitted Due to Request Limits

If there are more features in the map canvas than are allowed by the Elasticsearch query size response limit, a warning icon appears beside the layer.

Detailed example of a stored layer configuration

The icon, color, size, or popupFields can be specified in the properties object of an Elasticsearch document. For example, by using the following code, the church appears as a red heart on the map:

   "spatial_path": "pois/states/churches",
   "geometry": {
     "type": "point",
     "coordinates": [ [ 100.0, 0.0 ] ]
   "properties": {
     "icon": "heart",
     "color": "red",
     "popupfields": ['Label','denomination']
   "colorfield": "green"
Example 1: A document with some configuration fields
     "spatial_path": "pois/states/churches",
     "icon": "cross",
     "color": ["colorfield"],
     "popupfields" : ['Label','denomination']
     "spatial_path": "pois/states",
     "icon": "map",
     "popupfields" : ['Label','statecode’],
     "maxZoom": 15
     "color" : "default_color",
     "icon": "default_icon",
     "popupfield" : [],
     "minZoom": 0,
     "maxZoom": 18
Example 2: The stored layer configuration

The values for the icon, size, popupFields, and color properties on the map are taken in the following order: . From the feature itself. . Then, from the the most specific spatial_path parameter in the configuration. . Then, from the next most relevant spatial_path parameter in the configuration. . Finally, the root of the configuration is reached and a default value is assigned. The values for the maxZoom and minZoom properties on the map are taken in the following order: . From the most specific spatial_path parameter in the configuration. . Then, from the next spatial_path parameter in the configuration. . Finally, the root of the configuration is reached and a default value is assigned. The values for icon and color for the layer in the [Layer Control] are taken in the same order as the maxZoom and minZoom properties.

Configurations for example 1

For the example document above, the properties on the map will be:
  • color: red - taken from the feature document

  • icon: heart - taken from the feature document

  • size: m - this is the underlying default

  • popupField: ["label", “denomination”] - taken from the feature document

  • maxZoom: 15 - taken from the configuration with the “pois/states” spatial_path

  • minZoom: 0 - taken from the default configuration (the configuration without spatial_path attribute)

The properties on the [Layer Control] for example 1 will be:
  • color: green - field type, taken from the configuration and retrieved from a document with the “pois/states/churches” spatial_path

  • Icon: cross - taken from the configuration with the “Pois/states/churches” spatial_path If there are more features present within the current map canvas extent than were retrieved with the set Elasticsearch query size response limit, a warning icon will appear beside the layer. The warning icon has a tooltip indicating this and the set current limit

Configuring layer security

Index security

By default, only the sirenadmin user has the permissions to view the map layer indices. To make layers available for other users to configure, you must assign read permissions to their roles. To configure the permissions, open Access control, click the Roles tab, and add the prefix ?map__* to the allowed indices in index_permissions.


This prefix will apply permissions to all map indices. If you want to be more specific, you can add each index to the role individually.

Document-level security (DLS)

You can configure document-level security on the map indices, which allows only the documents that match the DLS query to be returned.

To maintain system performance, run DLS map queries ONLY on the map indices. For more information, see the Search Guard performance considerations.

Configuring security by spatial path

The following DLS query retrieves only the documents that contain "World Lakes" in their spatial_path parameter:

  - index_patterns:
      - '?siren*'
      - article
      - company
      - investment
      - investor
    fls: []
    masked_fields: []
      - READ
  - index_patterns:
      - '?map__*'
    dls: '{ "match": { "spatial_path":"World Lakes" } }'
    fls: []
    masked_fields: []
      - READ

Configuring security by geo-shape

The following DLS query retrieves only the documents that are within the specified coordinates:

- index_patterns:
    - '?map__*'
  dls: >-
    { "geo_shape": { "geometry": { "shape": { "type": "Polygon",
    "coordinates": [ [ [ -12.85400390625, 50.680797145321655 ], [
    -4.306640625, 50.680797145321655 ], [ -4.306640625, 56.42605447604972 ], [
    -12.85400390625, 56.42605447604972 ], [ -12.85400390625,
    50.680797145321655 ] ] ] }, "relation": "within" } } }
  fls: []
  masked_fields: []
    - READ

Configuring security by properties fields

The following DLS query retrieves only the documents that match a specific property:

- index_patterns:
    - '?map__*'
  dls: '{ "term": { "properties.CONTINENT.keyword": "North America" } }'
  fls: []
  masked_fields: []
    - READ