Map Functions

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.

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

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

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

createMap({apiKey: "<api-key>", initialState: {publishedMapId: '<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.

ArgumentTypeDescription
apiKey (required)stringYour Map SDK API Key (see Authentication).
containerHTMLElementDOM element to embed map into.
styleCSSPropertiesMap container CSS style customization.
eventHandlersMapEventHandlersEvent handlers to attach to the map.
showPlaceholderboolVisibility of loading screen placeholder. Default: true
initialStateobjectInformation about the state to load upon creation.
initialState.publishedMapIdstringIdentifier of the map to load. Note: the map must be published (currently an action available in the Studio UI). Not supported in the on-prem SDK.
basemapsobjectBasemap customization settings.
basemaps.customMapStylesMapStyleCreationProps[]Custom map styles to make available for usage.
basemaps.mapboxAccessTokenstringMapbox token to be used when loading the provided custom map styles.
basemaps.initialMapStyleIdstringIdentifier for the map style to be used initially.
transformRequestfunctionFunction to transform basemap resource requests.
rasterobject
Customization related to raster datasets and tiles.
raster.serverUrlsstring[]
URLs to custom servers to target when serving raster tiles.
raster.stacSearchUrlsstring
URL to pass to the backend for searching a STAC Collection.
raster.onTileLoadUpdateRasterTileLoadEvent
Called whenever a raster layer tile loading status updates.
uiConfigobject
UI configuration object.
uiConfig.mapNamestring
Name of the map to show in the title. Default = Studio
uiConfig.sidePanelobject
A UI component displaying options for data, layer, and map manipulation.
uiConfig.sidePanel.viewstring
View state of the side panel. Options include 'hidden','collapsed', or 'visible'.
uiConfig.sidePanel.isAddLayerVisiblebool
When enabled, display the "Add Layer" button.
uiConfig.sidePanel.addDataButtonobject
Custom settings for the Add Data button.
uiConfig.sidePanel.addDatabutton.onClick
Custom event handler for the Add Data button.
uiConfig.sideNavobject
A UI element containing company logo and relevant links.
uiConfig.sideNav.isVisiblebool
When enabled, display the sidenav sidePanel.
urls.staticAssetUrlBasestring
Custom URL base for static assets.
urls.applicationUrlBasestring
Custom URL base for workers and other script resources loaded by the SDK.

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.

mapConfig = map.getMapConfig();
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.

mapVisibilitySettings = map.getMapControlVisibility();
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.

splitMode = map.getSplitMode();
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.

view = map.getView();
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.

viewLimits = map.getViewLimits();
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".

viewMode = map.getViewMode();
view_mode = map.get_view_mode()

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


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.

map.remove_event_handlers(["on_view_update"])

Arguments

ArgumentTypeDescription
event_handlersSequence[string]A list of event handlers to remove. Passed in as a list of strings.

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.

map.set_event_handlers(EventHandlers(on_view_update=my_handler_func))

Arguments

ArgumentTypeDescription
event_handlersMapEventHandlers, LayerEventHandlers, FilterEventHandlers, dictEvent handlers to set. Can be passed as in through the aforementioned objects, as a dict, or through keyword 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.

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: {}
    }
  }
)
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": {}
    }
  }
})
ArgumentTypeDescription
configStudio MapConfigConfiguration to load into the map. For details around the format see the map format reference.
optionsSetMapConfigOptionsA set of options for the map configuration.

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.

map.setMapControlVisibility({
  legend: false,
  map-draw: false,
  split-map: true,
  toggle-3d: false,
  chart: false
});
map.set_map_control_visibility(
    PartialMapControlVisibility(
      legend=False,
      toggle_3d=True
    )
)

Arguments

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

ArgumentTypeDescription
mapControlsobjectObject containing map control visibility settings.
mapControls.legendboolWhether the legend is visible.
mapControls.toggle-3dboolWhether the 3D toggle is visible.
mapControls.split-mapboolWhether the split map button is visible.
mapControls.map-drawboolWhether the map draw button is visible.

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.

map.setSplitMode("swipe", {
  layers: [["left_layer"], ["right_layer"]],
  isViewSynced: true,
  isZoomSynced: true,
});
map.set_split_mode(split_mode='dual', options=PartialSplitModeContext(
    is_view_synced=True,
    is_zoom_synced=False,
))

Arguments

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

ArgumentTypeDescription
splitModestringSupported split map modes. Either 'single', 'dual', or 'swipe'.
splitModeOptionsobjectAn object containing split mode map options.
splitModeOptions.layersstring[][]Optional array of layerIds to show on either side of the split. Only applicable for dual and swipe split modes.
splitModeOptions.isViewSyncedboolBoolean indicating whether views are synced. Only applicable to dual split mode.
splitModeOptions.isZoomSyncedboolBoolean indicating whether zoom is synced between views. Only applicable to dual split mode.

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.

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

Arguments

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

ArgumentTypeDescription
themeobjectAn object containing UI theme preset options.
theme.presetstringUI theme preset name.
theme.optionsobjectOptional UI theme customization options.
theme.options.backgroundColorstringBackground color of UI elements in a CSS color string.

For more information, including full Python documentation, see setTheme() 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.

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

Arguments

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

ArgumentTypeDescription
viewobjectAn object containing view options.
view.longitudenumberLongitude of the view center [-180, 180].
view.latitudenumberLatitude of the view center [-90, 90].
view.zoomnumberView zoom level [0-22].
view.pitchnumberView pitch value [0-90].
view.bearingnumberView bearing.
view.dragRotatebooleanWhether to allow point drag rotate.

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.

map.setViewLimits({
  minZoom: 0,
  maxZoom: 22,
  maxBounds: {
    minLongitude: -122.4845632122524,
    maxLongitude: -121.7461580455235,
    minLatitude: 37.49028773126059,
    maxLatitude: 37.94131376494916,
  },
});
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

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

ArgumentTypeDescription
viewLimitsobjectAn object containing view limit options.
viewLimit.sminZoomnumberMinimum allowed zoom level.
viewLimit.maxZoomnumberMaximum allowed zoom level.
viewLimit.maxBoundsobjectObject containing optional maximum allowed bounds.
viewLimit.maxBound.minLongitudenumberMinimum (left) longitude value.
viewLimit.maxBound.maxLongitudenumberMaximum (right) longitude value.
viewLimit.maxBound.minLatitudenumberMinimum (bottom) latitude value.
viewLimit.maxBound.maxLatitudenumberMaximum (top) latitude value.

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.

map.setViewMode("3d");
map.set_view_mode("3d")

Arguments

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

ArgumentTypeDescription
view_modeViewModeAn object containing view modes. One of "2d","3d", or "globe"

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).

map.setAnimationFromConfig({
  currentTime: 123,
  speed: 1.1,
  domain: [100, 200],
  timeFormat: 'L LTS'
});
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.

Learn more about each effect available, including examples and all parameters available.

Add Effect

Add a new effect to the map.

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",
  },
});
map.add_effect(
    EffectCreationProps(
        id="effect-id",
        type=EffectType.INK,
        is_enabled=False,
        parameters={"strength": 0.33},
    )
)

Parameters

ArgumentTypeDescription
idstringUnique identifier of the effect.
typeEffectTypeRequired. The type of the effect. See types and respective parameters here.
isEnabledboolFlag indicating whether the effect is enabled or not.
parametersdictEffect-specific settings. See all available parameters here.

Update Effect

Update an effect on the map.

map.updateEffect({
  id: "effect-id",
  isEnabled: false,
  parameters: {
    shadowIntensity: 0.75,
    shadowColor: [25, 50, 75]
  },
});
map.update_effect(
    "effect-id",
    values=EffectUpdateProps(
        is_enabled=True,
        parameters={"strength": 0.5}
    ),
)

Parameters

ArgumentTypeDescription
idstringRequired. Unique identifier of the effect to update.
typeEffectTypeThe type of the effect. See types and respective parameters here.
isEnabledboolFlag indicating whether the effect is enabled or not.
parametersdictEffect-specific settings to update. See all available parameters here.

Get Effects

Get a list of effects added to the map.

map.getEffects()
map.get_effects()

Get Effect by ID

Get an effect by specifying its ID.

map.getEffectByID("effect-id")
map.get_effect_by_id("effect-id")

Remove Effect

Remove an effect from the map.

map.removeEffect("effect-id")
map.remove_effect("effect-id)