Map Functions

Using the Unfolded 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

Creates a new UnfoldedMap instance. Calling this embeds an Unfolded Map in your web page or Jupyter notebook.

Below is an simple usage of UnfoldedMap, calling an an existing map by its UUID. The UUID can be retrieved from the Data SDK's list_maps() function or from the URL of the map on Unfolded Studio. This will load and embed the UnfoldedMap in the webpage.

const unfoldedMap = new UnfoldedMap({
  embed: true
from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap(

If no UUID is provided, a new local map is created. Neither the map nor its data will be uploaded to the Unfolded cloud—all data stays in your local browser.

const unfoldedMap = new UnfoldedMap()
from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap()

In both instances, the returned object can be used to programmatically control the embedded map.

UnfoldedMap reference

HTML Unfolded Map

Creates a static version of Unfolded Studio. This is intended to be used inside Databricks notebooks since they do not support full Jupyter Widgets.

In the below example, a new HTMLUnfoldedMap is created with a earthquake dataset.

from unfolded.map_sdk import HTMLUnfoldedMap
import pandas as pd

data_url = ''
earthquakes_df = pd.read_csv(data_url)

          'label': 'Earthquakes',
          'data': earthquakes_df,

You can also define a layer specification for each dataset:

import pandas as pd
from unfolded.map_sdk import HTMLUnfoldedMap
from unfolded.map_sdk.models import Dataset, LayerSpec, LayerConfig

data_url = ''
earthquakes_df = pd.read_csv(data_url)

dataset = Dataset(

layer = LayerSpec(
    id = 'earthquake_points',
    type = 'point',
    config = LayerConfig(
        data_id = dataset.uuid,
        label = 'Earthquakes',
        columns = {'lat': 'Latitude','lng': 'Longitude'},
        is_visible = True,
        color_field = {'name': 'Magnitude','type': 'real'}

    datasets = [dataset],
    layers = [layer],

For more information and examples, please visit the full Map SDK reference.

HTMLUnfoldedMap reference

Get Map URL

Gets the url for a map created and published in Unfolded Studio.

var mapUrl = UnfoldedMapSDK.getMapUrl('MAP-UUID-GOES-HERE');
// OUTPUT: ''
from unfolded.map_sdk import UnfoldedMap
map_url = UnfoldedMap.get_map_url('MAP-UUID-GOES-HERE')

getMapURL reference

Get Map Configuration

Returns the map configuration object that contains mapState, mapStyle, and visState object properties. To ensure a return, only use getMapConfig after the map successfully loads.

getMapConfig can be used to store a configuration, then reload it using setMapConfig.

unfoldedMap.getMapConfig().then(mapConfig => {
mapConfig = unfolded_map.get_map_config()
# Then, in another cell you can call:

getMapConfig reference

Set Map Configuration

Sets the map configuration, including the mapState, mapStyle, and visState object properties. You can use the version tag to assign a version of your map.

const unfoldedMap = new UnfoldedMap({
  version: 'v1',
  config: {
    mapState: {...},
    mapStyle: {...},
    visState: {...}
from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap(mapUUID='MAP-UUID-GOES-HERE')
  'version': 'v1',
  'config': {
    'mapState': {...},
    'mapStyle': {...},
    'visState': {...}

setMapConfig reference.

Set View State

Positions the map view at a location specified by coordinates with a defined zoom level.

const unfoldedMap = new UnfoldedMap({
  embed: true,
  longitude: -74.006058,
  latitude: 40.712772,
  zoom: 10
  'latitude': 36.4140,
  'zoom': 15

setViewState reference

Set Split Mode

Sets the map split mode. Allows the user to pass layer id's to set layer visibility per split view.

There are three split modes:

  • single mode, which is the default view containing a single page.
  • dual mode provides the user with a side-by-side comparison of the same map area.
  • swipe mode gives the user a slider to compare different data layers by swiping a seperator.
const unfoldedMap = new UnfoldedMap({
  embed: true,
unfoldedMap.setSplitMode('dual', [['layer_id_1'], ['layer_id_2', 'layer_id_3']]);
unfolded_map.set_split_mode('dual', [['layer_id_1'], ['layer_id_2', 'layer_id_3']])

setSplitMode reference

Set Theme

Changes the Unfolded Studio theme to dark or light based on passed parameter.

You may also change any theme options available in your theme preset. This example changes the theme to light and the backgroundColor to red:

const unfoldedMap = new UnfoldedMap({
  embed: true,
unfoldedMap.setTheme('light', {backgroundColor: 'red'});
unfolded_map.set_theme(theme: 'light', {background_color: '#FF0000'})

setTheme reference

Set Map Control Visibility

Controls the visibility of map controls, such as the map legend.



This function is not yet available in the Python SDK.

You can control the following map control visibility with the Map SDK through a configuration object. This object contains a panelID with an isVisible boolean.

Map Control




2D / 3D View Control


Split Map Control


Map Draw Control


const unfoldedMap = new UnfoldedMap({
  embed: true,
  appendToDocument: true
const config = {
  panelId: 'mapLegend',
  isVisible: false
Not yet supported. Coming soon.

setMapControlVisibility reference

Did this page help you?