Skip to content

Geo Map GL

The Geo Map GL allows you to visualize geospatial data and provides an improved API and rendering experience when compared with our previous Geo Map versions. You can configure layers to represent markers, heat maps, shapes, proportional circles, while dynamically controling visibility, opacity of shape colors, between many other options. This visualization is provided in the Geo GL visualization package.

The remainder of this document will refer to the Geo Map GL simply as Geo Map.

Initialization

This version of the Geo Map is based on MapLibre GL JS and it needs access to its external libraries when a Geo Map visualization is used. These resources are loaded from their default location unless the data application specifies an alternate location. The table below shows the Geo Map dependencies.

Variable Default Url
mapLibreJsUrl https://unpkg.com/maplibre-gl@3.2.0/dist/maplibre-gl.js
mapLibreCssUrl https://unpkg.com/maplibre-gl@3.2.0/dist/maplibre-gl.css

You can update the location of these resources in two ways:

Option 1: Specify the maplibre gl libraries in your HTML file as shown below.

1
2
    <link rel="stylesheet" href="/css/maplibre-gl.css" />
    <script src="/js/maplibre-gl.js" charset="utf-8"></script>

Option 2: Define the global variables specified in the table above to inject the location of the Geo Map dependencies:

1
2
3
4
5
    <script>
        window.mapLibreJsUrl = 'https://unpkg.com/maplibre-gl@3.2.0/dist/maplibre-gl.js';
        window.mapLibreCssUrl = 'https://unpkg.com/maplibre-gl@3.2.0/dist/maplibre-gl.css';
    </script>
    <script src="../../lib/CFToolkit.min.js"></script>

Note

To be consistent with MapLibre GL, this version of the Geo Map specifies location as [longitude, latitude] instead of [latitude, longitude].

Map settings

The Geo Map supports the settings described below.

layers

Sets the Geo Map layers. This is an array of objects where each object is the definition of a specific layer. Refer to the Layers section below for details on how to configure their different options.

enableZoom

Enables and disables the map's NavigationControl. Supported values for position are top-right, top-left, bottom-right, bottom-left, vertical-center-right, and vertical-center-left. The default configuration is the following:

1
2
3
4
5
6
.set('enableZoom', {
    position: 'top-left',
    showCompass: true,
    showZoom: true,
    visualizePitch: false
})

The NavigationControl looks like the image below:

The image below shows how the zoom control looks in different positions.

Another way to position the zoom control is to access the MapLibre Map object, and modify the position of the NavigationControl with one of the control positions mentioned above (e.g. bottom-right). The example below shows how to do this.

1
2
3
4
5
6
7
visual.on('execute:stop', () => {
    const navigationControl = visual.get('getNavigationControl')();
    const map = visual.get('map');

    map.removeControl(navigationControl);
    map.addControl(navigationControl, 'bottom-left');
})

Finally, you can completly disable map navigation by setting enableZoom to false as follows: 

1
.set('enableZoom', false)

When disabled, users will not be allowed to zoom or pan the map.

zoomCenterInfo

Enables or disables the rendering of the current zoom level as well as the longitude/latitude of the current position of the mouse pointer. Example:

1
2
3
.set("zoomCenterInfo", {
    position: "vertical-center-left"
})

The previous setting would render the zoom and center information as shown below.

The zoomCenterInfo is enabled by default with the bottom-right position. Supported values for position are top-right, top-left, bottom-right, bottom-left, vertical-center-right, and vertical-center-left.

You can also change its position programatically as shown in the code below:

1
2
3
4
5
6
7
visual.on('execute:stop', () => {
    const zoomCenterInfoControl = visual.get('getZoomCenterInfoControl')();
    const map = visual.get('map');

    map.removeControl(zoomCenterInfoControl);
    map.addControl(zoomCenterInfoControl, 'bottom-left');
})

fullScreen

Enables or disables the FullScreenControl. It is disabled by default. Supported values for position are top-right, top-left, bottom-right, bottom-left, vertical-center-right, and vertical-center-left. The following example shows how to use this setting.

1
2
3
.set('fullScreen', {
    position: 'top-right'
})

You can also change the position of this control programatically as shown below:

1
2
3
4
5
6
7
visual.on('execute:stop', () => {
    const fullScreenControl = visual.get('getFullScreenControl')();
    const map = visual.get('map');

    map.removeControl(fullScreenControl);
    map.addControl(fullScreenControl, 'vertical-center-left');
})

zoom

Sets the initial zoom value of the map. Example: .set('zoom', 0.5). It is -0.12348307389299135 by default.

center

Sets the initial center of the map. Example: .set('center', [0,0]). It is [-12.205643247916555, 43.17470268118143] by default.

bearing

Sets the default bearing in degrees. Visit the bearing section in the MapLibre documentation for more info.

pitch

Sets the default pitch in degrees. Visit the pitch section in the MapLibre documentation for more info.

showLocation

Sets the visibility of "Position" information (e.g. longitude/latitude) in the tooltip. This is applicable to markers, shapes and circle layers. Its default value is true. Setting it to false hides this information from the tooltip.

layersControl

The layers control allows users to manage the priority and visibility of their geomap layers interactively. Users can move layers up and down, make them visible or invisible as well as view the legend of visible layers.

The layers control is not enabled by default. To enable it, use the layersControl setting as shown below.

.set('layersControl', true)

Valid values for this setting are true and false. When true, the map renders the layers control on the top right corner in an "expanded" fashion.

This setting also accepts a JSON object to specify the position of the layers control as well as if it should be initially expanded or collapsed. The JSON object format is shown below.

1
2
3
4
.set("layersControl", {
    "position": "right", // right by default
    "collapsed": true
})

Supported positions values are right, left, top-right, top-left, bottom-right, and bottom-left.

Supported collapsed values are true and false.

drawControl

Warning

The drawControl is an experimental feature. Its documentation and configuration properties may change within minor and major releases.

The draw control allows users to filter by drawings. Options available are shapes, bounds and distance. The draw control is not enabled by default. To enable it, use the drawControl setting as shown below.

.set('drawControl', true)

Valid values for this setting are true and false. When true, the map renders the draw control on the top left corner.

Note

The draw control is currently supported only for the Elasticsearch 7.x data provider versions v7.16 and above.

Selecting the draw control expands its options as shown below.

When selecting one of these option, a form allows users to enter a filter label as shown below.

The element IDs of the form buttons are:

  • btn-accept-draw
  • btn-cancel-draw

You can use these IDs in CSS to customize the style of these buttons.

maxZoom and minZoom

Sets the max and min zoom levels. Example: .set('maxZoom', 10). Default maxZoom is 24 and default minZoom is 0.

style

This property specifies the custom style document that defines the visual appearance of the map. Please refer to the Style Specification section of the MapLibre documentation for more information regarding the style document. The example below shows how to set a style for your Geo Map:

1
.set("style", "https://api.maptiler.com/maps/streets/style.json?key=get_your_own_OpIi9ZULNHzrESv6T2vL")

The style document may include the definition of MapLibre layers that you can configure in your Geo Map. The example below does just that by rendering 3D buildings as illustrated in the Display buildings in 3D MapLibre example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
.set("zoom", 15.5)
.set("center", [-74.00659999999999, 40.71350000000001])
.set("pitch", 45)
.set("bearing", -17.6)
.set("style", "https://api.maptiler.com/maps/streets/style.json?key=get_your_own_OpIi9ZULNHzrESv6T2vL")
.on("execute:stop", e => {
    const map = cf.getVisualization(e.element).get('map');
    // The 'building' layer in the streets vector source contains building-height
    // data from OpenStreetMap.
    map.on('load', function () {
        // Insert the layer beneath any symbol layer.
        const layers = map.getStyle().layers;

        let labelLayerId;
        for (let i = 0; i < layers.length; i++) {
            if (layers[i].type === 'symbol' && layers[i].layout['text-field']) {
                labelLayerId = layers[i].id;
                break;
            }
        }

        map.addLayer({
            'id': '3d-buildings',
            'source': 'openmaptiles',
            'source-layer': 'building',
            'filter': ['==', 'extrude', 'true'],
            'type': 'fill-extrusion',
            'minzoom': 15,
            'paint': {
                'fill-extrusion-color': '#aaa',

                // use an 'interpolate' expression to add a smooth transition effect to the
                // buildings as the user zooms in
                'fill-extrusion-height': [
                    'interpolate',
                    ['linear'],
                    ['zoom'],
                    15,
                    0,
                    15.05,
                    ['get', 'height']
                ],
                'fill-extrusion-base': [
                    'interpolate',
                    ['linear'],
                    ['zoom'],
                    15,
                    0,
                    15.05,
                    ['get', 'min_height']
                ],
                'fill-extrusion-opacity': 0.6
            }
        }, labelLayerId);
    });
})

The above code will render a map like the one in the image below, which is exactly the same as the "Display buildings in 3D" example:

credentials

This property indicates whether the user agent should send or receive cookies from the other domain in the case of tile layers cross-origin requests. For more information visit the Request.credentials section of MDN Web Docs.

Layers

The layers setting configures your Geo Map layers. This setting consists of an array of objects where each object is the definition of a specific layer.

Declaring layers

Use the structure below to configure your Geo Map layers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
.set('layers', [
  {
    "type": "tile",
    "name": "Tile",
    "priority": 1,
    "properties": {
      /* layer's properties */
    }
  }, {
    "type": "shape",
    "name": "My Shape Layer",
    "priority": 2,
    "properties": {
      /* layer's properties */
    }
  }
])

Types of layers

Layers are divided into two main groups:

  • Non-query layers: They are tile, tile-wms, fixed-marker and shape-only
  • Data layers: They are shape, marker, circle, and heatmap. These layers obtain their data by performing queries to their associated data engine. For each data layer, ChartFactor creates an Aktive instance so that each layer can have its own data provider and data source and execute its own independent queries.

The Aktive instance ID

You may need to obtain the Aktive instance ID to configure drill-ins for a shape layer or to invoke a utility function. The Aktive instance ID is the concatenation of the element ID of the Geo Map visualization and the name of the data layer. For example, if the ID of the Geo Map is specified as .element('my-map-id') and a data layer "name" property is set to "My beautiful shape layer" then the Aktive instance ID of that layer is "my-map-id-My beautiful shape layer".

Layer settings

Common settings to all layers

All layers have the common settings below.

type

String representing the type of the layer

name

String with the unique name of the layer object in the array

priority

Integer greater than zero that determines which layer is rendered above the others. A layer with a higher priority is rendered on top of a layer with a lower priority. Note that in the case of tile and tile-wms layers, they will always be below the other layers, so the established priority will only influence between them.

Common settings to data layers

Data layers can specify the following settings:

provider

String with the name of a previously registered provider

source

String with the name of the data source

To illustrate, the example below declares a Geo Map with a tile layer and a shape layer. The shape layer name is "Realtor Monthly Inventory State" and it specifies Elastic Local as the data provider and realtor_monthly_inventory_state_all as the source.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
cf.create()
  .graph("Geo Map GL")
  .set("layers", [
      {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
      },
      {
          "type": "shape",
          "name": "Realtor Monthly Inventory State",
          "priority": 1,
          "provider": "Elastic Local",
          "source": "realtor_monthly_inventory_state_all",
          "properties": {
              "shapes": [
                  {
                      "url": "https://chartfactor.com/resources/us-states.json"
                  }
              ],
              "options": {
                  "rows": [
                      cf.Row("state_name", "State Name")
                  ],                    
                  "metrics": [
                      cf.Metric("median_days_on_market_mm", "avg")
                  ],
                  "color": cf.Color()
                      .autoRange({ dynamic: false })
                      .palette(["#fcfbfd", "#efedf5", "#dadaeb", "#bcbddc", "#9e9ac8", "#807dba", "#6a51a3", "#54278f", "#3f007d"].reverse())
                      .metric(cf.Metric("median_days_on_market_mm", "avg"))
              },
          }
      }
  ])
  .set("center", [-127.2658535, 51.86885231807966])
  .set("zoom", 2)
  .execute();

properties

This setting allows to configure your map layer with many configuration properties. The actual properties depend on the layer type.

The following sections cover:

  • Common properties across layers
  • Common properties to data layers
  • Properties specific of each layer type

Common properties across layers

visible

This visible property allows you show or hide a layer. When this is a data layer, the Aktive instance attached to the layer remains active even when the layer is hidden, keeping track of filters added or removed by the Interaction Manager component. However, the Aktive instance executes queries only when its respective data layer is visible.

visibilityZoomRange

The visibilityZoomRange property allows you to define a range of zoom values where the layer is visible. For example, if you want your layer to be rendered when the map zoom is greater than or equal to 4 and less than or equal to 6, you would use the definition below:

1
"visibilityZoomRange": [4, 6]

Common properties to data layers

The following are properties common to all data layer types:

  • filters
  • clientFilters
  • textFilter
  • staticFilters
  • legend

The example below illustrates how to set these properties.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
"filters": [
    cf.Filter('state').label('state').operation('IN').value(['Utah'])
],
"clientFilters": [
    cf.Filter('state').label('state').operation('IN').value(['Utah'])
],
"textFilter": `State:CA`,
"staticFilters": [
    cf.Filter('state').label('state').operation('IN').value(['Utah'])
],
"legend": 'left'

Note that when you are using the IM (Interaction Manager) component in your application, you can specify staticFilters while the IM automatically manages filters, clientFilters, and textFilter depending on user interactions.

For the legend property, the available positions are right, left, top-right, top-left, bottom-right, and bottom-left.

When multiple layers define a legend, the legend displayed on the Geo Map is the one that belongs to the layer on top. Please refer to the Legend documention for additional information on this visualization element.

The following sections cover properties specific to each layer type.

Layer-specific properties

Tile

This layer is based on the MapLibre raster layer type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "type": "tile",
  "name": "Tile 1",
  "priority": 1,
  "properties": {
    "source": {
        "tiles": [
            "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
        ],
        "scheme": "xyz",
        "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
    },
    "layer": {
        //...
    }
  }
}

The previous tile layer example renders with the attribution specified as shown below.

attribution

The properties object in the example above has two sub-properties: source and layer. All settings supported in the raster source section and the raster layer section of the MapLibre documentation are available to be configured within these two properties respectively.

Tile-Wms

WMS (Web Map Services) can also be used as tile layers. Like the tile layer, tile-wms layer is based on the MapLibre raster layer type.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "type": "tile-wms",
  "name": "Tile Wms 1",
  "priority": 2,
  "properties": {
    "source": {
        "tiles": [
            "https://img.nj.gov/imagerywms/Natural2015?bbox={bbox-epsg-3857}&format=image/png&service=WMS&version=1.1.1&request=GetMap&srs=EPSG:3857&transparent=true&width=256&height=256&layers=Natural2015"
        ],
        "tileSize": 512,
        "attribution": "NJ Geographic Information Network",
        "headers": [
            {
                "header": "Authorization",
                "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
            },
            {
                "header": "Content-Type",
                "value": "image/png"
            }
        ]
    },
    "layer": {
        //...
    }
  }
}

The previous tile-wms layer example will render the Map as shown below.

attribution

The headers property can be a function that returns an array of header configurations as shown below: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const getHeaders = () => {
    // Getting the token from localStorage for example
    const authData = JSON.parse(localStorage.getItem('auth'));
    if (authData && authData.access_token) {
        const bearerToken = 'Bearer ' + authData.access_token;
        const headers = [
            { header: 'Authorization', value: bearerToken },
            { header: 'Content-Type', value: 'image/png' },
        ];

        return headers;
    }

    return [];
};

Now, your WMS requests will contain headers that include the Authorization and Content-Type items configured as specified in the function above. The screenshot below shows the request headers after configuring the WMS tiles as specified in the previous example.

wms-tile-layers-headers

Fixed-Marker

We can define markers that are independent from the data. This is usefull when displaying fixed locations that are always going to be visible and are not affected by filters. These markers won't trigger any filters when clicked since they are not part of queried data. Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "type": "fixed-marker",
    "name": "Fixed Marker 1",
    "priority": 3,
    "properties": {
        "lngLat": [-74.93350894607465, 43.2622234032705],
        "label":
            "<div style=\"color: blue; font-size: 20px; width: 185px;\">My custom fixed pin</div>",
        "icon": "data:image/png;base64,...",
        "color": "red", // Default to #034e7b
    },
}

As seen in the example above, the label of the marker could be either a simple text or a string representing html code. The color used for the pin is red. The lngLat is a longitud and latitude array. This example will display the following:

attribution

The icon property accepts a base64 image that will be converted into a SDF-enabled image. For more information go to the Custom markers section.

Shape and Shape-Only

Both shape and shape-only layer types share the same properties but their behavior is different since, while a shape layer contains an instance of the Aktive class to execute queries on the data source, the shape-only layer only takes data from a geoJSON file defined in the url of each shape configured in the shapes property. See the shape type layer structure below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "type": "shape",
  "name": "State Name",
  "priority": 1,
  "provider": "provider-name",
  "source": "source-name",
  "properties": {
      "shapes": [
          {
            "name": "State Name",
            "url": "https://chartfactor.com/resources/us-states.json",
            "fitBounds": true,
            "featureProperty": "name",
            "shapeOpacity": 0.1
          },
          {
            "name": "County Name",
            "url": "https://chartfactor.com/resources/us-states/MT-30-montana-counties.geo.json",
            "featureProperty": "name",
            "fitBounds": true            
          }
      ],
      "legend": "right",
      "options": {
          "featureProperty": "custom_name",
          "shapeFillColor": "green",
          "shapeOpacity": 1,
          "shapeBorderColor": "blue",
          "shapeFillColorHl": "white",
          "shapeOpacityHl": 0.5,
          "shapeBorderColorHl": "red",
          "shapeBorderWeightHl": 3,
          "clientFilteredOutColor": "red",
          "clientFilteredOutColorOpacity": 0.2,
          "style": {
              "color": "#999", // Equivalent to shapeBorderColor
              "weight": 2, // Border weight
              "opacity": 1, // Border opacity
              "fillOpacity": 0.8, // Equivalent to shapeOpacity
              "fillColor": "#B0DE5C" // Equivalent to shapeFillColor
          },
          "allowClick": true,
          "allowHover": true,
          "allowMultiSelect": true,
          "dataField": {
              "name": "state",              
              "label": "State",
              "type": "ATTRIBUTE"
          },
          "metrics": [
              {}
          ],
          "color": {},
          "rows": [
              {}
          ],
          "fitBounds": true,
          "animationDuration": 1.5,
          "opacityZoomLevels": [
              {
                  "zoom": 1,
                  "fillOpacity": 0.1
              },
              {
                  "zoom": 6,
                  "fillOpacity": 0.8
              },
              {
                  "zoom": 10.1,
                  "fillOpacity": 0.1
              }
          ],
          "min": 0,
          "max": 20
      }      
  }
}

Here is the structure of the shape-only layer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
    "type": "shape-only",
    "name": "Borough shape only",
    "priority": 2,
    "properties": {
        "shapes": [
            {
                "url": "https://chartfactor.com/resources/ny.json",
            }
        ],
        "options": {
            "featureProperty": "name",
            "shapeOpacity": 0.6,
            "metrics": [
                {
                    "name": "shape_area",
                    "label": "Shape Area",
                    "type": "NUMBER"
                }
            ],
            "color": cf.Color()
                .autoRange({ dynamic: true })
                .palette(["#08306b", "#08519c", "#2171b5", "#4292c6", "#6baed6", "#9ecae1", "#c6dbef", "#deebf7", "#f7fbff"])
                .metric(cf.Metric("shape_area", "sum")),
            "rows": [
                {
                    "name": "name",
                    "label": "Borough",
                    "type": "ATTRIBUTE"
                },
                {
                    "name": "boro_code",
                    "label": "Borough Code",
                    "type": "ATTRIBUTE"
                }
            ],
            "fitBounds": true
        }
    }
}
Properties
  • shapes is an array of JSON objects. It should be noted that:
    • The url of the GeoJSON file is the only required property
    • When multiple shape objects exist in the shapes array, the last one is the shape that is data driven. Multiple shapes in the same layer are useful when you want to allow users to drill-in into a shape (e.g. from US level to a specific US State to show its counties) and still want to keep the parent shape rendered so that users can select not only counties but also other states.
    • The name property considerations:
      • For the data-driven shape this property should match the label of the first field specified in the rows array. This allows the map to synchronize the different geometric objects in the shape file and the field values in the data.
      • The main label that will be displayed on the shape tooltip is the value specified in this property.
      • When a shape is clicked, the filter name is also the value specified in this property.
    • You can also specify custom options for each shape if required. For example "featureProperty": "boundary_name" or "shapeOpacity": 0.1. When these options exist, they override the same option set at the options level.
    • The Interaction Manager will set these options automatically when you configure drill-in functionality
  • legend only applies to the shape type, not for shape-only layer type. For more information visit the Legends documentation.
  • options can be customized with options to speicify colors, borders and others. The next section describes these options in detail.
Options

Four main groups of options exist for shape layers. They are:

  • Shape-specific options
  • Interaction options
  • Data options
  • Miscellaneous options
Shape-specific options
  • featureProperty: This option should be set with the name of the GeoJSON's feature property that contains the values (e.g. county name, county code) that match the attribute values obtained from the data source. It defaults to "name".
Shape-specific options when not hovered
  • shapeFillColor: The color of the shape when it doesn't contain data. By default is white.
  • shapeOpacity: Applies some opacity to the shape. 0 is completely transparent and 1 is completely opaque.
  • shapeBorderColor: The color of the borders of the shape. Uses a dark color by default.
Shape-specific options when hovered
  • shapeBorderColorHl: The borders of the shape when it is hovered. By default it has the same value as shapeBorderColor.
  • shapeOpacityHl: Shape opacity when hovered. By default it has the same value as shapeOpacity.
  • shapeFillColorHl: The color of the shape when hovered. By default, the shape keeps its current color.
  • shapeBorderWeightHl: The thickness of the border when hovered.
Shape-specific options when client filter is enabled
  • clientFilteredOutColor: The color of filtered-out shapes, that is, when they do not match the applied client filter. By default the color is #CCC.
  • clientFilteredOutColorOpacity: Applies the specified opacity to the shapes that do not match the applied client filter. 0 is completely transparent and 1 is completely opaque. By default the value is 0.5.

It is also possible to define shape styles using the style property. Let's see the example below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "type": "shape",
    "name": "Realtor Monthly Inventory State",
    "priority": 2,
    "provider": "Aktiun Elastic",
    "source": "realtor_monthly_inventory_state_all",
    "properties": {
        "shapes": [
            {
                "url": "https://chartfactor.com/resources/us-states.json",
                "fitBounds": true,
                "featureProperty": "name",
                "shapeOpacity": 1,
                "name": "State Name"
            }
        ],
        "limit": 100,
        "options": {
            "style": {
                color: "#999",  // Equivalent to shapeBorderColor
                weight: 2,  // Border weight
                opacity: 1, // Border opacity
                fillOpacity: 0.8,   // Equivalent to shapeOpacity
                fillColor: "#B0DE5C" // Equivalent to shapeFillColor
            },
            "fitBounds": true,
            "allowMultiSelect": false,
            "featureProperty": "name",
            "animationDuration": 1.5
        },
    }
}

The previous code block renders the shape in Geo Map with the following look:

maplibre-shape-style

There are two things to keep in mind:

  • The described properties defined within the style object override the equivalent properties defined within the options object
  • Data-driven shape coloring (see Data options below) has prescedence over both style fillColor and options shapeFillColor properties
Interaction options
  • allowClick: True by default. Enables or disables the ability to trigger a filter when clicking a shape.
  • allowHover: True by default. Allows to display tooltips when the mouse goes over the shape.
  • allowMultiSelect: False by default. Enables or disables the ability to select multiples shapes.
Data options

  • rows:

    • For shape layer types, this is an array of Row objects that match the field names specified in the data source metadata.
    1
2
3
    "rows": [
    cf.Row("state_str", "State Name")
]
    • For shape-only layer types, this is an array of JSON objects. The name property of each object must match the name of the property specified in the features > properties object of the GeoJSON file. The specified properties will be rendered in the shape's tooltip.
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    "rows": [
    {
        "name": "name",
        "label": "Borough",
        "type": "ATTRIBUTE"
    },
    {
        "name": "boro_code",
        "label": "Borough Code",
        "type": "ATTRIBUTE"
    }
]

  • metrics:

    • For shape layer types, this is an array of Metric objects. These metrics must match the fields names in the data source metadata.
    1
2
3
    "metrics": [
    cf.Metric("bbl", "sum")
]
    • For shape-only layer types, this is an array of JSON objects. These metrics must match the names in the features > properties object of the GeoJSON file.
    1
2
3
4
5
6
7
    "metrics": [
    {
        "name": "shape_area",
        "label": "Shape Area",
        "type": "NUMBER"
    }
]

  • color: This is a color object (cf.Color). The color metric is the metric defined in the cf.Color() object. If not provided, it defaults to the first metric defined in the metrics array.

    Note

    When configuring drill-ins using the Interaction Manager, make sure your color ranges are dynamically calculated. Refer to Automatic color ranges and its dynamic property.

    In addition to coloring by metric, you can also color your map shapes by attribute value. Refer to the Color by Attribute Values documentation for details.

  • dataField: This applies when the layer is rendered using external data. It is a JSON representation of the field used by the shape in order to trigger valid filters.

    Take a look at the following example:

      1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
    // Define metrics
let metric1 = new cf.Metric('metric', 'sum')
.label('Metric Custom Label')
.hideFunction();

let metric2 = new cf.Metric('id', 'sum')
.label('Id Sum')
.hideFunction();

cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('zoom', 3.8000000000000003)
.set('center', [-101.35230305777141, 54.4664606400153])
.element('v1')
.execute()
.then(() => {
    // The data array structure should be 
    // like the one described here: https://chartfactor.com/doc/latest/data_format/
    const data = [
        {
            group: ['Alabama'],
            current: {
                count: 11,
                metrics: {
                    metric: {
                        sum: 636
                    },
                    id: {
                        sum: 5413
                    }
                }
            }
        },
        {
            group: ['Alaska'],
            current: {
                count: 7,
                metrics: {
                    metric: {
                        sum: 416
                    },
                    id: {
                        sum: 3128
                    }
                }
            }
        },
        {
            group: ['Arizona'],
            current: {
                count: 17,
                metrics: {
                    metric: {
                        sum: 777
                    },
                    id: {
                        sum: 7787
                    }
                }
            }
        },
        {
            group: ['Arkansas'],
            current: {
                count: 1,
                metrics: {
                    metric: {
                        sum: 17
                    },
                    id: {
                        sum: 250
                    }
                }
            }
        },
        {
            group: ['California'],
            current: {
                count: 137,
                metrics: {
                    metric: {
                        sum: 6995
                    },
                    id: {
                        sum: 69316
                    }
                }
            }
        },
        {
            group: ['Colorado'],
            current: {
                count: 29,
                metrics: {
                    metric: {
                        sum: 1349
                    },
                    id: {
                        sum: 13745
                    }
                }
            }
        },
        {
            group: ['Connecticut'],
            current: {
                count: 10,
                metrics: {
                    metric: {
                        sum: 479
                    },
                    id: {
                        sum: 5626
                    }
                }
            }
        },
        {
            group: ['District of Columbia'],
            current: {
                count: 35,
                metrics: {
                    metric: {
                        sum: 1626
                    },
                    id: {
                        sum: 17381
                    }
                }
            }
        },
        {
            group: ['Florida'],
            current: {
                count: 84,
                metrics: {
                    metric: {
                        sum: 4086
                    },
                    id: {
                        sum: 36709
                    }
                }
            }
        },
        {
            group: ['Georgia'],
            current: {
                count: 35,
                metrics: {
                    metric: {
                        sum: 1836
                    },
                    id: {
                        sum: 17439
                    }
                }
            }
        },
        {
            group: ['Hawaii'],
            current: {
                count: 6,
                metrics: {
                    metric: {
                        sum: 308
                    },
                    id: {
                        sum: 3386
                    }
                }
            }
        },
        {
            group: ['Idaho'],
            current: {
                count: 4,
                metrics: {
                    metric: {
                        sum: 205
                    },
                    id: {
                        sum: 2851
                    }
                }
            }
        },
        {
            group: ['Illinois'],
            current: {
                count: 26,
                metrics: {
                    metric: {
                        sum: 1257
                    },
                    id: {
                        sum: 12124
                    }
                }
            }
        },
        {
            group: ['Indiana'],
            current: {
                count: 15,
                metrics: {
                    metric: {
                        sum: 820
                    },
                    id: {
                        sum: 6859
                    }
                }
            }
        },
        {
            group: ['Iowa'],
            current: {
                count: 14,
                metrics: {
                    metric: {
                        sum: 708
                    },
                    id: {
                        sum: 6008
                    }
                }
            }
        },
        {
            group: ['Kansas'],
            current: {
                count: 15,
                metrics: {
                    metric: {
                        sum: 667
                    },
                    id: {
                        sum: 7500
                    }
                }
            }
        },
        {
            group: ['Kentucky'],
            current: {
                count: 9,
                metrics: {
                    metric: {
                        sum: 435
                    },
                    id: {
                        sum: 3755
                    }
                }
            }
        },
        {
            group: ['Louisiana'],
            current: {
                count: 21,
                metrics: {
                    metric: {
                        sum: 1177
                    },
                    id: {
                        sum: 11001
                    }
                }
            }
        },
        {
            group: ['Maryland'],
            current: {
                count: 9,
                metrics: {
                    metric: {
                        sum: 569
                    },
                    id: {
                        sum: 4243
                    }
                }
            }
        },
        {
            group: ['Massachusetts'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 768
                    },
                    id: {
                        sum: 3941
                    }
                }
            }
        },
        {
            group: ['Michigan'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 582
                    },
                    id: {
                        sum: 8272
                    }
                }
            }
        },
        {
            group: ['Minnesota'],
            current: {
                count: 26,
                metrics: {
                    metric: {
                        sum: 1507
                    },
                    id: {
                        sum: 12745
                    }
                }
            }
        },
        {
            group: ['Mississippi'],
            current: {
                count: 5,
                metrics: {
                    metric: {
                        sum: 269
                    },
                    id: {
                        sum: 2651
                    }
                }
            }
        },
        {
            group: ['Missouri'],
            current: {
                count: 16,
                metrics: {
                    metric: {
                        sum: 865
                    },
                    id: {
                        sum: 8566
                    }
                }
            }
        },
        {
            group: ['Nebraska'],
            current: {
                count: 11,
                metrics: {
                    metric: {
                        sum: 632
                    },
                    id: {
                        sum: 6678
                    }
                }
            }
        },
        {
            group: ['Nevada'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 457
                    },
                    id: {
                        sum: 5678
                    }
                }
            }
        },
        {
            group: ['New Hampshire'],
            current: {
                count: 1,
                metrics: {
                    metric: {
                        sum: 97
                    },
                    id: {
                        sum: 844
                    }
                }
            }
        },
        {
            group: ['New Jersey'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 668
                    },
                    id: {
                        sum: 5626
                    }
                }
            }
        },
        {
            group: ['New Mexico'],
            current: {
                count: 10,
                metrics: {
                    metric: {
                        sum: 450
                    },
                    id: {
                        sum: 4872
                    }
                }
            }
        },
        {
            group: ['New York'],
            current: {
                count: 49,
                metrics: {
                    metric: {
                        sum: 2343
                    },
                    id: {
                        sum: 25291
                    }
                }
            }
        },
        {
            group: ['North Carolina'],
            current: {
                count: 16,
                metrics: {
                    metric: {
                        sum: 988
                    },
                    id: {
                        sum: 9054
                    }
                }
            }
        },
        {
            group: ['North Dakota'],
            current: {
                count: 2,
                metrics: {
                    metric: {
                        sum: 136
                    },
                    id: {
                        sum: 918
                    }
                }
            }
        },
        {
            group: ['Ohio'],
            current: {
                count: 38,
                metrics: {
                    metric: {
                        sum: 2036
                    },
                    id: {
                        sum: 20429
                    }
                }
            }
        },
        {
            group: ['Oklahoma'],
            current: {
                count: 22,
                metrics: {
                    metric: {
                        sum: 1408
                    },
                    id: {
                        sum: 11763
                    }
                }
            }
        },
        {
            group: ['Oregon'],
            current: {
                count: 10,
                metrics: {
                    metric: {
                        sum: 540
                    },
                    id: {
                        sum: 6668
                    }
                }
            }
        },
        {
            group: ['Pennsylvania'],
            current: {
                count: 26,
                metrics: {
                    metric: {
                        sum: 1253
                    },
                    id: {
                        sum: 13150
                    }
                }
            }
        },
        {
            group: ['Rhode Island'],
            current: {
                count: 2,
                metrics: {
                    metric: {
                        sum: 14
                    },
                    id: {
                        sum: 1131
                    }
                }
            }
        },
        {
            group: ['South Carolina'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 645
                    },
                    id: {
                        sum: 5926
                    }
                }
            }
        },
        {
            group: ['South Dakota'],
            current: {
                count: 2,
                metrics: {
                    metric: {
                        sum: 73
                    },
                    id: {
                        sum: 965
                    }
                }
            }
        },
        {
            group: ['Tennessee'],
            current: {
                count: 18,
                metrics: {
                    metric: {
                        sum: 905
                    },
                    id: {
                        sum: 6209
                    }
                }
            }
        },
        {
            group: ['Texas'],
            current: {
                count: 112,
                metrics: {
                    metric: {
                        sum: 5535
                    },
                    id: {
                        sum: 57873
                    }
                }
            }
        },
        {
            group: ['Utah'],
            current: {
                count: 11,
                metrics: {
                    metric: {
                        sum: 681
                    },
                    id: {
                        sum: 6014
                    }
                }
            }
        },
        {
            group: ['Virginia'],
            current: {
                count: 33,
                metrics: {
                    metric: {
                        sum: 1489
                    },
                    id: {
                        sum: 14552
                    }
                }
            }
        },
        {
            group: ['Washington'],
            current: {
                count: 20,
                metrics: {
                    metric: {
                        sum: 1052
                    },
                    id: {
                        sum: 10573
                    }
                }
            }
        },
        {
            group: ['West Virginia'],
            current: {
                count: 12,
                metrics: {
                    metric: {
                        sum: 656
                    },
                    id: {
                        sum: 8475
                    }
                }
            }
        },
        {
            group: ['Wisconsin'],
            current: {
                count: 13,
                metrics: {
                    metric: {
                        sum: 774
                    },
                    id: {
                        sum: 7115
                    }
                }
            }
        }
    ];

    const shape = {
        type: 'shape',
        name: 'State shape',
        priority: 2,
        properties: {
            limit: 1000,
            shapes: [
                {
                    url: 'https://chartfactor.com/resources/us-states.json'
                }
            ],
            options: {
                featureProperty: 'name',
                metrics: [metric1.toJSON(), metric2.toJSON()], // Metrics should be in a JSON format
                allowClick: false,
                showLocation: false,
                shapeOpacity: 2,
                shapeOpacityHl: 1,
                shapeBorderColor: 'black',
                shapeBorderWeightHl: 4,
                color: cf.Color()
                    .palette(['#006d2c', '#2ca25f', '#66c2a4', '#b2e2e2', '#edf8fb'])
                    .metric(metric1)
                    .autoRange({ dynamic: true }),
                dataField: {
                    name: 'state',
                    label: 'State',
                    type: 'ATTRIBUTE'
                }
            }
        }
    };

    const map = cf.getVisualization('v1');

    map.get('removeLayer')(shape.name).then(() => {
        map.get('addLayer')(shape, data);
    });
});

    The previous code will render a map like the one below:

    geo-map-v2-shape-external-data

Miscellaneous options
  • fitBounds fits a map that contains geographical bounds with the maximum zoom level possible. Valid values are true and false. It is false by default.
  • animationDuration it allows you to set the duration of the animation effect when the map is fitting the bounds depending on the map's zoom and center. For example "animationDuration": 1.5 would change the animation duration to 1.5 seconds. By defult the animation duration time is 0.5 seconds.
  • opacityZoomLevels works similar to the precisionLevels property of markers, only in this case instead of setting the precision, it sets the fill opacity depending on the current zoom level.

The layer definition below shows how to use the opacityZoomLevels property:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "type": "shape",
    "name": "Realtor Monthly Inventory State 2",
    "priority": 2,
    "provider": "Aktiun Elastic",
    "source": "realtor_monthly_inventory_state_all",
    "properties": {
        "shapes": [
            {
                "url": "https://chartfactor.com/resources/us-states.json",
                "fitBounds": true,
                "featureProperty": "name",
                "name": "State Name"
            }
        ],
        "limit": 100,
        "options": {
            "rows": [
                cf.Row("state_name", "State Name")
            ],
            "featureProperty": "name",
            "metrics": [
                cf.Metric("median_days_on_market_mm", "avg")
            ],
            "color": cf.Color()
                .autoRange({ dynamic: false })
                .palette(["#fcfbfd", "#efedf5", "#dadaeb", "#bcbddc", "#9e9ac8", "#807dba", "#6a51a3", "#54278f", "#3f007d"].reverse())
                .metric(cf.Metric("median_days_on_market_mm", "avg")),
            "opacityZoomLevels": [
                {
                    "zoom": 1,
                    "fillOpacity": 0.8
                },
                {
                    "zoom": 3,
                    "fillOpacity": 0.5
                },
                {
                    "zoom": 5,
                    "fillOpacity": 0.3
                },
                {
                    "zoom": 6,
                    "fillOpacity": 0.1
                }
            ]
        }
    }
}

Note

Valid values for fillOpacity are from any value great than zero (e.g. 0.001) to 1

The above layer code would render a map with a behaviour similar to the animation below.

  • min and max defines the domain values for color range calculation. When an instance of the Color class is used as the layer color and this instance does not have a defined color range, ChartFactor calculates the color ranges of the layer data based on the color palette as scale, the min and max values as domain and on the value of the color's metric or the first defined metric if the color's metric is not defined.

    The default value of these properties will be the minimum and maximum value of the metric defined within the layer data.

    Let's take a look at the following example:

    Suppose we have a layer with the following instance of Color defined: 

    1
2
3
4
5
6
7
    cf.Color()
.palette([
    "#fcfbfd", "#efedf5", "#dadaeb",
    "#bcbddc", "#9e9ac8", "#807dba",
    "#6a51a3", "#54278f", "#3f007d"
].reverse())
.metric(cf.Metric("metric", "sum"))

    And the value of the metric inside the layer's data goes from 1 to 30:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
    [
    {
        "group": [
            "Group 1"
        ],
        "current": {
            "count": 1,
            "metrics": {
                "metric": {
                    "sum": 1
                }
            }
        }
    },
    ...
    {
        "group": [
            "Group 30"
        ],
        "current": {
            "count": 1,
            "metrics": {
                "metric": {
                    "sum": 30
                }
            }
        }
    }
]

    If we do not set a min and a max value, ChartFactor will calculate them automatically and it will use min = 1 and max = 30 and the colors for each element will be as follows:

    • When the value is:

      • 1 then the color will be #3f007d.
      • 2 then the color will be #450b82.
      • 3 then the color will be #4b1687.

      ...

      • 28 then the color will be #f5f3f9.
      • 29 then the color will be #f8f7fb.
      • 30 then the color will be #fcfbfd.

    Note that the color when it is 1 and 30 matches the first and last color of the palette after doing the reverse.

    Now suppose we manually set a min and max value of 3 and 28 respectively, then:

    When the value is 1, 2 and 3 the color will be #3f007d and fcfbfd when is 28, 29 or 30, that also match the first and last color of the palette. This happens because by limiting the domain, ChartFactory cannot calculate a color outside of that range and therefore sets those colors as the default color.

Adding shape layers

We can inject shape layers programatically after the map has been executed the first time. Let's say that we set the US map shape using either the shape or shape-only layer described above to render an initial map like the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
cf.create()
.graph("Geo Map GL")
.set("layers", [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }, {
        type: "shape",
        name: "Realtor Monthly Inventory State",
        priority: 2,
        provider: "Aktiun Elastic",
        source: "realtor_monthly_inventory_state_all",
        properties: {
            shapes: [
                {
                    url: "https://chartfactor.com/resources/us-states.json",
                    fitBounds: true,
                    featureProperty: "name",
                    name: "State Name",
                },
            ],
            limit: 100,
            options: {
                rows: [cf.Row("state_name", "State Name")],
                allowMultiSelect: false,
                shapeOpacity: 1,
                style: {
                    color: "#756bb1",
                    weight: 2,
                    opacity: 1, // Border opacity
                },
                shapeBorderWeightHl: 3,
                shapeBorderColorHl: "green",
                featureProperty: "name",
                metrics: [cf.Metric("median_days_on_market_mm", "avg")],
                color: cf
                    .Color()
                    .autoRange({ dynamic: false })
                    .palette(
                        [
                            "#fcfbfd",
                            "#efedf5",
                            "#dadaeb",
                            "#bcbddc",
                            "#9e9ac8",
                            "#807dba",
                            "#6a51a3",
                            "#54278f",
                            "#3f007d",
                        ].reverse()
                    )
                    .metric(cf.Metric("median_days_on_market_mm", "avg")),
                animationDuration: 1.5,
            },
        },
    }
])
.set("center", [-110.04435988330839, 46.73985210238146])
.set("zoom", 7)
.execute();

us-states

After the map is rendered, to add the Texas shape with county geometries, we would do the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
const map = cf.getVisualization('geo-map-div-chart');
await map.get('addLayer')({
  type: "shape",
  name: "Realtor Monthly Inventory County",
  priority: 3,
  provider: "Aktiun Elastic",
  source: "realtor_monthly_inventory_county_all",
  properties: {
    shapes: [
        {
            url: "https://chartfactor.com/resources/county/44_TX_county.json",
        },
    ],
    options: {
        rows: [cf.Row("county_name", "County Name")],
        shapeOpacity: 1,
        style: {
            color: "#00441b",
            weight: 2,
            opacity: 1, // Border opacity
        },
        featureProperty: "boundary_name",
        metrics: [cf.Metric("median_days_on_market_mm", "avg")],
        color: cf
            .Color()
            .autoRange({ dynamic: false })
            .palette(
                [
                    "#f7fcf5",
                    "#e5f5e0",
                    "#c7e9c0",
                    "#a1d99b",
                    "#74c476",
                    "#41ab5d",
                    "#238b45",
                    "#006d2c",
                    "#00441b",
                ].reverse()
            )
            .metric(cf.Metric("median_days_on_market_mm", "avg")),
        animationDuration: 1.5,
    }
  }
})

After executing the code above the state shape for Texas will be rendered over the US shape.

us-states

Note that the addLayer function returns a promise. This is because the GeoJSON file with the shape data needs to be fetched the first time.

Custom data

A shape can also be added using custom data queried using ChartFactor's Aktive query in the following way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
// Define metrics
let metric = new cf.Metric('metric', 'sum')
    .label('Metric Custom Label')
    .hideFunction();

let metric2 = new cf.Metric('id', 'sum')
    .label('Id Sum')
    .hideFunction();

let palette = ['#006d2c', '#2ca25f', '#66c2a4', '#b2e2e2', '#edf8fb'];
const shapeColor = cf.Color().palette(palette).metric(metric, metric2);

shapeColor.autoRange({ dynamic: true });

let myMap = cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('center', [-101.35230305777141, 54.4664606400153])
.set('zoom', 3.8000000000000003)
.element('v1')
.execute()
.then(() => {
    cf.provider('Akt Elastic').source('company_location')
        .limit(1000)
        .rows('state', 'name', 'id')
        .metrics(metric, metric2)
        .on('execute:stop', (event) => {

            const shape = {
                'type': 'shape',
                'name': 'State shape',
                'priority': 2,
                'properties': {
                    'limit': 1000,
                    'shapes': [{
                        url: 'https://chartfactor.com/resources/us-states.json'
                    }],
                    'options': {
                        'featureProperty': 'name',
                        'metrics': [metric.toJSON(), metric2.toJSON()],
                        'allowClick': false,
                        'showLocation': false,
                        'shapeOpacity': 2,
                        'shapeOpacityHl': 1,
                        'shapeBorderColor': 'black',
                        'shapeBorderWeightHl': 4,
                        'color': shapeColor,
                        'rows': cf.getVisualization(event.element).get().rows
                    }
                }
            };

            const map = cf.getVisualization('v1');

            map.get('removeLayer')(shape.name).then(() => {
                map.get('addLayer')(shape, event.data);
            });
        })
        .execute();
});

Note

For custom data, the metrics and rows properties must be in JSON format. That is why for the metrics we use the .toJSON() function at the end and for the rows, we obtain them from Aktive instance with the .get().rows statement, which returns the rows in JSON format.

The above code will render a map that looks like the following:

geo-map-shapes-custom-data

You can also add a shape layer with external data obtained outside ChartFactor's Aktive queries. Please refer to the Shape's data options section, specifically the dataField property, for details and example.

Marker

The marker layer supports two types of queries:

  • Geohash queries: They require location point information using the location property. You can learn more about this type of query here. The markers shown for this query represent the center of an area. The area size is determined by a precision value.

  • Raw queries: They also require location point information using the location property. In this case, each marker represents a single event. Multiple events on the same location will render multiple markers. Use the "fields": [] property to specify the attributes the marker should include in its tooltip in addition to the location point information.

Note

  • When using data engines that support geo-point data types such as Elasticsearch, location point information refers to the geo-point data type. For SQL engines such as BigQuery, location point information refers to the longitude and latitude columns.
  • The default limit for agregate and raw queries is 1000. Use the "limit": n property to change this default.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "type": "marker",
  "name": "Marker layer 1",
  "priority": 2,
  "provider": "provider-name",
  "source": "source-name",
  "properties": {               
      "limit": 100,
      "color": {},
      "clusterColor": {},
      "markerIcon": "data:image/png;base64,...",
      "clusterIcon": "data:image/png;base64,...",
      "rows": [],
      "fields": [],
      "metrics": [],
      "min": 0,
      "max": 20,
      "ignoreCoords": [],
      "showLocation": true,
      "disableMarkerEvents": false,
      "maxSpiderifyMarkers": 100,
      "geoHashMarkerClickEvent": {},
      "allowClickInRawMarker": true,
      "location": "location",
      "precision": 5,
      "precisionLevels": {
          "raw": {
              "zoom": 18,
              "fields": ["street_name", "person_name"] 
          },
          "levels": [
              {
                  "zoom": 9,
                  "precision": 4
              },
              {
                  "zoom": 12,
                  "precision": 5
              },
              {
                  "zoom": 15,
                  "precision": 6
              },
              {
                  "zoom": 17,
                  "precision": 7
              }
          ]
      },
      "legend": "right"
  }
}

For Geohash and Raw queries, the location property is required. Consider the following scenarios, illustrated using Elasticsearch:

  1. Executing a Raw query directly. In this case, you must specify the location property and the fields property with the fields that you want to show in the tooltip if they are required.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    {
    type: "marker",
    name: "My Marker layer",
    priority: 3,
    provider: "Elasticsearch",
    source: "chicago_taxi_trips",
    properties: {
        legend: "right",
        limit: 1000,
        clusterColor: colorDefinition,
        location: "dropoff_location",
        fields: ["company", "extras", "fare"]
    }
}

  2. Executing a Geohash query with a precisionLevels setting. In this case, you need to specify the precisionLevels object. Note that for the "raw" level, you can also specify the fields property with the fields to be rendered in the tooltip.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
    {
    type: "marker",
    name: "My Marker layer",
    priority: 3,
    provider: "Elasticsearch",
    source: "chicago_taxi_trips",
    properties: {
        legend: "right",
        limit: 1000,
        clusterColor: colorDefinition,
        location: "dropoff_location",
        precisionLevels: {
            raw: { zoom: 16, fields: ["company", "extras", "fare"] },
            levels: [
                {
                    zoom: 10,
                    precision: 5
                },
                {
                    zoom: 13,
                    precision: 8
                },
                {
                    zoom: 15,
                    precision: 11
                },
            ]
        }
    }
}

  3. Executing a Geohash query with a specific precision. In this case, you need to only specify the location and the precision properties.

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    {
    type: "marker",
    name: "My Marker layer",
    priority: 3,
    provider: "Elasticsearch",
    source: "chicago_taxi_trips",
    properties: {
        legend: "right",
        limit: 1000,
        clusterColor: colorDefinition,
        location: "dropoff_location",
        precision: 5
    }
}

Note

When using data engines that support geo-point data types such as Elasticsearch, to filter a field of type geo_point you need to provide the values as an array of two elements corresponding to latitude and longitude respectively. Take a look at the example below using the staticFilters property:

1
2
3
4
5
6
staticFilters: [
    cf.Filter("dropoff_location")
        .label("dropoff_location")
        .operation("NOT IN")
        .value([0, 0]),
]
Custom markers

The Geo Map uses SDF-enabled images to render markers. The article Using recolorable images in Mapbox maps explains what these types of images are, their benefits and limitations.

The markerIcon property expects a single color http resource or a base64-encoded image which you can obtain by converting an SVG image to base64 format. Once the correct value is set to this property, ChartFactor adds this image to the map with SDF enabled. Take a look at the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
//...
{
    name: "NY 311 Markers",
    priority: 2,
    type: "marker",
    provider: "BigQuery",
    source: "bigquery-public-data:new_york_311.311_service_requests",
    properties: {
        legend: "top-right",
        limit: 10000,
        color: cf.Color().palette(["#a50026", "#d73027", "#f46d43", "#fdae61", "#fee090"]).metric(cf.Metric()),
        markerIcon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/NlyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAChUlEQVR4nO2aPWgUURDHxw8EEYkWIojx8mbviNhqY5XCVIKFha2lraVtSlsrsbU8ghZiISecvtlcE8vYBCUk2ZkLimc8BAl+rLxLDEfuwt5+3e0+3w+mut1383/zv503ywE4HA7HiHhvg2kkXlSau70geT7jB7NgrVgtX5AkPBAd8xnYBhIvDhG7F1wH21Cau4cJVpq/gW3godXdDbANdILFVdgq0FlanKWtAp2lxVnaKtBZWpylrQKdpcVeS6Mv16IqbK6B0hOGR5D4vtKyEyVYEf9UxAsQhkehjFS1nFOaX0ZWdkC4vJ721y9AmUAd3EBiiSu2r9qf0JebUHTmmuFxY0vU/Dup2P3Q/EeRPLqysnICikil2Z5RWlqphQ5a/B2+2axBkVDUvoMkX7MW2/dWs+uR3Ju0Tpj1P59G4qd5CR0Mrleaa2cmItYjuapIVscndl/0mucH1wvZWzEvi4+rZ1cT9tb8hOfYszFlb82x2tn27Lkse2tekVXP9lobVaV5OV1CvK20PIusVO8a3k5Vbc3LJucx91b+ZQ4LiuShomD+365H3df70np4zDz9kfgBkjSSPBgT92yM9zv6qEiemE26ROtnk6w37J7zr9qnzKbtbh6/j5NTxoL5u6mAqYSpSBYbOMoaNdpCUz1zADH/HMhRMA+1afL1Mkgwwv6x11OaPyjNj5H4NjY6U5CSzAUfXL/RmTK5mpxN7jBpMGfBhQOdYHEVtgp0lhZnaSu42No42Zu2oo+nC+ZaKDOKglvmnD36mVw2PZK7UDZqtIVI/CLupNMXjcoSX4YS2fdHCrF7Y57smKHeTExgg30xhs3N2AlFAzMWWvizNv5vgh0OB0yCv1phdcRD/nuLAAAAAElFTkSuQmCC",
        ignoreCoords: [0, 0],
        showLocation: true,
        disableMarkerEvents: false,
        maxSpiderifyMarkers: 100,
        allowClickInRawMarker: true,
        visibilityZoomRange: [0, 24],
        location: ["longitude", "latitude"],
        precisionLevels: {
            raw: {
                zoom: 18,
                fields: [
                    "agency",
                    "street_name",
                    "complaint_type",
                    "incident_address",
                    "city",
                    "location_type"
                ]
            },
            levels: [
                { zoom: 4, precision: 3 },
                { zoom: 6, precision: 4 },
                { zoom: 9, precision: 5 },
                { zoom: 11.75, precision: 6 },
                { zoom: 14.25, precision: 7 },
                { zoom: 16, precision: 8 }
            ]
        }
    }
}
// ...

The previous code will render a Geo Map like the one below:

geo map markers

Marker events

Normally, hovering a pin pin will show the latitude and longitude information for the pin in addition to other fields specified either in the fields property or in the precision levels definition. If the marker is clicked, a filter with the latitude and longitude values will be applied. This behavior can be removed by setting disableMarkerEvents to true:

1
"disableMarkerEvents": true
Geohash clusters

Geohash clusters represent the center of areas for an aggregated geohash query result. This type of geo visualization can be extremely powerful when dealing with big data.

A Geo Map using a marker layer with a geohash query can be defined like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
cf.create()
    .graph("Geo Map GL")
    .set('layers', [
        {
            type: "tile",
            name: "Tile",
            priority: 1,
            properties: {
                source: {
                    tiles: [
                        "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                    ],
                    scheme: "xyz",
                    attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
                }
            }
        },
        {
            type: "marker",
            name: "Marker layer 1",
            priority: 3,
            provider: "BigQuery",
            source: "bigquery-public-data:new_york_311.311_service_requests",
            properties: {
                limit: 1000,
                color: cf.Color().palette([
                    "blue",
                    "#fed976",
                    "#feb24c",
                    "#fd8d3c",
                    "#fc4e2a",
                    "#e31a1c",
                    "#b10026",
                ]),
                clusterColor: cf.Color().palette([
                    "#ffffb2",
                    "#fed976",
                    "#feb24c",
                    "#fd8d3c",
                    "#fc4e2a",
                    "#e31a1c",
                    "#b10026",
                ].reverse()),
                maxSpiderifyMarkers: 100,
                disableMarkerEvents: false,
                allowClickInRawMarker: false,
                location: ["longitude", "latitude"],
                precision: 4,
                staticFilters: [
                    cf.Filter("latitude").label("latitude").operation("NOT IN").value([null])
                ],
            },
        }
    ])
    .set("center", [-73.9575251587163, 40.667325725461126])
    .set("zoom", 8.29)
    .element('chart-id')
    .execute()

The above code is aggregating the location of 311 call in the New York area. It may render something like this:

pin

When hovering one of the clusters we can see a rectangle that defines the area where this cluster is the center. Imagine using a raw query instead of using a geohash query. The amount of raw markers and clusters could potentially tear down the map since we can see there are several millions of calls.

Now let's remove the precision: 4 property and add the precisionLevels option shown below to the above marker layer before executing it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
"precisionLevels": {
    "raw": {
        "zoom": 18,
        "fields": [
            "agency",
            "street_name",
            "complaint_type",
            "incident_address",
            "city",
            "location_type"
        ]
    },
    "levels": [
        { "zoom": 4, "precision": 3 },
        { "zoom": 6, "precision": 4 },
        { "zoom": 9, "precision": 5 },
        { "zoom": 11.75, "precision": 6 },
        { "zoom": 14.25, "precision": 7 },
        { "zoom": 16, "precision": 8 }
    ]
}

The above configuration takes care of the magic: It allows to automatically trigger a new geohash query with a new level of precision every time a specific zoom level is reached by using the bounding box filter. This allows to zoom-in step by step until it hits the last zoom level represented by the raw property. This is the level the Geo Map considers safe enough to do a raw query. By default if no fields were configured for the raw level query, all fields are included and shown on the markers tooltips. Use the fields property to query only some of them:

Here is an example of a map changing the query at different precision levels:

Cluster and marker color

You can color clusters depending on their value. You can define your custom color ranges or take advantage of our automatic color ranges by simply providing a color palette. See the Color Range documentation. After defining your color instance, just set the property "color": colorInstance in your marker layer configuration. See the following example:

1
2
3
4
5
6
7
// color configuration
let color = cf.Color();
color.palette(['#fcfbfd','#efedf5','#dadaeb','#bcbddc','#9e9ac8','#807dba','#6a51a3','#54278f','#3f007d'].reverse());
color.autoRange({ dynamic: true });
//...
"color": color,
//...

The previous code will render the color of the clusters like the image below.

geo map marker icons html

Cluster and marker colors support the following properties:

  • color: applies the provided color definition to markers and clusters. For markers, it uses the first color in the palette. For clusters, it uses all colors in the palette to color individual clusters depending on their value. The color property is optional. It defaults to a standard map color definition.
  • clusterColor: applies the provided color definition to clusters, overriding the value provided in the color property if any. This property is useful when you need to provide separate color definitions for clusters and markers. For example, you may want to color clusters according to their value and markers with color blue. In this case, you would provide a color definition with a single color palette to the color property (for markers) and a color definition with a multi-color palette to the clusterColor property (for clusters). The clusterColor property is optional. It defaults to the value of the color property if provided, otherwise, to a standard map color definition.
Cluster icons

The clusterIcon setting allows you to add icons to the standard representation of geohash clusters. This is useful to distinguish what clusters belong to what datasets when rendering multiple datasets on the Geo Map. It works the same way as the markerIcon property. Take a look at the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
//...
{
    name: "NY 311 Markers",
    priority: 2,
    type: "marker",
    provider: "BigQuery",
    source: "bigquery-public-data:new_york_311.311_service_requests",
    properties: {
        legend: "top-right",
        limit: 10000,
        color: cf.Color().palette(["#a50026", "#d73027", "#f46d43", "#fdae61", "#fee090"]).metric(cf.Metric()),
        clusterIcon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/NlyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAChUlEQVR4nO2aPWgUURDHxw8EEYkWIojx8mbviNhqY5XCVIKFha2lraVtSlsrsbU8ghZiISecvtlcE8vYBCUk2ZkLimc8BAl+rLxLDEfuwt5+3e0+3w+mut1383/zv503ywE4HA7HiHhvg2kkXlSau70geT7jB7NgrVgtX5AkPBAd8xnYBhIvDhG7F1wH21Cau4cJVpq/gW3godXdDbANdILFVdgq0FlanKWtAp2lxVnaKtBZWpylrQKdpcVeS6Mv16IqbK6B0hOGR5D4vtKyEyVYEf9UxAsQhkehjFS1nFOaX0ZWdkC4vJ721y9AmUAd3EBiiSu2r9qf0JebUHTmmuFxY0vU/Dup2P3Q/EeRPLqysnICikil2Z5RWlqphQ5a/B2+2axBkVDUvoMkX7MW2/dWs+uR3Ju0Tpj1P59G4qd5CR0Mrleaa2cmItYjuapIVscndl/0mucH1wvZWzEvi4+rZ1cT9tb8hOfYszFlb82x2tn27Lkse2tekVXP9lobVaV5OV1CvK20PIusVO8a3k5Vbc3LJucx91b+ZQ4LiuShomD+365H3df70np4zDz9kfgBkjSSPBgT92yM9zv6qEiemE26ROtnk6w37J7zr9qnzKbtbh6/j5NTxoL5u6mAqYSpSBYbOMoaNdpCUz1zADH/HMhRMA+1afL1Mkgwwv6x11OaPyjNj5H4NjY6U5CSzAUfXL/RmTK5mpxN7jBpMGfBhQOdYHEVtgp0lhZnaSu42No42Zu2oo+nC+ZaKDOKglvmnD36mVw2PZK7UDZqtIVI/CLupNMXjcoSX4YS2fdHCrF7Y57smKHeTExgg30xhs3N2AlFAzMWWvizNv5vgh0OB0yCv1phdcRD/nuLAAAAAElFTkSuQmCC",
        ignoreCoords: [0, 0],
        showLocation: true,
        disableMarkerEvents: false,
        maxSpiderifyMarkers: 100,
        allowClickInRawMarker: true,
        visibilityZoomRange: [0, 24],
        location: ["longitude", "latitude"],
        precisionLevels: {
            raw: {
                zoom: 18,
                fields: [
                    "agency",
                    "street_name",
                    "complaint_type",
                    "incident_address",
                    "city",
                    "location_type"
                ]
            },
            levels: [
                { zoom: 4, precision: 3 },
                { zoom: 6, precision: 4 },
                { zoom: 9, precision: 5 },
                { zoom: 11.75, precision: 6 },
                { zoom: 14.25, precision: 7 },
                { zoom: 16, precision: 8 }
            ]
        }
    }
}
//...

The important parts to render this visualization are:

  • Define the clusterIcon property with the marker icon to render.
  • Provide the "location" field name by using the location property. In the example above, the location field name is ["longitude", "latitude"].
  • Provide the precisionLevels property.

The previous code renders a Geo Map like the one below.

geo map marker icons html

Custom tooltip

The property customTooltip allows you to provide a custom html for the tooltip, this property receives a function that will receive the data of the marker and should return the html to be displayed in the tooltip. You can see how to use it in the example below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/**
 * Function to create a custom tooltip
 * @param {Array} data - Data of the marker
 * @returns {String} - HTML to be displayed in the tooltip
 */
const myTooltip = data => {
    return `<div style="padding: 10px; border-radius: 10px;">
                <span id="test-tooltip-val">test value</span>
                <span>Company: ${data[1].value}</span>
                <span>Payment type: ${data[2].value}</span>
            </div>`;
};

let myChart = cf.create().graph("Geo Map GL")
    .set("layers", [
        {
            "name": "marker",
            "type": "marker",
            ..., // other properties
            "properties": {
                "customTooltip": myTooltip, // Custom tooltip function
                ... // other properties
            },
        },
        {
            "type": "tile",
            ...
        },
    ])
    .execute();

The data object has the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
[
  {
    "name": "dropoff_location",
    "limit": 10000,
    "is": "Field",
    "type": "GEO_POINT",
    "originName": "dropoff_location",
    "originalType": "geo_point",
    "label": "dropoff_location",
    "value": [
      "41.885075298",
      "-87.713853381"
    ]
  },
  {
    "name": "company",
    "limit": 10000,
    "is": "Field",
    "type": "ATTRIBUTE",
    "originName": "company",
    "originalType": "keyword",
    "label": "company",
    "keyword": true,
    "value": "Northwest Management LLC"
  },
  {
    "name": "payment_type",
    "limit": 10000,
    "is": "Field",
    "type": "ATTRIBUTE",
    "originName": "payment_type",
    "originalType": "keyword",
    "label": "payment_type",
    "keyword": true,
    "value": "Cash"
  },
  {
    "name": "dropoff_location.lat",
    "value": "41.885075298"
  },
  {
    "name": "dropoff_location.lon",
    "value": "-87.713853381"
  }
]

Note

The fields listed in the data array correspond to the fields listed in the fields property of the layer. To include more fields, simply specify them using this property.

Miscellaneous properties
ignoreCoords

Ignores markers when they match a specified location. Example: .set('ignoreCoords', [0, 0]). None by default. This is useful when the dataset includes invalid points as 0,0 for example.

maxSpiderifyMarkers

Allows to define the maximum number of markers that can be spiderified when clicking a cluster. It's default value is 500. This is useful when a large number of markers have the same lat/long:

1
"maxSpiderifyMarkers": 100

The above configuration will render clusters of up to 100 underlying markers using the spider effect. Beyond that, it will display a table with the list:

geoHashMarkerClickEvent

Allows to provide a function that will be executed when a geohash cluster is clicked. This function will receive an object parameter with the structure shown below:

1
2
3
4
5
6
7
8
9
  {
      "name": "geohash-marker-click",
      "data": {
          "currentZoom": 3,
          "lat": 40.386201799139656,
          "lon": -107.49540489453966,
          "point": [53.06780372335744, -108.90099832062985]
      }
  }
allowClickInRawMarker

If the marker is clicked, a filter with the latitude and longitude values will be applied. This behavior can be removed by setting allowClickInRawMarker to false.

min and max

These properties work in the same way as the min and max options described in the miscellaneous options of the shape.

Custom data

The Geo Map visualization also allows to render external data in the map by using the exposed utility addLayer.

Let's take a look at some examples:

Rendering raw markers from static data

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
    cf.create()
    .graph("Geo Map GL")
    .set('layers', [
        {
            type: "tile",
            name: "Tile",
            priority: 1,
            properties: {
                source: {
                    tiles: [
                        "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                    ],
                    scheme: "xyz",
                    attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
                }
            }
        }
    ])
    .set('zoom', 4)
    .set('center', [-86.53231371294318, 27.72243591897343])
    .element('v1')
    .execute()
    .then(() => {
        const data = [
            {
                'rn': 1,
                'name': 'Donnelly-Sporer',
                'latitude': '33.6773',
                'longitude': '-118.0051'
            },
            {
                'rn': 2,
                'name': 'Daugherty LLC',
                'latitude': '30.6143',
                'longitude': '-87.2758'
            },
            {
                'rn': 3,
                'name': 'Reinger-Lebsack',
                'latitude': '26.6654',
                'longitude': '-80.0929'
            },
            {
                'rn': 4,
                'name': 'Wehner LLC',
                'latitude': '38.9164',
                'longitude': '-76.9948'
            },
            {
                'rn': 5,
                'name': 'Kunde Group',
                'latitude': '30.4061',
                'longitude': '-87.2917'
            },
            {
                'rn': 6,
                'name': 'Jast and Sons',
                'latitude': '32.491',
                'longitude': '-84.8741'
            },
            {
                'rn': 7,
                'name': 'Corkery and Sons',
                'latitude': '41.5444',
                'longitude': '-93.6192'
            },
            {
                'rn': 8,
                'name': 'Wisoky LLC',
                'latitude': '32.8538',
                'longitude': '-117.1197'
            },
            {
                'rn': 9,
                'name': 'Heathcote, Krajcik and Lemke',
                'latitude': '36.5799',
                'longitude': '-82.5733'
            },
            {
                'rn': 10,
                'name': 'Koepp, Heathcote and Will',
                'latitude': '47.9335',
                'longitude': '-97.3944'
            }
        ];

        const marker = {
            'type': 'marker',
            'name': 'Marker',
            'priority': 2,
            'properties': {
                'fields': [
                    cf.Field('longitude', 'pickup_longitude').toJSON(),
                    cf.Field('latitude', 'pickup_latitude').toJSON(),
                    cf.Field('name', 'company').toJSON()
                ],
                'min': 0,
                'max': 20,
                'clusterColor': cf.Color().palette(['#006d2c', '#2ca25f', '#66c2a4', '#b2e2e2', '#edf8fb']).autoRange({ dynamic: false })
            }
        };

        const map = cf.getVisualization('v1');

        map.get('removeLayer')('Marker').then(() => {
            map.get('addLayer')(marker, data);
        });
    });

Rendering raw markers from a raw query

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
let metrics = [
    cf.Metric('metric', 'sum'),
    cf.Metric('count')
];

cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('zoom', 4)
.set('center', [-86.53231371294318, 27.72243591897343])
.element('v1')
.execute()
.then(() => {
    cf.provider('Akt Elastic').source('company_location')
    .limit(1000)
    .fields(
        cf.Field('longitude', 'pickup_longitude'),
        cf.Field('latitude', 'pickup_latitude'),
        cf.Field('name', 'company')
    )
    .metrics(metrics)
    .on('execute:stop', (event) => {

        const marker = {
            'type': 'marker',
            'name': 'Marker',
            'priority': 2,
            'properties': {
                'metrics': [
                  cf.Metric('metric', 'sum'),
                  cf.Metric('count')
                ],
                'fields': [
                    cf.Field('longitude', 'pickup_longitude').toJSON(),
                    cf.Field('latitude', 'pickup_latitude').toJSON(),                    
                    cf.Field('name', 'company').toJSON()
                ],
                'min': 0,
                'max': 20,
                'clusterColor': cf.Color().palette(['#006d2c', '#2ca25f', '#66c2a4', '#b2e2e2', '#edf8fb']).autoRange({ dynamic: false })
            }
        };

        const map = cf.getVisualization('v1');

        map.get('removeLayer')('Marker').then(() => {
            map.get('addLayer')(marker, event.data);
        });
    })
    .execute();
});

Rendering markers from a geohash query

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('zoom', 3.56)
.set('center', [-89.90712749238719, 35.43420815633684])
.element('v1')
.execute()
.then(() => {
    cf.provider('Akt Elastic').source('company_location')
    .location('location')
    .precision(2)
    .on('execute:stop', (event) => {
        const marker = {
            'type': 'marker',
            'name': 'Marker',
            'priority': 2,
            'properties': {
                'min': 0,
                'max': 20,
                'clusterColor': cf.Color().palette(['#006d2c', '#2ca25f', '#66c2a4', '#b2e2e2', '#edf8fb']).autoRange({ dynamic: false })
            }
        };

        const map = cf.getVisualization('v1');

        map.get('removeLayer')('Marker').then(() => {
            map.get('addLayer')(marker, event.data);
        });
    })
    .execute();
});

Note

  • For custom data, the metrics, fields and rows properties must be in JSON format. That is why for the metrics and fields we use the .toJSON() function at the end.
  • For raw and static data, each data element must contain the longitude and latitude properties to render the markers.
  • The precisionLevels property does not apply when using custom data.

The above code will render a map that looks like the following:

maplibre-markers-from-geohash-data

Heatmap

The heatmap layer allows to render data with latitude and longitude information (geohash and raw) as a heat map instead of markers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
  "type": "heatmap",
  "name": "HeapMap layer 1",
  "priority": 2,
  "provider": "provider-name",
  "source": "source-name",
  "properties": {
      "options": {
            "preprocessor": (data, featureCollection) => { /*...*/ },
            "heatmap-weight": [
                "interpolate",
                ["linear"],
                ["get", "__cf_cluster_count_percent__"],
                1,
                0.2,
                80,
                85
            ],
            "heatmap-radius": [
                "interpolate",
                ["linear"],
                ["get", "__cf_cluster_count_percent__"],
                1,
                3,
                20,
                5,
                80,
                10
            ],
            "heatmap-intensity": [
                "interpolate",
                ["linear"],
                ["zoom"],
                5,
                1,
                18,
                6
            ],
            "heatmap-color": [
                'interpolate',
                ['linear'],
                ['heatmap-density'],
                0,
                'rgba(0, 0, 255, 0)',
                0.1,
                'royalblue',
                0.3,
                'cyan',
                0.5,
                'lime',
                0.7,
                'yellow',
                1,
                'red'
            ]
            "switchToMarkersAtRaw": false
      },
      "legend": "right"
      "limit": 1000,
      "visibilityZoomRange": [10, 24],
      "location": ["longitude", "latitude"],
      "precisionLevels": {
        "raw": { "zoom": 18, "fields": ["agency"] },
        "levels": [
            { "zoom": 4, "precision": 6 },
            { "zoom": 10, "precision": 7 },
            { "zoom": 15, "precision": 11 },
        ]
      }      
  }
}

Let's see the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
cf.create()
.graph("Geo Map GL")
.set("layers", [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    },
    {
        name: "HeatMap",
        priority: 2,
        type: "heatmap",
        provider: "BigQuery",
        source: "bigquery-public-data:new_york_311.311_service_requests",
        properties: {
            "filters": [
                cf.Filter("status").label("Status").operation("NOT IN").value(["Closed"])
            ],
            limit: 10000,
            location: ["longitude", "latitude"],
            visibilityZoomRange: [10, 24],
            options: {
                "heatmap-weight": [
                    "interpolate",
                    ["linear"],
                    ["get", "__cf_cluster_count_percent__"],
                    1,
                    0.2,
                    80,
                    85
                ],
                "heatmap-radius": [
                    "interpolate",
                    ["linear"],
                    ["get", "__cf_cluster_count_percent__"],
                    1,
                    3,
                    20,
                    5,
                    80,
                    10
                ],
                "heatmap-intensity": [
                    "interpolate",
                    ["linear"],
                    ["zoom"],
                    5,
                    1,
                    18,
                    6
                ],
                switchToMarkersAtRaw: false
            },
            precisionLevels: {
                raw: { zoom: 18, fields: ["agency"] },
                levels: [
                    { zoom: 4, precision: 6 },
                    { zoom: 10, precision: 7 },
                    { zoom: 15, precision: 11 },
                ]
            }
        }
    }
])
.set("zoom", 10.917255501044915)
.set("center", [-73.9369865142919, 40.70379423447997])
.set("zoomCenterInfo", { position: "top-left" })
.set("layersControl", false)
.execute()

The code above will render a Map with a Heatmap layer like this:

maplibre-heatmap-default

The options property accepts all Heatmap paint properties described in the MapLibre heatmap layer documentation. The default values for each of these properties are the default values specified in their documentation.

Advanced settings

Two out-of-the-box properties are added internally by the Geo Map to each feature in the featureCollection, the __cf_cluster_count__ and __cf_cluster_count_percent__. The first will have the value of the count property that comes from the query, and the second is that value, but normalized so that it is represented as a percentage, that is, values that will go from 0 to 100.

As shown in the example above, the normalized value of the count is used in the heatmap-weight and heatmap-radius properties expressions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
//...
"heatmap-weight": [
    "interpolate",
    ["linear"],
    ["get", "__cf_cluster_count_percent__"],
    1,
    0.2,
    80,
    85
],
"heatmap-radius": [
    "interpolate",
    ["linear"],
    ["get", "__cf_cluster_count_percent__"],
    1,
    3,
    20,
    5,
    80,
    10
]
// ...

The preprocessor property, accepts a function with two parameters the data and the featureCollection. The data is the original data obtained from the provider query and the featureCollection is the FeatureCollection type of object in which each feature already contains the __cf_cluster_count__ and __cf_cluster_count_percent__ properties.

This function allows you to add new properties according to your preference to each feature within the featureCollection, in order to allow greater flexibility and configuration, let's see how it works:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
//...

function getClusterCounts(data) {
    return data.map(d => (d.type === 'geohash' ? d.count : 1));
}

function getNormalizeFunction(clusterCounts) {
    const minClusterCount = Math.min(...clusterCounts);
    const maxClusterCount = Math.max(...clusterCounts);

    // To avoid dividing by zero
    const normalize = (maxClusterCount - minClusterCount === 0) ?
        () => 1 :
        (value) => (value - minClusterCount) / (maxClusterCount - minClusterCount);

    return normalize;
}

"options": {
    "preprocessor": (data, featureCollection) => {
        const clusterCounts = getClusterCounts(data);
        const normalize = getNormalizeFunction(clusterCounts);
        const normalizedClusterCounts = clusterCounts.map(pc => normalize(pc));

        const rescale = (normalizedValue, newMin, newMax) => (normalizedValue * (newMax - newMin)) + newMin;
        const rescaledClusterCounts = normalizedClusterCounts.map(npc => rescale(npc, 0.01, 1));
        const rescaledClusterCountsRadius = normalizedClusterCounts.map(npc => rescale(npc, 1, 5));

        featureCollection.features.forEach((f, i) => {
            f.properties["__custom_cluster_weight__"] = rescaledClusterCounts[i];
            f.properties["__custom_cluster_radius__"] = rescaledClusterCountsRadius[i];
        });
    },
    "heatmap-weight": [
        "interpolate",
        ["linear"],
        ["get", "__custom_cluster_weight__"],
        0.01,
        0.2,
        0.8,
        85
    ],
    "heatmap-radius": [
        "interpolate",
        ["linear"],
        ["get", "__custom_cluster_radius__"],
        0.01,
        3,
        0.2,
        5,
        0.8,
        10
    ],
    "heatmap-intensity": [
        "interpolate",
        ["linear"],
        ["zoom"],
        5,
        1,
        18,
        6
    ]
}
//...

In the example above, the function takes two parameters, data and featureCollection.

  • getClusterCounts(data): This function takes an array of data points and returns an array of cluster counts. If a data point is a geohash, the cluster count is extracted from the count field. Otherwise, the cluster count is assumed to be 1.

  • getNormalizeFunction(clusterCounts): This function takes an array of cluster counts and returns a normalization function. The normalization function takes a cluster count as input and returns a value between 0 and 1 that represents the normalized cluster count. The normalization function is defined as follows: (value - minClusterCount) / (maxClusterCount - minClusterCount).

    The minClusterCount and maxClusterCount are the minimum and maximum cluster counts in the array, respectively. To avoid division by zero, the function checks if maxClusterCount - minClusterCount is equal to 0 and returns a constant function that always returns 1 in that case.

  • preprocessor(originalData, featureCollection): This function takes an array of data points and a GeoJSON feature collection, applies some preprocessing to the data, and sets custom properties on the GeoJSON features. Here's a breakdown of what it does:

    1. It calls getClusterCounts to get an array of cluster counts.
    2. It calls getNormalizeFunction to get a normalization function based on the cluster counts.
    3. It applies the normalization function to the array of cluster counts to get an array of normalized cluster counts.
    4. It defines a rescale function that takes a normalized value and rescales it to a new range (specified by newMin and newMax). This function is used to rescale the normalized cluster counts to the range 0.01 to 1 and the range 1 to 5, respectively.
    5. It applies the rescale function to the normalized cluster counts to get the rescaled cluster counts and rescaled cluster radii.
    6. It sets custom properties (__custom_cluster_weight__ and __custom_cluster_radius__) on each feature in the feature collection, using the rescaled cluster counts and radii.

The code above will render a Heatmap layer like the following:

maplibre-heatmap-preprocessor

Heatmap and precision levels

The Heatmap works together with the precisionLevels configuration (when defined), just like the code above. This allows you to have a Heatmap of higher and higher precision as users zoom into the map. See the Geohash clusters section for more details on precisionLevels.

Additionally, the Heatmap options supports the switchToMarkersAtRaw setting. This property is false by default. When true, the Heatmap automatically switches to a Markers layer when executing raw queries. This would occur when users zoom-in enough to reach the raw query point according to the precisionLevels configuration.

1
2
3
4
"options": {
    // ...
    "switchToMarkersAtRaw": true
}

The code above would render a map that will change to markers layers when the zoom level is high enough to execute a raw query. See the following animation:

Custom data

Heat Map can also be added using custom data in the following way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
let myMap = cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('zoom', 8.68)
.set('center', [-87.64195321419868, 41.82682486196157])
.element('v1')
.execute()
.then(() => {
    cf.provider('Akt Elastic')
        .source('chicago_taxi_trips')
        .limit(100)
        .location('dropoff_location')
        .precision(11)
        .on('execute:stop', event => {

            const heatMap = {
                'type': 'heatmap',
                'name': 'HeapMap layer 1',
                'priority': 1,
                'properties': {
                    'options': {                      
                    }
                }
            };

            const map = cf.getVisualization('v1');

            map.get('removeLayer')('HeapMap layer 1').then(() => {
                map.get('addLayer')(heatMap, event.data);
            });
        })
        .execute();
});

Note

  • The precisionLevels and switchToMarkersAtRaw properties do not apply when using custom data

The above code will render a map that looks like the following:

geo-map-heatmap-custom-data

Circle

With the circle layer, data can be represented through proportional circles based on the value of a metric.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  "type": "circle",
  "name": "Circle 1",
  "priority": 2,
  "provider": "provider-name",
  "source": "source-name",
  "properties": {
      "limit": 100,
      "rows": [],
      "options": {
          "name": "City",
          "color": "red",
          "metrics": [],
          "allowClick": true,
          "showLocation": true,
          "min": 0,
          "max": 10,
          "radiusScale": { "min": 1, "max": 50},
          "circle-radius": [
                "interpolate",
                ["linear"],
                ["get", "metric_sum"],
                2533,
                4,
                8116.46,
                17
          ],
          "fillOpacity": 0.5,
          "opacityZoomLevels": [
              {
                  "zoom": 1,
                  "fillOpacity": 0.1
              },
              {
                  "zoom": 6,
                  "fillOpacity": 0.8
              },
              {
                  "zoom": 10.1,
                  "fillOpacity": 0.1
              }
          ]
      },
      "legend": "right",
      "location": "location" // only needed to filter with drawControl in this layer
  }
}

The following example renders a Geo Map with proportional circles.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
cf.create()
.graph("Geo Map GL")
.set("layers", [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    },
    {
        type: "circle",
        name: "Circle 1",
        priority: 1,
        provider: "Elastic Demo",
        source: "chicago_taxi_trips",
        properties: {
            limit: 1000,
            rows: [
                cf.Row("pickup_longitude", "pickup_longitude"),
                cf.Row("pickup_latitude", "pickup_latitude"),
                cf.Row("company", "company"),
                cf.Row("dropoff_community_area_desc", "Area"),
                cf.Row("payment_type"),
                cf.Row("trip_minutes")
            ],
            options: {
                name: "Company",
                color: cf
                    .Color()
                    .palette([
                        "#ffffb2",
                        "#fed976",
                        "#feb24c",
                        "#fd8d3c",
                        "#fc4e2a",
                        "#e31a1c",
                        "#b10026",
                    ].reverse())
                    .autoRange({ dynamic: true })
                    .match({
                        "Taxi Affiliation Services": "black",
                        null: "green",
                    }),
                metrics: [cf.Metric("trip_total", "sum"), cf.Metric("count")]                
            },
        },
    },
])
.set("center", [-87.60348000847188, 41.83234362220446])
.set("zoom", 11.16)
.execute();

The requirements to render this visualization are:

  • Define at least one metric. In the example above, we define two metrics.
  • Provide the at least three attributes to group by using the rows property. The first two rows should be the longitude and latitude respectively.

Note

Although the location property is not required to render circle layers, it is needed for drawing filters to work (see the drawControl section). Otherwise, these type of filters will be ignored. The expected value of this property is the name of field of type geo_point for Elasticsearch.

The previous code renders a Geo Map like the one below.

maplibre proportional circles

Options
  • name An string that represents the label of the main field defined after the latitude and longitude fields that will be use to show in the circles tooltips.
  • showLocation Toggles the visibility of the "Position" in the tooltip. Go to the Custom Configuration for Maps section to see how it works.
  • allowClick True by default. Enables or disables the ability to trigger a filter when clicking a circle.
  • color An string or a cf.Color() object that specify the circles color.
  • metrics An array of metric objects. The first metric will be used to calculate the circles radius. All metrics will be rendered in the circles tooltip.
  • rows An array of row objects. It works just like the rows property specified in Shapes Data Options section.
  • fillOpacity Applies opacity to the area of the circle but not the perimeter. 0 is completely transparent and 1 is completely opaque. Valid values for fillOpacity are from any value great than zero (e.g. 0.001) to 1
  • opacityZoomLevels see the miscellaneous options of the shape. When specified, this option takes precedence over fillOpacity.
  • min and max these properties work in the same way as the min and max options described in the miscellaneous options of the shape.

  • radiusScale An object with two properties, min and max which default values are 1 and 50 respectively. Allows to scale the radius of the circles in pixels, where the domain will be the minimum and maximum value of the first defined metric. The smallest circle will have a radius equal to the minimum value you enter, while the largest circle will have a radius equal to the maximum value you enter. The scaled value of each feature within the circle's Geojson will be stored in the __cf_radius__ property. The example below ilustrate how it works:

      1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
    // Given the following dataset
let data = [
    {
        "group": [
            "-122.751",
            "43.61872",
            "Company 1"
        ],
        "current": {
            "count": 12,
            "metrics": {
                "metric": {
                    "sum": 4982.85
                }
            }
        }
    },
    {
        "group": [
            "-122.77025",
            "42.15829",
            "Company 2"
        ],
        "current": {
            "count": 12,
            "metrics": {
                "metric": {
                    "sum": 7123.01
                }
            }
        }
    },
    {
        "group": [
            "-122.82302",
            "45.51525",
            "Company 3"
        ],
        "current": {
            "count": 5,
            "metrics": {
                "metric": {
                    "sum": 2568.84
                }
            }
        }
    },
    {
        "group": [
            "-123.09535",
            "42.41837",
            "Company 4"
        ],
        "current": {
            "count": 14,
            "metrics": {
                "metric": {
                    "sum": 6686.0199999999995
                }
            }
        }
    },
    {
        "group": [
            "-123.20298",
            "42.88061",
            "Company 5"
        ],
        "current": {
            "count": 12,
            "metrics": {
                "metric": {
                    "sum": 6129.0599999999995
                }
            }
        }
    },
    {
        "group": [
            "-123.32726",
            "42.28551",
            "Company 6"
        ],
        "current": {
            "count": 5,
            "metrics": {
                "metric": {
                    "sum": 2533.5099999999998
                }
            }
        }
    },
    {
        "group": [
            "-123.45647",
            "42.21149",
            "Company 7"
        ],
        "current": {
            "count": 12,
            "metrics": {
                "metric": {
                    "sum": 6358.74
                }
            }
        }
    },
    {
        "group": [
            "-123.80491",
            "42.78412",
            "Company 8"
        ],
        "current": {
            "count": 11,
            "metrics": {
                "metric": {
                    "sum": 5599.09
                }
            }
        }
    },
    {
        "group": [
            "-123.94363",
            "42.76188",
            "Company 9"
        ],
        "current": {
            "count": 17,
            "metrics": {
                "metric": {
                    "sum": 8116.46
                }
            }
        }
    }
];

// A circle configuration like this
"options": {
    //...
    "metrics": [cf.Metric('metric', 'sum')],
    "radiusScale": { min: 4, max: 17 }
    //...
}

    The scale domain will be first metric's minimum and maximum values: 2533.5099999999998 and 8116.46. The pixel-scaled value of each feature will be as follows:

    1
    [9.703332467602255, 14.686733716046176, 4.082266543673149, 13.669194601420394, 12.372303173053671, 4, 12.907117205061839, 11.13825844759491, 17]

  • circle-radius Sets the circle's radius as specified in the MapLibre documentation. Defaults to this expression: ['get', '__cf_radius__']. Let's dig into this:

    First, we need to know that the metric values will be stored in the circle's Geojson as a feature property as follows: 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    "options": {
    //...
    "metrics": [cf.Metric('metric', 'sum'), cf.Metric()]
    //...
}

// Feature properties
"properties": {
    "count": 12,
    "metric_sum": 4982.85
}

    Note

    If a function is defined for the metric, then the property name will be in the format of {metric.name}_{metric.func}. Otherwise, the property name will simply be {metric.func}.

    Now, we can set the circle-radius property by using a custom MapLibre expression as follows: 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    "options": {
    //...
    "circle-radius": [
        "interpolate",
        ["linear"],
        ["get", "metric_sum"],
        2533,
        4,
        8116.46,
        17
    ]
    //...
}

  • preprocessor this option works in the same way as the preprocessor option described in the Aadvanced settings of the Heatmap.

Custom data

Circles can also be added using custom data in the following way:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
let myMap = cf.create()
.graph("Geo Map GL")
.set('layers', [
    {
        type: "tile",
        name: "Tile",
        priority: 1,
        properties: {
            source: {
                tiles: [
                    "https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL",
                ],
                scheme: "xyz",
                attribution: "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>",
            }
        }
    }
])
.set('center', [-87.64909744262697, 41.83158391539821])
.set('zoom', 12)
.element('v1')
.execute()
.then(() => {
    let filter = cf
    .Filter('company')
    .label('company')
    .operation('IN')
    .value(['Taxi Affiliation Services']);

    cf.provider('Akt Elastic')
    .source('chicago_taxi_trips')
    .limit(500)
    .rows(
        cf.Row('pickup_longitude', 'pickup_longitude'),
        cf.Row('pickup_latitude', 'pickup_latitude'),
        cf.Row('company', 'company'),
        cf.Row('dropoff_community_area_desc', 'Area'),
        cf.Row('payment_type'),
        cf.Row('trip_minutes')
    )
    .filters([filter])
    .metrics(cf.Metric().label('Count'))
    .on('execute:stop', event => {

        const circle = {
            'type': 'circle',
            'name': 'Circle 1',
            'priority': 1,
            'properties': {
                'filters': [cf.Filter('company').label('company').operation('IN').value(['Taxi Affiliation Services'])],
                'limit': 500,
                'rows': cf.getVisualization(event.element).get().rows,
                'options': {
                    'name': 'Company',
                    'color': 'red',
                    'metrics': [cf.Metric().label('Count').toJSON()]
                }
            }
        };

        const map = cf.getVisualization('v1');

        map.get('removeLayer')('Circle 1').then(() => {
            map.get('addLayer')(circle, event.data);
        });
    })
    .execute();
});

Note

For custom data, the metrics and rows properties must be in JSON format. That is why for the metrics we use the .toJSON() function at the end and for the rows, we obtain them from Aktive instance with the .get().rows statement, which returns the rows in JSON format.

The above code will render a map that looks like the following:

geo-map-circles-custom-data

3d

Warning

The 3d layer is an experimental feature. Its documentation and configuration properties may change within minor and major releases.

The 3d layer allows you to render 3D models in gltf format on the map using the THREE.js library.

THREE.js initialization

The version of THREE.js used in this layer is 0.147.0 and it is loaded from the following CDN:

Variable Default Url
threeJsUrl https://unpkg.com/three@0.147.0/build/three.min.js
gltfLoaderUrl https://unpkg.com/three@0.147.0/examples/js/loaders/GLTFLoader.js
css2DRendererUrl https://unpkg.com/three@0.147.0/examples/js/renderers/CSS2DRenderer.js

You can update these resources in two ways:

Option 1: Specify the resources in your HTML tags, like this:

1
2
3
    <script src="https://unpkg.com/three@0.147.0/build/three.min.js"></script>
    <script src="https://unpkg.com/three@0.147.0/examples/js/loaders/GLTFLoader.js"></script>
    <script src="https://unpkg.com/three@0.147.0/examples/js/renderers/CSS2DRenderer.js"></script>

Option 2: Define the global variables specified in the table above to inject the location of the THREE.js dependencies:

1
2
3
4
5
6
    <script>
        window.threeJsUrl = 'https://unpkg.com/three@0.147.0/build/three.min.js';
        window.gltfLoaderUrl = 'https://unpkg.com/three@0.147.0/examples/js/loaders/GLTFLoader.js';
        window.css2DRendererUrl = 'https://unpkg.com/three@0.147.0/examples/js/renderers/CSS2DRenderer.js';
    </script>
    <script src="../../lib/CFToolkit.min.js"></script>

This layer supports two types of queries to obtain data:

  • Simple multigroup queries: Use this query type when you need to render aggregate data. With this query type, you need to specify the lon and lat fields as the first two fields in the query. The third field is the one that shows in the tooltip header. Example:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "name": "3d models",
    "priority": 2,
    "type": "3d", // layer type
    "provider": "My provider",
    "source": "source_example",
    "model": {...}, // the 3d models configuration
    "properties": {
        "visibilityZoomRange": [14, 24], // specifies the zoom range where the layer will be visible
        "limit": 10000,
        "location": "company_location", // Needed for bounding box queries. For elasticsearch this is a geo_point field and for other providers it is an array with the longitude and latitude fields
        "Rows": [
            cf.Row("company_longitude"), // longitude must be specified in order to group the data
            cf.Row("company_latitude"), // latitude must be specified in order to group the data
            cf.Row("company_name") // this field, the third in th list, will be used as the tooltip header
        ],
        "options": {
            "metrics": [cf.Metric("company_value", "sum")], // the metrics will be used to group the data using the specified operation 
            "name": "Company", // tooltip header name
            "showLocation": true
        }
    }
}
  • Detail queries: Use this query type when you need to render raw data, not aggregated by any field. With this query type, you need to specify a location property which is a geo_point field for Elasticsearch or an array of longitude and latitude fields for SQL providers. Example:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "name": "3d models",
    "priority": 2,
    "type": "3d", // Layer type
    "provider": "My provider",
    "source": "source_example",
    "model": {...}, // the 3d models configuration
    "properties": {
        "visibilityZoomRange": [14, 24], // Specify the zoom range where the layer will be visible
        "limit": 10000,
        "location": "company_location", // The location of the model, for elasticsearch is a geo_point field and for other providers is an array with the longitude and latitude fields
        "fields": [
            cf.Field("company_name"), // the first field will be used as the tooltip header
            cf.Field("company_value")
        ],
        "options": {
            "name": "Company", // tooltip header name
            "showLocation": true
        }
    }
}

The configuration of the 3D model is specified using the model property as shown in the example bellow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
    "name": "3d models",
    "priority": 2,
    "type": "3d", // Layer type
    "provider": "My provider",
    "source": "source_example",
    "model": {
        "clusterLabel": { // the cluster label configuration
            "color": "white", // text color
            "textBorderColor": "blue", // text border color
            "label": "Cells" // text label
        },
        "light": {
            "intensity": 0.7, // intensity of the light
            "color": "#2196f3" // a blue light
        },
        "rotation": {
            "x": 0,
            "y": cf.Fields("company_orientation"), // the orientation of the model
            "z": 0
        },
        "scale": data => {
            const companyEmployees = data.fields.find(m => m.name === "company_employee_count");
            const employees = companyEmployees ? companyEmployees.value : 0;

            return employees > 3000 ? 25: 5; // 25 times bigger if the company has more than 3000 employees
        },
        "gltfUrl": "https://myserver.com/gltf/default_company.gltf", // defualt gltf url
        "urlBuilder": data => {
            const companyEmployees = data.fields.find(m => m.name === "company_employee_count");
            const employees = companyEmployees ? companyEmployees.value : 0;

            return `https://myserver.com/gltf/${employees > 3000 ? "big_company" : "small_company"}.gltf`;
        }
    },
    "properties": {
        "tooltip": { // custom tooltip configuration
            content: data => { // callback that returns the tooltip html content
                return `this is a ${data["radio"]} antenna`;
            },
            color: data => { // callback that returns the tooltip color
                const colorConf = colorMatch[data["radio"]];
                return colorConf ? colorConf.backgroundColor : null;
            }
        },
        "tooltipTable": { // customizaion of the tooltip table cells
            "fields": ["radio"], // fields that will be customized
            "format": function(field, value) {// callback returns the cell configuration
                const formatConfig = colorMatch[value];
                return {
                    value: value, // the cell value
                    style: { // the cell style
                        "background-color": formatConfig.backgroundColor,
                        "color": formatConfig.color,
                        "padding-left": "5px"
                    }
                };
            }
        },...
    }
}
3D Layer specific properties
tooltip

Allows to customize the tooltip content and border color. The configuration is a JSON structure with the following properties:

  • content: Specifies a callback that returns the tooltip html content
  • color: Specifies a callback that returns the tooltip border color

The callback data parameter is in both cases the data object with the value of each field for the item selected.

tooltipTable

Allows to customize the tooltip table that renders when users select a clustered 3D object. A clustered 3D object represents more than one item in the same location. The tooltipTable configuration is a JSON structure with the following properties:

  • fields: Specifies the fields that will be customized in the tooltip table
  • format: Returns the cell configuration. The callback parameter is the field and value of the cell and the syntax of the callback is: (field, value) => { return {....}}. The configuration should return a JSON with the following properties:
    • value: Specifies the new cell value
    • style: Specifies the cell style in css format
Model properties

The model key contains configurations for the 3D model as described below.

clusterLabel

Allows to configure the label that informs users of how many items exist in a clustered 3D object. A clustered 3D object represents more than one item in the same location. The configuratin is a JSON structure with the following properties:

  • color: Specifies the color of the label. The default value is #ffffff (white).
  • textBorderColor: Specifies the color of the label border. The default value is #000000 (black).
  • label: Specifies the label text. It defaults to the count label specified in the metadata definition for this source. If the metadata count label is not defined, the label then defaults to Items.
light

Represents the light settings for the model. You can also specify a callback that returns the following structure:

  • intensity: Specifies the intensity of the light, default value is 1
  • color: Specifies the color of the light, the default value is #ffffff (white)
rotation

Specifies the rotation of the model. The rotation value could be a fixed number, a metric (example: cf.Metric("value", "sum")) or a field (example: cf.Field("rotation")). If you specify a metric or a field, the rotation value will be taken from the data. You can also specify a callback that returns the next structure.

  • x: Specifies the rotation value around the x-axis, default value: 0 (no rotation)
  • y: Specifies the rotation value around the y-axis, default value: 0 (no rotation)
  • z: Specifies the rotation value around the z-axis, default value: 0 (no rotation)
  • format: Specifies the format of the rotation values, supported values are degrees and radians, default value is degrees
scale

Represents the scale of the model. Its default value is 1, example: scale: 3 (the model will be 3 times bigger). You can also specify a callback that returns a number.

gltfUrl

Specifies the URL to the glTF model file. This is a mandatory property.

urlBuilder

Defines a function that builds the URL for the glTF model file based on the provided data. If the function returns a null, empty string or if the item is a cluster of items, then the gltfUrl property will be used instead.

Callback definition

As shown in the previous section, some model properties allow you to specify a callback that returns the needed configuration. This callback is called every time the data is updated. The parameter of this callback is an object that contains the following properties:

  • fields: In the case of a Detail query, this property contains the fields names and values. Otherwise it is an empty array.
  • rows: In the case of a Simple multigroup query, this property contains the row names and values, otherwise it is an empty array.
  • metrics: If metrics are specified in the query, this property contains the metrics names and values. Otherwise it is an empty array.

Callback example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
"model": {
    "scale": data => {
        const sizeMetric = data.metrics.find(metric => metric.name === 'Size');
        const size = sizeMetric ? sizeMetric.value : 1;

        if (size < 10) {
            return 20;
        }  else {
            return 1;
        }
    }
}

Listening To Custom Map Events

ChartFactor Toolkit Maps have special events to which you can subscribe to obtain current zoom information or the position where the map is located, here are some examples.

1
2
3
4
5
6
7
    myChart.on('mapzoom', (e)=>{
        console.log("Current map zoom: ", e.data);
    });

    myChart.on('mapmove', (e)=>{
        console.log("Current map center: ", e.data);
    });

As specified in the events documentation, you can also subscribe to click events in the Geo Map. The click event is dispatched as soon as users click on a specific layer, be it a marker, a proportional circle, a shape or any other type of layer. See the following example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
  const handleMapClick = (e) => { 
      // Get the current map visualization
      const map = cf.getVisualization(e.chart);
      // Get the clicked data
      const data = e.data;
      // Some other logic...
  }

  const map = cf.getVisualization(mapId);
  map.on('click', (e) => handleMapClick(e));

The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • chart: the current visualization id
  • data: the current zoom value when the event is mapzoom, the current map center when is mapmove and an object with the layer internal information when it is a click event
  • nativeData: the whole MapLibre native information corresponding to the specific type of layer

Layers events

The events associated with the layers are the following:

geo:layer-added

This event is fired when a new layer is added to the map. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id
  • layer: the new added layer object
  • mapLibreLayers: an array of MapLibre layers corresponding to the specific type of layer

geo:layer-removed

This event is fired when a layer is removed from the map. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id
  • layer: the removed layer object

geo:layer-changed

This event is fired when the Layers Control changes the visible property of a layer. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id
  • layer: the changed layer object

geo:layers-priority-changed

This event is fired when the Layers Control has finished changing the priority property of all layers.

  • name: the current event name
  • element: the current visualization id
  • layers: all defined layers with the priority property updated

geo:layers-execution-start

This event is fired when any of the Aktive instances associated with a data layer starts an execution. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id

geo:layers-execution-stop

This event is fired when all Aktive instances associated with a data layer stops the execution. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id

geo:layers-control-changed

This event is fired when the Layers Control expand/collapse button is pressed. The callback function receives the e object as a parameter with the following properties:

  • name: the current event name
  • element: the current visualization id
  • layersControl the layers control configuration object

Available utilities

The are several functions that can be used to implement most custom scenarios:

async addLayer(layerObj, data=undefined)

Adds an specific layer to the current map.

The layer object can be any of the available layer types.

async updateLayer(layerObj)

Updates an existing layer. This function is intended to update layer properties and options without having to re-query data.

Similar to the addLayer() function, the layer object parameter can be any of the available layer types. Just take the layer you want to edit from the defined layers, then modify the necessary properties and call the updateLayer() function providing the updated object.

Usages:

  • Tile 
1
2
3
4
5
6
7
const map = win.cf.getVisualization('visualization-id');

// Tile
const tileLayer = map.get('getDefinedLayer')('My Tile layer');

tileLayer.properties.tiles = 'https://api.maptiler.com/maps/openstreetmap/{z}/{x}/{y}.jpg?key=get_your_own_OpIi9ZULNHzrESv6T2vL';
await map.get('updateLayer')(tileLayer);
  • Shape
1
2
3
4
5
// Shape
const shapeLayer = map.get('getDefinedLayer')('My Shape layer');

shapeLayer.properties.shapes[0].url = 'https://chartfactor.com/resources/us-states/MT-30-montana-counties.geo.json';
await map.get('updateLayer')(shapeLayer);
  • Marker
1
2
3
4
5
// Markers
const markerLayer = markersMap.get('getDefinedLayer')('My Marker layer');

markerLayer.properties.markerIcon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/NlyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAChUlEQVR4nO2aPWgUURDHxw8EEYkWIojx8mbviNhqY5XCVIKFha2lraVtSlsrsbU8ghZiISecvtlcE8vYBCUk2ZkLimc8BAl+rLxLDEfuwt5+3e0+3w+mut1383/zv503ywE4HA7HiHhvg2kkXlSau70geT7jB7NgrVgtX5AkPBAd8xnYBhIvDhG7F1wH21Cau4cJVpq/gW3godXdDbANdILFVdgq0FlanKWtAp2lxVnaKtBZWpylrQKdpcVeS6Mv16IqbK6B0hOGR5D4vtKyEyVYEf9UxAsQhkehjFS1nFOaX0ZWdkC4vJ721y9AmUAd3EBiiSu2r9qf0JebUHTmmuFxY0vU/Dup2P3Q/EeRPLqysnICikil2Z5RWlqphQ5a/B2+2axBkVDUvoMkX7MW2/dWs+uR3Ju0Tpj1P59G4qd5CR0Mrleaa2cmItYjuapIVscndl/0mucH1wvZWzEvi4+rZ1cT9tb8hOfYszFlb82x2tn27Lkse2tekVXP9lobVaV5OV1CvK20PIusVO8a3k5Vbc3LJucx91b+ZQ4LiuShomD+365H3df70np4zDz9kfgBkjSSPBgT92yM9zv6qEiemE26ROtnk6w37J7zr9qnzKbtbh6/j5NTxoL5u6mAqYSpSBYbOMoaNdpCUz1zADH/HMhRMA+1afL1Mkgwwv6x11OaPyjNj5H4NjY6U5CSzAUfXL/RmTK5mpxN7jBpMGfBhQOdYHEVtgp0lhZnaSu42No42Zu2oo+nC+ZaKDOKglvmnD36mVw2PZK7UDZqtIVI/CLupNMXjcoSX4YS2fdHCrF7Y57smKHeTExgg30xhs3N2AlFAzMWWvizNv5vgh0OB0yCv1phdcRD/nuLAAAAAElFTkSuQmCC";
await map.get('updateLayer')(markerLayer);
  • Circle
1
2
3
4
5
// Circles
const circleLayer = circlesMap.get('getDefinedLayer')('My Circle layer');

circleLayer.properties.options.name = 'My custom label';
await map.get('updateLayer')(circleLayer);
  • Heat Map
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Heat Map
const heatmapLayer = heatmapMap.get('getDefinedLayer')('My HeatMap layer');
const heatmapIntensity = [
    "interpolate",
    ["linear"],
    ["zoom"],
    5,
    1,
    18,
    3
];

heatmapLayer.properties.options["heatmap-intensity"] = heatmapIntensity;
await map.get('updateLayer')(heatmapLayer);
  • Fixed Marker
1
2
3
4
5
6
7
8
// Fixed Marker
const fixedMarkerLayer = fixedMarkerMap.get('getDefinedLayer')('My Fixed Marker layer');

fixedMarkerLayer.properties.lngLat = [-89.69403786674964, 41.40153558289848];
fixedMarkerLayer.properties.label = '<div style="color: blue; font-size: 20px">My custom fixed pin tooltip message</div>';
fixedMarkerLayer.properties.icon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/NlyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAChUlEQVR4nO2aPWgUURDHxw8EEYkWIojx8mbviNhqY5XCVIKFha2lraVtSlsrsbU8ghZiISecvtlcE8vYBCUk2ZkLimc8BAl+rLxLDEfuwt5+3e0+3w+mut1383/zv503ywE4HA7HiHhvg2kkXlSau70geT7jB7NgrVgtX5AkPBAd8xnYBhIvDhG7F1wH21Cau4cJVpq/gW3godXdDbANdILFVdgq0FlanKWtAp2lxVnaKtBZWpylrQKdpcVeS6Mv16IqbK6B0hOGR5D4vtKyEyVYEf9UxAsQhkehjFS1nFOaX0ZWdkC4vJ721y9AmUAd3EBiiSu2r9qf0JebUHTmmuFxY0vU/Dup2P3Q/EeRPLqysnICikil2Z5RWlqphQ5a/B2+2axBkVDUvoMkX7MW2/dWs+uR3Ju0Tpj1P59G4qd5CR0Mrleaa2cmItYjuapIVscndl/0mucH1wvZWzEvi4+rZ1cT9tb8hOfYszFlb82x2tn27Lkse2tekVXP9lobVaV5OV1CvK20PIusVO8a3k5Vbc3LJucx91b+ZQ4LiuShomD+365H3df70np4zDz9kfgBkjSSPBgT92yM9zv6qEiemE26ROtnk6w37J7zr9qnzKbtbh6/j5NTxoL5u6mAqYSpSBYbOMoaNdpCUz1zADH/HMhRMA+1afL1Mkgwwv6x11OaPyjNj5H4NjY6U5CSzAUfXL/RmTK5mpxN7jBpMGfBhQOdYHEVtgp0lhZnaSu42No42Zu2oo+nC+ZaKDOKglvmnD36mVw2PZK7UDZqtIVI/CLupNMXjcoSX4YS2fdHCrF7Y57smKHeTExgg30xhs3N2AlFAzMWWvizNv5vgh0OB0yCv1phdcRD/nuLAAAAAElFTkSuQmCC";
fixedMarkerLayer.properties.color = 'blue';
await map.get('updateLayer')(fixedMarkerLayer);

Note

To change the query configuration of the layer, you need to remove and re-add the layer.

async removeLayer(layerName)

Removes the layer specified by the layerName parameter from the Geo Map.

changeGeoHashPrecisionLevel(aktive, zoomLevel)

Changes the precision level of an existing query object (aktive parameter) by triggering a new query using a bounding box filter at the zoom level specified by the zoom parameter. The aktive parameter must have a precisionLevels configured.

changeMapBoundariesFilter(aktive, eventNativeData)

This function performs a new query with a new bounding box. It is meant to be used within a callback subscribed to the mapmove event. You should pass the aktive query object to query the data and the nativeData property of the mapmove event. The function will trigger a query using the new boundaries of the map's viewport when the user is panning the map. Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
const map = cf.getVisualization(mapId);

const handleMapMove = (e) => {    
    const layers = map.get('getAllDefinedLayers')();

    layers.forEach((layer) => {                
        const aktiveQuery = cf.getVisualization(layer.id);

        if (aktiveQuery) {
            if (
                map.get('isGeoHashData')(aktiveQuery) ||
                map.get('isRawData')(aktiveQuery)
            ) {
                map.get('changeMapBoundariesFilter')(aktiveQuery, e.nativeData);
            }
        }
    });
};

map.on('mapmove', (e) => handleMapMove(e));

getAllDefinedLayers()

Returns all defined layers.

getDefinedLayer(layerName)

Returns the json representation of the layer that matches the layerName parameter.

getGeoHashPrecisionByZoomLevel(levels, zoom)

Given the precisionLevels' levels array (ie: precisionLevels.levels) passed as the first parameter, it returns the geohash precision that matches the zoom parameter.

getFullScreenControl()

It returns the current FullScreenControl instance.

getHighestLayerPriority()

Returns the highest priority number assigned to layers.

getLayerPaneId(layerName)

Returns the sanitized layer pane id given the layer name as a parameter. The layer pane id is used to identify the layer container in the map.

getLayerPriority(layerName)

Returns the priority of the layer that match with layerName parameter.

getNavigationControl()

It returns the current NavigationControl instance.

getOpacityByZoomLevel(levels, zoom)

Given the opacity levels array passed as the first parameter, it returns the opacity value that matches the zoom parameter.

getZoomCenterInfoControl()

It returns the current ZoomCenterInfoControl instance.

isAggregatedData(aktive)

It returns true when this query configuration is not a GeoHash and it is not a Raw query

isGeoHashData(aktive)

It returns true when this query configuration includes the precision property or when the data includes geohash information

isLayerDefined(layerName)

Checks if the given layer exists in the current layers configuration by comparing the layerName parameter.

isRawData(aktive)

It returns true when this query configuration is not a GeoHash query and it includes fields or when the data includes lat/long information

processGeohashData(data)

It processes the array of data where each element is an object with two properties: geohash and count. Given the following array with one element:

1
2
3
4
let data = [{
    "geohash": "dr72xk1",
    "count": 67217
}]

The function will return:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[{
    "originalGeohash": "dr72xk1",
    "latitude": 40.89179992675781,
    "longitude": -73.85902404785156,
    "ne": {
        "lat": 40.892486572265625,
        "lon": -73.85833740234375
    },
    "sw": {
        "lat": 40.89111328125,
        "lon": -73.85971069335938
    },
    "type": "geohash",
    "count": 67217
}]

renderLegend()

This function renders the legend for the current map. It is useful when you want to refresh the legend after changing the layers priority or visibility manually.

renderLayersControl()

This function renders the layers control for the current map and, if it exists, then updates it. It is useful when you want to refresh the layers control after changing the layers priority or visibility manually.

reorganizeLayers()

Reorganizes the layers after changing their priority

validCoords(lat, lon)

It returns true when the following conditions are met: lat >= -90 && lat <= 90 && lon >= -180 && lon <= 180