Using the Map SDK, you can configure the visualization configuration of maps, then embed them into a webpage or notebook.

For a full description of a function and its parameters, please follow the link to the full Map SDK reference.

Create Map

This functions creates a new map. It accepts a single MapCreationProps object (or keyword arguments in Python), allowing you to customize the style, event handlers, basemaps, raster support, and various UI configuration settings. Many of these advanced options are only available for on-prem versions of the Map SDK.

JavaScript

const map = createMap({apiKey: "<api-key>"});

Python

map = create_map(api_key="<api-key>")

For example, you can also load published maps from the Map SDK by setting initialState.publishedMapId:

JavaScript

const map = createMap({
  apiKey: "<api-key>",
  initialState: {publishedMapId: '<uuid>'}
})

Python

map = create_map(
  api_key="<api-key>",
  initial_state={'published_map_id': '<uuid>'}
)

Arguments

This is the full list of additional properties within MapCreationProps that you can provide when creating a map.

Note: Python Arguments require Python syntax and snake_case parameter names.

For more information, including full Python documentation, see createMap() in the full API reference.

Get Map Configuration

Gets the configuration representing the current map state.

For more information, see the JSON reference for the map configuration file.

JavaScript

mapConfig = map.getMapConfig();

Python

map_config = map.get_map_config()

For more information, including full Python documentation, see getMapConfig() in the full API reference.

Get Map Control Visibility

Gets the current map control visibility settings. This object contains flags that control the visibility of the legend, toggle_3d, split_map, and map_draw buttons.

JavaScript

mapVisibilitySettings = map.getMapControlVisibility();

Python

map_visibility_settings = map.get_map_control_visibility()

For more information, including full Python documentation, see getMapControlVisibility() in the full API reference.

Get Split Mode

Gets the current split mode of the map along with its associated layers.

JavaScript

splitMode = map.getSplitMode();

Python

split_mode = map.get_split_mode();

For more information, including full Python documentation, see getSplitMode() in the full API reference.

Get View

Gets the current view state of the map. The view state object contains the viewport's latitude, longitude, zoom, pitch, and bearing.

JavaScript

view = map.getView();

Python

view = map.get_view()

For more information, including full Python documentation, see getView() in the full API reference.

Get View Limits

Gets the current view limits of the map. This includes the minZoom, maxZoom, and maxBounds, all of which limit the user's viewport.

JavaScript

viewLimits = map.getViewLimits();

Python

view_limits = map.get_view_limits()

For more information, including full Python documentation, see getViewLimits() in the full API reference.

Get View Mode

Gets the current view mode of the map. View mode can be one of "2D", "3D", or "globe".

JavaScript

viewMode = map.getViewMode();

Python

view_mode = map.get_view_mode()

Remove Event Handlers

Removes event handlers from the map, layers, or filters.

Note: This function only exists for Python. While using Javascript, event handlers can be accessed, added, and modified through the map object.

Python

map.remove_event_handlers(["on_view_update"])

Arguments

For more information, see remove_event_handlers() in the full API reference.

Set Event Handlers

Applies the specified event handlers to the map, layers, or filters.

Note: This function only exists for Python. While using Javascript, event handlers can be accessed, added, and modified through the map object.

Python

map.set_event_handlers(EventHandlers(on_view_update=my_handler_func))

Arguments

For more information, see set_event_handlers() in the full API reference.

Set Map Config

Loads the provided configuration into the map. See the the map format reference to learn about Studio's map configuration JSON schema.

JavaScript

map.setMapConfig({
  version: "v1",
  config: {
    visState: {
      filters: [],
      layers: [],
      interactionConfig: {
        tooltip: {
          fieldsToShow: {},
          compareMode: false,
          compareType: "absolute",
          enabled: true
        },
        brush: {
          size: 0.5,
          enabled: false
        },
        geocoder: {
          enabled: false
        },
        coordinate: {
          enabled: false
        }
      },
      layerBlending: "normal",
      overlayBlending: "normal",
      splitMaps: [],
      animationConfig: {
        currentTime: null,
        speed: 1
      },
      editor: {
        features: [],
        visible: true
      },
      metrics: [],
      geoKeys: [],
      groupBys: [],
      datasets: {
        fieldDisplayNames: {},
        fieldDisplayFormats: {},
        datasetColors: {}
      },
      joins: [],
      analyses: [],
      charts: []
    },
    mapState: {
      bearing: 0,
      dragRotate: false,
      latitude: 37.75043,
      longitude: -122.34679,
      pitch: 0,
      zoom: 9,
      isSplit: false,
      isViewportSynced: true,
      isZoomLocked: false,
      splitMapViewports: [],
      mapViewMode: "MODE_2D",
      mapSplitMode: "SINGLE_MAP",
      globe: {
        enabled: false,
        config: {
          atmosphere: true,
          azimuth: false,
          azimuthAngle: 45,
          terminator: true,
          terminatorOpacity: 0.35,
          basemap: true,
          labels: false,
          labelsColor: [
            114.75,
            114.75,
            114.75
          ],
          adminLines: true,
          adminLinesColor: [
            40,
            63,
            93
          ],
          water: true,
          waterColor: [
            17,
            35,
            48
          ],
          surface: true,
          surfaceColor: [
            9,
            16,
            29
          ]
        }
      }
    },
    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
      ],
      backgroundColor: [
        255,
        255,
        255
      ],
      mapStyles: {}
    }
  }
)

Python

map.set_map_config({
  "version": "v1",
  "config": {
    "visState": {
      "filters": [],
      "layers": [],
      "interactionConfig": {
        "tooltip": {
          "fieldsToShow": {},
          "compareMode": False,
          "compareType": "absolute",
          "enabled": True
        },
        "brush": {
          "size": 0.5,
          "enabled": False
        },
        "geocoder": {
          "enabled": False
        },
        "coordinate": {
          "enabled": False
        }
      },
      "layerBlending": "normal",
      "overlayBlending": "normal",
      "splitMaps": [],
      "animationConfig": {
        "currentTime": null,
        "speed": 1
      },
      "editor": {
        "features": [],
        "visible": True
      },
      "metrics": [],
      "geoKeys": [],
      "groupBys": [],
      "datasets": {
        "fieldDisplayNames": {},
        "fieldDisplayFormats": {},
        "datasetColors": {}
      },
      "joins": [],
      "analyses": [],
      "charts": []
    },
    "mapState": {
      "bearing": 0,
      "dragRotate": False,
      "latitude": 37.75043,
      "longitude": -122.34679,
      "pitch": 0,
      "zoom": 9,
      "isSplit": False,
      "isViewportSynced": True,
      "isZoomLocked": False,
      "splitMapViewports": [],
      "mapViewMode": "MODE_2D",
      "mapSplitMode": "SINGLE_MAP",
      "globe": {
        "enabled": False,
        "config": {
          "atmosphere": True,
          "azimuth": False,
          "azimuthAngle": 45,
          "terminator": True,
          "terminatorOpacity": 0.35,
          "basemap": True,
          "labels": False,
          "labelsColor": [
            114.75,
            114.75,
            114.75
          ],
          "adminLines": True,
          "adminLinesColor": [
            40,
            63,
            93
          ],
          "water": True,
          "waterColor": [
            17,
            35,
            48
          ],
          "surface": True,
          "surfaceColor": [
            9,
            16,
            29
          ]
        }
      }
    },
    "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
      ],
      "backgroundColor": [
        255,
        255,
        255
      ],
      "mapStyles": {}
    }
  }
})

For more information, see setMapConfig() in the full API reference.

Set Map Control Visibility

Sets the visibility of map controls, including the legend, toggle-3d, split-map, and map-draw buttons.

JavaScript

map.setMapControlVisibility({
  legend: false,
  map-draw: false,
  split-map: true,
  toggle-3d: false,
  chart: false
});

Python

map.set_map_control_visibility(
    PartialMapControlVisibility(
      legend=False,
      toggle_3d=True
    )
)

Arguments

For more information, including full Python documentation, see setMapControlVisibility() in the full API reference.

Set Split Mode

Set the split mode of the map. Takes SplitMode and an options object.

JavaScript

map.setSplitMode("swipe", {
  layers: [["left_layer"], ["right_layer"]],
  isViewSynced: true,
  isZoomSynced: true,
});

Python

map.set_split_mode(split_mode='dual', options=PartialSplitModeContext(
    is_view_synced=True,
    is_zoom_synced=False,
))

Arguments

For more information, including full Python documentation, see setSplitMode() in the full API reference.

Set Theme

Sets the UI theme of the map. A theme contains a preset (either light or dark), as well as an optional background_color.

JavaScript

map.setTheme({
  preset: "light",
  options: {
    backgroundColor: "lightseagreen",
  },
});

Python

map.set_theme(
  preset="dark",
  background_color="lightseagreen"
)

Arguments

For more information, including full Python documentation, see setTheme() in the full API reference.

Set Tooltip

Defines that status of the interactive tooltip on the map.

JavaScript

map.setTooltipConfig({
  enabled: true,
  tooltipConfig: {
      fieldsToShow: {
        compareType: "relative",
        compareMode: true,
        "datasetId1": [{
            name: "lat",
            format: null
        }, {
            name: "lon",
            format: null
        }],
        "datasetId2": [{
            name: "datasetColumnName",
            format: null
        }]
      }
  },
})

Python

map.set_tooltip_config(map.TooltipInteractionConfig(
    enabled=True,
    tooltip_config=map.TooltipConfig(
        compare_type="relative",
        compare_mode=True
        fields_to_show={
            "datasetId1": [
                map_sdk.TooltipField(name = "lat"),
                map_sdk.TooltipField(name = "lon"),
            ],
            "datasetId2": [
                map_sdk.TooltipField(name = "dataset_column_name")
            ]
        }
    )
))

Arguments

For more information, including full Python documentation, see setTooltip() in the full API reference.

Set View

Sets the view state of the map. The view state object should contain the viewport's latitude, longitude, zoom, pitch, and bearing.

JavaScript

map.setView({
  longitude: -118.8189,
  latitude: 34.01207,
  zoom: 10,
  pitch: 0,
  bearing: 0,
});

Python

map.set_view(PartialView(
    longitude = -118.8189,
    latitude = 34.01207,
    zoom = 10,
    pitch = 0,
    bearing = 0
))

Arguments

For more information, including full Python documentation, see setView() in the full API reference.

Set View Limits

Set the view limits of the map. This includes the minZoom, maxZoom, and maxBounds, all of which limit the user's viewport.

JavaScript

map.setViewLimits({
  minZoom: 0,
  maxZoom: 22,
  maxBounds: {
    minLongitude: -122.4845632122524,
    maxLongitude: -121.7461580455235,
    minLatitude: 37.49028773126059,
    maxLatitude: 37.94131376494916,
  },
});

Python

map.set_view_limits(PartialViewLimits(
    min_zoom=0,
    max_zoom=22,
    max_bounds=Bounds(
        min_longitude=-122.4845632122524,
        max_longitude=-121.7461580455235,
        min_latitude=37.49028773126059,
        max_latitude=37.94131376494916
    )
))

Arguments

For more information, including full Python documentation, see setVZiewLimits() in the full API reference.

Set View Mode

Sets the view mode of the map to one of 2D, 3D, or globe.

JavaScript

map.setViewMode("3d");

Python

map.set_view_mode("3d")

Arguments

For more information, including full Python documentation, see setView() in the full API reference.

Set Animation From Config

Sets the animation properties from the animation JSON configuration.

This function can configure animation to either of types of animation (layer and timeline type of animation).

JavaScript

map.setAnimationFromConfig({
  currentTime: 123,
  speed: 1.1,
  domain: [100, 200],
  timeFormat: 'L LTS'
});

Python

map.set_animation_from_config(
    Animation(
        currentTime=1655250000,
        domain=[1655250000, 1655251000],
        speed=1.1,
        timeFormat="L LTS",
    )
)

For more information, including full Python documentation, see setAnimationFromConfig() in the full API reference.

Effect Functions

The Map SDK allows you to apply post-processing effects to your maps. With a robust set of post-processing effects available, users familiar with Photoshop and other image editing programs should find a similar set of functionality.

Add Effect

Add a new effect to the map.

JavaScript

map.addEffect({
  type: "light-and-shadow",
  parameters: {
    shadowIntensity: 0.5,
    shadowColor: [0, 0, 0],
    sunLightColor: [255, 255, 255],
    sunLightIntensity: 1,
    ambientLightColor: [255, 255, 255],
    ambientLightIntensity: 1,
    timeMode: "current",
  },
});

Python

map.add_effect(
    EffectCreationProps(
        id="effect-id",
        type=EffectType.INK,
        is_enabled=False,
        parameters={"strength": 0.33},
    )
)

Parameters

Update Effect

Update an effect on the map.

JavaScript

map.updateEffect({
  id: "effect-id",
  isEnabled: false,
  parameters: {
    shadowIntensity: 0.75,
    shadowColor: [25, 50, 75]
  },
});

Python

map.update_effect(
    "effect-id",
    values=EffectUpdateProps(
        is_enabled=True,
        parameters={"strength": 0.5}
    ),
)

Parameters

Get Effects

Get a list of effects added to the map.

JavaScript

map.getEffects()

Python

map.get_effects()

Get Effect by ID

Get an effect by specifying its ID.

JavaScript

map.getEffectByID("effect-id")

Python

map.get_effect_by_id("effect-id")

Remove Effect

Remove an effect from the map.

JavaScript

map.removeEffect("effect-id")

Python

map.remove_effect("effect-id")