SDK Docs
Support

Map Configuration

Suggest Edits

At the top level, a Studio map configuration object contains a version string and an object with map state, map style and visualization state.

📘

Note:

The map configuration does not contain the actual data in the map, just configuration information for the visual and interactive aspects of the map. Rendering of a map typically requires both a map configuration and one or more associated datasets.

Configuration Parameters

FieldTypeDescription
versionstringVersion string, for future format changes. Currently must always be the string 'v1'.
configobjectMap configuration data.
config.mapStateMapStateCurrent view state of the map (location, zoom, tilt etc), various view settings and optionally globe parameters.
config.mapStyleMapStyleBase map style and configuration.
config.visStateVisStateDetailed visualization and interaction configurations, including the map's visualization layers.

Map State

The map state contains the current view of the map (location, zoom, tilt) as well as the various view (2D, 3D, Globe, split screen etc) and base map settings.

The config.mapState object can have the following fields:

FieldTypeDescription
latitudenumberLatitude of map center.
longitudenumberLongitude of map center.
zoomnumberCurrent zoom of the map.
bearingnumberMap up direction. 0 = north.
pitchnumberAngle of view, 0 = look from above.
dragRotatebooleanEnables user to tilt and rotate map.
isSplitbooleanWhether map is split.
mapViewMode'MODE_GLOBE', ...2D, 3D or globe.
mapSplitMode'SINGLE_MAP', ...Single, Split, Swipe-to-compare.
globe?objectGlobe mode configuration.
globe.enabledbooleanEnable globe mode.
globe.configobjectGlobe parameters.
globe.config.atmosphereboolean
globe.config.azimuthbooleanEnable azimuth.
globe.config.azimuthAnglenumberAngle of azimuth.
globe.config.basemapbooleanWhether to render a basemap on the globe.
globe.config.labelsbooleanWhether to render basemap labels on the globe.
globe.config.terminatorbooleanWhether to show a terminator (night shadow) on the globe.
globe.config.terminatorOpacitynumberOpacity of the night shadow.

Map Styles

The map state contains the current view of the map (location, zoom, tilt) as well as the various view (2D, 3D, Globe, split screen etc) and base map settings.

SettingTypeDescription
styleType'dark', 'light', ...Base map style.
mapStyles{[styleName: string]: CustomMapStyle}Map of custom map styles.
visibileLayerGroups{[layerName: string]: boolean}Indicating which base map layers are visible.
topLayerGroups{[layerName: string]: boolean}Which base map layers should be shown on top of the Studio layers.
threeDBuildingColor[number, number, number]RGB color.

Custom map styles can be added:

SettingTypeDescription
mapStyles[stylename].urlstring
mapStyles[stylename].accessTokenstringMapbox access token
mapStyles[stylename].customboolean
mapStyles[stylename].iconboolean
mapStyles[stylename].iconstring
mapStyles[stylename].idstring
mapStyles[stylename].labelstring

Fields are described as follows:

SettingTypeDescription
namestringname of the field
typestring
formatstring
analyzerTypestring

Visualization State

The visualization state contains the configuration of the map visualization, which includes:

  • Layers (Note: documented on a separate page )
  • Filters
  • Joins
  • Metrics
  • Interaction settings
  • General visualization settings

The following fields can be added to config.visState:

SettingTypeDescription
config.visState.layersarrayConfiguration of layers
config.visState.filtersarrayConfiguration of filters
config.visState.interactionConfigobjectConfiguration of interactive elements, see below
config.visState.layerBlendingadditive, ...How layers are blended visually
config.visState.splitMapsarrayArray describing the configuration of each map when using split maps.
config.visState.animationConfigobjectTimeline animation configuration
config.visState.animationConfig.currentTimenumber, nullCurrent timestamps (UNIX epoch microseconds)
config.visState.animationConfig.speednumberSpeed of playback

Layers

An array of layers can be added via the config.visState.interactionConfig.layers array:

SettingTypeDescription
config.visState.layersarraySee layer configuration.

Filters

SettingTypeDescription
config.visState.filtersarray

Interaction Configuration

Contains the configuration for interactive elements on the map. The config.visState.interactionConfig has a number of sub objects defining various aspects of map interactivity.

Tooltips

Enable and configure tooltips can be defined in config.visState.interactionConfig.tooltip:

SettingTypeDescription
tooltipobject
tooltip.enabledobject
tooltip.fieldsToShowobjectmap of fields to show, keyed by fieldId
tooltip.fieldsToShow[fieldId].namestringname of field
tooltip.fieldsToShow[fieldId].formatnullformat of field
tooltip.compareModeboolean
tooltip.compareType'absolute'

Brushing

Enable and configure the brushing feature by adding a config.visState.interactionConfig.brush object:

SettingTypeDescription
brush?object
brush.enabled?booleanWhether brushing is enabled
brush.size?numberThe size of the brush

Geocoder

Enable and configure the geocoder feature by adding a config.visState.interactionConfig.geocoder object:

SettingTypeDescription
config.visState.geocoderobject
config.visState.geocoder.enabledbooleanEnable the geocoder control

Coordinate

SettingTypeDescription
config.visState.coordinateobject
config.visState.coordinate.enabledbooleanEnable coordinate tooltip

Example Map Config

{
  "version": "v1",
  "config": {
    "mapState": {
      "bearing": 0,
      "dragRotate": true,
      "latitude": 27.82040844812393,
      "longitude": 31.05221861771137,
      "pitch": 0,
      "zoom": 1.844221289168002,
      "isSplit": false,
      "mapViewMode": "MODE_GLOBE",
      "mapSplitMode": "SINGLE_MAP",
      "globe": {
        "enabled": true,
        "config": {
          "atmosphere": true,
          "azimuth": true,
          "azimuthAngle": 174,
          "basemap": true,
          "labels": false,
          "terminator": true,
          "terminatorOpacity": 0.33
        }
      }
    },
    "mapStyle": {
      "styleType": "dark",
      "topLayerGroups": {},
      "visibleLayerGroups": {
        "label": true,
        "road": true,
        "border": false,
        "building": true,
        "water": true,
        "land": true,
        "3d building": false
      },
      "threeDBuildingColor": [
        9.665468314072013,
        17.18305478057247,
        31.1442867897876
      ],
      "mapStyles": {}
    },
    "visState": {
      "filters": [],
      "interactionConfig": {
        "tooltip": {
          "fieldsToShow": {
            "f81a0c43-3712-484f-b7a9-24e826777138": [
              {
                "name": "hex",
                "format": null
              },
              {
                "name": "population",
                "format": null
              }
            ]
          },
          "compareMode": false,
          "compareType": "absolute",
          "enabled": true
        },
        "brush": {
          "size": 0.5,
          "enabled": false
        },
        "geocoder": {
          "enabled": false
        },
        "coordinate": {
          "enabled": false
        }
      },
      "layerBlending": "additive",
      "splitMaps": [],
      "animationConfig": {
        "currentTime": null,
        "speed": 1
      },
      "metrics": [],
      "geoKeys": [],
      "groupBys": [],
      "datasets": {
        "fieldDisplayNames": {
          "f81a0c43-3712-484f-b7a9-24e826777138": {}
        }
      },
      "joins": [],
      "layers": [
        {
          "id": "zyf79x7",
          "type": "hexagonId",
          "config": {
            "dataId": "f81a0c43-3712-484f-b7a9-24e826777138",
            "label": "Population - 10 km",
            "color": [130, 154, 227],
            "columns": {
              "hex_id": "hex"
            },
            "isVisible": true,
            "visConfig": {
              "opacity": 0.8,
              "colorRange": {
                "name": "Sunrise 8",
                "type": "sequential",
                "category": "Uber",
                "colors": [
                  "#194266",
                  "#355C7D",
                  "#63617F",
                  "#916681",
                  "#C06C84",
                  "#D28389",
                  "#E59A8F",
                  "#F8B195"
                ]
              },
              "coverage": 1,
              "enable3d": true,
              "sizeRange": [0, 500],
              "coverageRange": [0, 1],
              "elevationScale": 39.1
            },
            "hidden": false,
            "textLabel": [
              {
                "field": null,
                "color": [255, 255, 255],
                "size": 18,
                "offset": [0, 0],
                "anchor": "start",
                "alignment": "center"
              }
            ]
          },
          "visualChannels": {
            "colorField": {
              "name": "population",
              "type": "integer"
            },
            "colorScale": "quantile",
            "sizeField": {
              "name": "population",
              "type": "integer"
            },
            "sizeScale": "linear",
            "coverageField": null,
            "coverageScale": "linear"
          }
        }
      ]
    }
  }
}

Updated 4 months ago