❗️
You are viewing documentation for an old version of the Studio Map SDK
This API reference refers to only version 0 of the Studio Map SDK. It is highly recommended to upgrade to version 1, which comes with type safety, a wide range of new features, and added security.

Map Functions

This section contains detailed reference documentation covering the Map SDK's map functions.

To view each function with a brief description and an example, visit the map functions documentation.

UnfoldedMap

Creates a new UnfoldedMap. This embeds a Studio Map
in your web page or Jupyter Notebook. The returned object is used to
programmatically control the embedded map.

UnfoldedMap() can either:

Load a published or private map from the Studio cloud (specified using its map id).
Create a new local map (that is not saved to the Studio cloud).

You can add data and layers to a local map, however neither the map itself nor any data you add to it will be uploaded to the Studio cloud. All data stays in your local browser. Note that you still need to use a valid Studio token to create local maps.

new UnfoldedMap({
  mapUUID?: string,
  embed: boolean,
  id: string,
  appendToDocument: boolean,
  appendToId: string,
  width?: number | string,
  height?: number | string,
  onLoad?,
  onFilter?,
  onTimelineIntervalChange?,
  onLayerTimelineTimeChange?
})

UnfoldedMap(
  mapUUID: Optional[str],
  width: Optional[Union[str, int]],
  height: Optional[Union[str, int]],
  on_load: Optional[Callable[[None], None]],
  on_filter: Optional[Callable[[FilterChangeEvent], None]]
  on_timeline_interval_change: Optional[Callable[[List[int]], None]],
  on_layer_timeline_time_change: Optional[Callable[[int], None]],
)

Parameters

Parameter	Type	Description
`mapUUID`	`string`	The id (`UUID`) of a published Studio map. If no UUID is provided, a new map is created. The UUID of a Map can be copied from the URL of the map or obtained using the Data SDK.
`onLoad`	event handler	Map load event handler.
`onFilter`	event handler	Event handler for map filter changes.
`onTimelineIntervalChange`	event handler	Event handler for timeline interval change events. The handler is passed an array of two Unix timestamps as a parameter: `[intervalStartTime, intervalEndTime]` (in milliseconds).
`onLayerTimelineTimeChange`	event handler	Event handler for time change events in the layer timeline. The handler is passed the time as a Unix timestamp (in milliseconds) as a parameter.
`onFilter`	event handler	Event handler for time change events in the layer timeline. The handler is passed the time as a Unix timestamp (in milliseconds) as a parameter.
`width`	`int`, `string`	Width of the embedded map. Can be a number in pixel units or a valid CSS string (e.g. `'100%'`, `'100vh'`...). Defaults to `'100%'`.
`height`	`int`, `string`	Height of the embedded map. Can be a number in pixel units or a valid CSS string (e.g. `'100%'`, `'100vh'`...). Defaults to `'100%'`.

JavaScript Only Parameters

The JavaScript version also provides additional support for custom integrations and CSS styling.
The optional id, appendToDocument and appendToId parameters lets you control how the map is added to your page.

JavaScript Parameter	Type	Description
`embed`	`boolean`	If `true`, loads the map in the embedded mode. Default: `false`.
`id`	`string`	ID of the map HTML element (for CSS styling).
`appendToDocument`	`boolean`	Specify `false` if you would like to manually add the map HTML element to your web page.
`appendToId`	`string`	If supplied, specifies the HTML ID of the HTML element to which the map should be appended. By default the map is added to `document.body`.

Returns

A JavaScript or Python instance object that can be used to invoke other SDK functions on the newly created embedded map.

Examples

Using Map UUID:

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});

from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap(
  mapUUID='MAP-UUID-GOES-HERE'
)
unfolded_map

Using local map:

const unfoldedMap = new UnfoldedMap();

from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap()
unfolded_map

HTMLUnfoldedMap

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

HTMLUnfoldedMap() can either:

Load a published or private map from the Studio cloud (specified using its map id).
Create a new local map (that is not saved to the Studio cloud).

You can add data and layers to a local map, however neither the map itself nor any data you add to it will be uploaded to the Studio cloud. All data stays in your local browser. Note that you still need to use a valid Studio token to create local maps.

HTMLUnfoldedMap(
  *,
  datasets: Sequence[Union[unfolded.map_sdk.models.Dataset, Dict]] = (),
  layers: Sequence[Union[unfolded.map_sdk.models.LayerSpec, Dict]] = (),
  filters: Sequence[Union[unfolded.map_sdk.models.FilterInfo, Dict]] = (),
  map_config: Optional[Union[unfolded.map_sdk.models.MapConfig, Dict]] = None,
  mapUrl: Optional[str] = None,
  mapUUID: Optional[str] = None,
  width: Optional[Union[str, int]] = '100%',
  height: Optional[Union[str, int]] = 400,
  center_map: bool = True,
)

Parameters

Inherits all parameters from UnfoldedMap.

Additional parameters:

Parameter	Prop	Type	Description
`datasets`	-	list of `dataset` specifications	A Dataset object can be created by passing arguments to unfolded.map_sdk.models.
	`uuid`	`string`	Optional data identifier. Default: a random UUID
	`label`	`string`	Optional dataset label. Default: `'Untitled'`
	`data`	`pandas.DataFrame`, `string`	Required.`pandas.DataFrame` or path to dataset content. If a pandas `DataFrame` is provided, it will be converted to CSV under the hood and passed to Studio Studio. Otherwise, a CSV or JSON encoded as a string is allowed.
`layers`	-	list of `Layer` specifications	A list of `Layer` specifications. A `Layer` object can be created by passing arguments to `unfolded.map_sdk.models.LayerSpec`. Each object should conform to the Studio Layer specification.
`filters`	-	list of `Filter` specifications	A `Filter` object can be created by passing arguments to`unfolded.map_sdk.models.FilterInfo`;
	`id`	`string`	Required. Filter identifier.
	`data_id`	`string`	Required. Identifier of dataset to apply filtering on.
	`field`	`string`	Required. Column within related dataset to apply filtering on.
	`value`	List[float]`,`List[str]`, or`bool`	Range of values to use for data filtering.
`map_config`	-	`unfolded.map_sdk.models.MapConfig`instance,`dict`	If this is provided, it will override the`layers`and`filters`keys. Should conform to the Studio Map specification.
`height`	-	`str`or`int`	The height of the iframe in pixels (e.g.,`500`) or a percentage (e.g.,`100%`). Note that when height =`100%`, Databrick's resizing logic may infinitely scale the iframe. Default:`500`
`width`	-	`str`or`int`	The width of the iframe in pixels (e.g.,`500`) or a percentage (e.g.,`100%`). Default:`100%`
`center_map`	-	`bool`	When`True`, centers map on new dataset. Default:`True`

All other parameters are the same as the standard UnfoldedMap

Returns

A Python instance object that can be used to render Studio Studio with the provided data.

In Databricks, this should render automatically if run in a cell by itself.

Examples

Find Python examples below.

from unfolded.map_sdk import HTMLUnfoldedMap
import pandas as pd

data_url = 'https://raw.githubusercontent.com/UnfoldedInc/examples/master/notebooks/data/earthquakes.csv'
earthquakes_df = pd.read_csv(data_url)

HTMLUnfoldedMap(
    datasets=[
        {
          'label': 'Earthquakes',
          'data': earthquakes_df,
        }
    ]
)

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

data_url = 'https://raw.githubusercontent.com/UnfoldedInc/examples/master/notebooks/data/earthquakes.csv'
earthquakes_df = pd.read_csv(data_url)

dataset = Dataset(
   label='Earthquakes',
   data=earthquakes_df
)

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'}
    )
)

HTMLUnfoldedMap(
    datasets = [dataset],
    layers = [layer],
    height=500
)

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

data_url = 'https://raw.githubusercontent.com/UnfoldedInc/examples/master/notebooks/data/earthquakes.csv'
earthquakes_df = pd.read_csv(data_url)

dataset = Dataset(label='Earthquakes', data=earthquakes_df)
filter_info = FilterInfo(
    id='filter_id', data_id=dataset.uuid, field='Magnitude', value=[2.5, 2.6]
)

HTMLUnfoldedMap(datasets=[dataset], filters=[filter_info])

from uuid import uuid4
import pandas as pd
from unfolded.map_sdk import HTMLUnfoldedMap
from unfolded.map_sdk.models import Dataset

data_url = 'https://raw.githubusercontent.com/UnfoldedInc/examples/master/notebooks/data/earthquakes.csv'
earthquakes_df = pd.read_csv(data_url)

dataset_id = str(uuid4())
dataset = Dataset(uuid=dataset_id, label='Earthquakes', data=earthquakes_df)

map_config = {
    "version": "v1",
    "config": {
        "visState": {
            "filters": [
                {
                    "dataId": [dataset_id],
                    "id": "k7319uc78",
                    "name": ["time"],
                    "type": "timeRange",
                    "value": [1603701166243.6045, 1603787566242.6052],
                    "enlarged": True,
                    "plotType": {
                        "interval": "12-hour",
                        "type": "lineChart",
                        "aggregation": "maximum",
                    },
                    "animationWindow": "free",
                    "yAxis": {"name": "mag", "type": "real"},
                    "speed": 1,
                }
            ],
            "layers": [
                {
                    "id": "k30kgcr",
                    "type": "geojson",
                    "config": {
                        "dataId": dataset_id,
                        "columnMode": "geojson",
                        "label": "all_month",
                        "color": [18, 147, 154],
                        "columns": {"geojson": "_geojson"},
                        "isVisible": True,
                        "visConfig": {
                            "opacity": 0.8,
                            "strokeOpacity": 0.8,
                            "thickness": 0.5,
                            "strokeColor": None,
                            "colorRange": {
                                "name": "Global Warming",
                                "type": "sequential",
                                "category": "Uber",
                                "colors": [
                                    "#5A1846",
                                    "#900C3F",
                                    "#C70039",
                                    "#E3611C",
                                    "#F1920E",
                                    "#FFC300",
                                ],
                            },
                            "strokeColorRange": {
                                "name": "Global Warming",
                                "type": "sequential",
                                "category": "Uber",
                                "colors": [
                                    "#5A1846",
                                    "#900C3F",
                                    "#C70039",
                                    "#E3611C",
                                    "#F1920E",
                                    "#FFC300",
                                ],
                            },
                            "radius": 10,
                            "sizeRange": [0, 10],
                            "radiusRange": [0, 50],
                            "heightRange": [0, 500],
                            "elevationScale": 5,
                            "stroked": False,
                            "filled": True,
                            "enable3d": False,
                            "wireframe": False,
                            "fixedHeight": False,
                        },
                        "hidden": False,
                        "textLabel": [
                            {
                                "field": None,
                                "color": [255, 255, 255],
                                "size": 18,
                                "offset": [0, 0],
                                "anchor": "start",
                                "alignment": "center",
                            }
                        ],
                    },
                    "visualChannels": {
                        "colorField": {"name": "mag", "type": "real"},
                        "colorScale": "quantile",
                        "strokeColorField": None,
                        "strokeColorScale": "quantile",
                        "sizeField": None,
                        "sizeScale": "linear",
                        "heightField": None,
                        "heightScale": "linear",
                        "radiusField": None,
                        "radiusScale": "linear",
                    },
                },
                {
                    "id": "g8n1vni",
                    "type": "geojson",
                    "config": {
                        "dataId": dataset_id,
                        "columnMode": "geojson",
                        "label": "new layer",
                        "color": [34, 63, 154],
                        "columns": {"geojson": "_geojson"},
                        "isVisible": True,
                        "visConfig": {
                            "opacity": 0.8,
                            "strokeOpacity": 0.8,
                            "thickness": 0.5,
                            "strokeColor": None,
                            "colorRange": {
                                "name": "Global Warming",
                                "type": "sequential",
                                "category": "Uber",
                                "colors": [
                                    "#5A1846",
                                    "#900C3F",
                                    "#C70039",
                                    "#E3611C",
                                    "#F1920E",
                                    "#FFC300",
                                ],
                            },
                            "strokeColorRange": {
                                "name": "Global Warming",
                                "type": "sequential",
                                "category": "Uber",
                                "colors": [
                                    "#5A1846",
                                    "#900C3F",
                                    "#C70039",
                                    "#E3611C",
                                    "#F1920E",
                                    "#FFC300",
                                ],
                            },
                            "radius": 79.7,
                            "sizeRange": [0, 10],
                            "radiusRange": [0, 50],
                            "heightRange": [0, 500],
                            "elevationScale": 5,
                            "stroked": True,
                            "filled": False,
                            "enable3d": False,
                            "wireframe": False,
                            "fixedHeight": False,
                        },
                        "hidden": False,
                        "textLabel": [
                            {
                                "field": None,
                                "color": [255, 255, 255],
                                "size": 18,
                                "offset": [0, 0],
                                "anchor": "start",
                                "alignment": "center",
                            }
                        ],
                    },
                    "visualChannels": {
                        "colorField": None,
                        "colorScale": "quantile",
                        "strokeColorField": {"name": "felt", "type": "integer"},
                        "strokeColorScale": "quantile",
                        "sizeField": None,
                        "sizeScale": "linear",
                        "heightField": None,
                        "heightScale": "linear",
                        "radiusField": None,
                        "radiusScale": "linear",
                    },
                },
            ],
            "interactionConfig": {
                "tooltip": {
                    "fieldsToShow": {
                        dataset_id: [
                            {"name": "mag", "format": None},
                            {"name": "place", "format": None},
                            {"name": "time", "format": None},
                            {"name": "updated", "format": None},
                            {"name": "tz", "format": None},
                        ]
                    },
                    "compareMode": False,
                    "compareType": "absolute",
                    "enabled": True,
                },
                "brush": {"size": 0.5, "enabled": False},
                "geocoder": {"enabled": False},
                "coordinate": {"enabled": False},
            },
            "layerBlending": "additive",
            "splitMaps": [],
            "animationConfig": {"currentTime": None, "speed": 1},
            "metrics": [],
            "geoKeys": [],
            "groupBys": [],
            "datasets": {"fieldDisplayNames": {dataset_id: {}}},
            "joins": [],
            "charts": [],
        },
        "mapState": {
            "bearing": 0,
            "dragRotate": False,
            "latitude": 45.98714824780471,
            "longitude": -112.25342718053346,
            "pitch": 0,
            "zoom": 2.6539953739060738,
            "isSplit": False,
            "mapViewMode": "MODE_2D",
            "mapSplitMode": "SINGLE_MAP",
            "globe": {
                "enabled": False,
                "config": {
                    "atmosphere": True,
                    "azimuth": False,
                    "azimuthAngle": 45,
                    "basemap": True,
                    "labels": False,
                    "terminator": True,
                    "terminatorOpacity": 0.35,
                },
            },
        },
        "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": {},
        },
    },
}

getMapUrl

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

UnfoldedMap.getMapUrl(mapUUID: string): string;

UnfoldedMap.get_map_url(map_uuid: str) -> str

Parameters

Parameter	Type	Description
`mapUUID`	`string`	UUID of the map.

Returns

URL string for the map created and published in Studio Studio.

Examples

var mapUrl = UnfoldedMapSDK.getMapUrl("MAP-UUID-GOES-HERE");
console.log(mapUrl);
// OUTPUT: 'https://studio.foursquare.com/public/mapUUID'

from unfolded.map_sdk import UnfoldedMap
map_url = UnfoldedMap.get_map_url('MAP-UUID-GOES-HERE')

getMapConfig

Returns the map configuration object that contains mapState, mapStyle, and visState object properties.

Can be used if you want to store the configuration and later reload it using setMapConfig.

UnfoldedMap.getMapConfig(): Promise<MapConfig>

UnfoldedMap.get_map_config() -> Future

Types

interface MapConfig {
  version: string;
  config: {
    mapState: any,
    mapStyle: any,
    visState: any,
  };
}

class MapConfig:
  version: str
  config: MapConfigInternal
class MapConfigInternal:
   mapState: Any
   mapStyle: Any
   visState: Any

Returns

Map configuration object.

Map configuration can be updated with setMapConfig.

Examples

unfoldedMap.getMapConfig().then((mapConfig) => {
  console.log(mapConfig);
});

mapConfig = unfolded_map.get_map_config()
# Then, in another cell you can call:
mapConfig.result()

setMapConfig

Set map configuration.

UnfoldedMap.setMapConfig(mapConfig: MapConfig): Promise<boolean>

UnfoldedMap.set_map_config(self, mapConfig: models.MapConfig) -> None:

Types

interface MapConfig {
  version: string;
  config: {
    mapState: any,
    mapStyle: any,
    visState: any,
  };
}

class MapConfig:
  version: str
  config: MapConfigInternal
class MapConfigInternal:
   mapState: Any
   mapStyle: Any
   visState: Any

Parameters

Parameter	Type	Description
`mapConfig`	`object`	Specifies the map configuration settings.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: 'MAP-UUID-GOES-HERE'
});
unfoldedMap.setMapConfig({
  version: 'v1',
  config: {
    mapState: {...},
    mapStyle: {...},
    visState: {...}
  }
});

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

setViewState

Positions the map view on a certain location based on provided coordinates, and with a defined zoom level.

UnfoldedMap.setViewState(viewState: ViewState): void

UnfoldedMap.set_view_state(
  view_state: unfolded.map_sdk.models.ViewState
) -> None:

Types

interface ViewState {
  longitude: number;
  latitude: number;
  zoom?: number;
  minZoom?: number;
  maxZoom?: number;
  maxBounds?: Bounds;
}

class ViewState:
    longitude: float
    latitude: float
    zoom: Optional[float] = None

Models

`Bounds`

// Bounds = [minLongitude , minLatitude , maxLongitude , maxLatitude]
type Bounds = [number, number, number, number];

# Bounds = [minLongitude , minLatitude , maxLongitude , maxLatitude]
  Bounds = Tuple[float, float, float, float]

Parameters

Parameter	Part	Type	Description
`viewState`	-	`object`	ViewState that takes in several view properties.
	`longitude`	`float`	Defines the longitude to center the viewport on. Longitude is a decimal number between -180.0 and 180.0.
	`latitude`	`float`	Defines the latitude to center the viewport on. Latitude is a decimal number between -90.0 and 90.0.
	`zoom`	`float`	Defines the viewport zoom level, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in).
	`minZoom`	`float`	Limits the minimum allowed zoom level value.
	`maxZoom`	`float`	Limits the maximum allowed zoom level value.
	`maxBounds`	`Bounds`	Limits the viewport to an area specified by a set of coordinates.

Examples

unfoldedMap.setViewState({
  longitude: -121.1204,
  latitude: 37.51305,
  zoom: 10,
  minZoom: 5,
  maxZoom: 14,
  maxBounds: [
    -122.4845632122524,
    37.49028773126059,
    -121.7461580455235,
    37.94131376494916,
  ],
});

unfolded_map.set_view_state({
    'longitude': -121.1204,
    'latitude': 37.51305,
    'zoom': 10,
    'min_zoom': 5,
    'max_zoom': 14,
    'max_bounds': [-122.4845632122524, 37.49028773126059,
                   -121.7461580455235, 37.94131376494916]
  })

setSplitMode

Sets the map split mode between dual, swipe, or single mode. Allows the user to pass layer id's to set layer visibility per split view.

enum MapSplitMode {
  SINGLE = 'single',
  DUAL = 'dual',
  SWIPE = 'swipe'
}
UnfoldedMap.setSplitMode(mode: MapSplitMode, layers?: string[][]): void

UnfoldedMap.set_split_mode(
  mode: Literal['single', 'dual', 'swipe'],
  layers: Optional[List<List<str>>] = None
) -> None:

Parameters

Parameter	Type	Description
`mode`	`enum`: `single`, `dual`, or `swipe.	Choice between dual, swipe, or single mode.
`layers`	array of`string`	First element in the array should contain the id for a layer to appear on the left half of the map; second element should contain id for layer to appear on right. If the id of an existing and visible layer is not listed in one or both of the elements, layer will be hidden from that half of the map.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  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']])

setTheme

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

UnfoldedMap.setTheme(theme: string, options?: ThemeOptions): void

UnfoldedMap.set_theme(theme: str, options: Optional[ThemeOptions]) -> Optional[Union['Future[str]', str]]:

Types

type ThemeOptions = {
  backgroundColor: string,
};

class ThemeOptions:
   background_color: Optional[str]

Parameters

Parameter	Type	Description
`theme`	`string`	Theme of Studio Studio. Can be 'light' or 'dark'.
`options`	`object`	A set of customization options on top of the theme preset.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
unfoldedMap.setTheme("light", { backgroundColor: "red" });

unfolded_map.set_theme(theme: 'light', {background_color: '#FF0000'})

setMapControlVisibility

Control the visibility of map controls such as the map legend.

UnfoldedMap.setMapControlVisibility(config: MapControlConfig): void

Not yet supported. Coming soon.

Types

interface MapControlConfig {
  panelId: string;
  isVisible: boolean;
}

Not yet supported. Coming soon.

Parameters

Parameter	Type	Description
`config`	`object`	A `MapControlConfig`configuration object that is used to set the map control visibility.
`panelId`	`string`	String id that identifies the map control.
`isVisibile`	`boolean`	Set the visibility of the map control to `true` or `false`.

Currently this API only supports toggling of the map legend.

Map Control	ID
Legend	`mapLegend`
2D / 3D View Control	`toggle3d`
Split Map Control	`splitMap`
Map Draw Control	`mapDraw`

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
  appendToDocument: true,
});
const config = {
  panelId: "mapLegend",
  isVisible: false,
};
unfoldedMap.setMapControlVisibility(config);

Not yet supported. Coming soon.

Data Functions

This section contains detailed reference documentation covering the Map SDK's dataset functions.

To view each function with a brief description and an example, visit the data functions documentation.

addDataset

Add a dataset to the map.

This method can be used to add previously uploaded datasets to a map. To do so provide the id of the Dataset, the method will attempt to add a previously uploaded dataset with the specified id to the map. Datasets can be either uploaded via the Studio Data SDK or manually uploaded in Studio Studio.

Alternatively, if a Dataset object with data is provided, a new dataset will be created and added to the map (but not uploaded to the Studio Cloud).

UnfoldedMap.addDataset(
  dataset: string | Dataset,
  autoCreateLayers = true,
  centerMap = true,
): Promise<boolean>

UnfoldedMap.add_dataset(
  dataset: Union[UUID, str, models.Dataset],
  auto_create_layers: bool = True
  center_map: bool = True
) -> Future

Types

type Dataset = {
  uuid: string,
  label: string,
  data?: string,
};

class Dataset:
  uuid: UUID = Field(default_factory=uuid4)
  label: str = 'Untitled'
  data: Optional[Union[str, pandas.DataFrame, geopandas.GeoDataFrame]]

Parameters

Parameter	Prop	Type	Description
`dataset`	-	`string` or `dataset` object	UUID of the dataset, or dataset object containing `uuid`, `label`, and `data` props.
	`uuid`	`string`	Unique identifier of the dataset
	`label`	`string`	Optional. Displayable dataset label
`autoCreateLayer`	-	`boolean`	When `True`, Studio will attempt to create layers automatically
`centerMap`	-	`bool`	When `True`, center map on the new dataset.

Examples

With dataset uuid:

unfoldedMap.addDataset("DATASET-UUID-GOES-HERE");

unfolded_map.add_dataset('DATASET-UUID-GOES-HERE')

With dataset object:

unfoldedMap.addDataset({
  uuid: "DATASET-UUID-GOES-HERE", // use e.g. www.uuidgenerator.net
  label: "Cities",
  data: JSON.stringify([
    { city: "Buenos Aires", country: "Argentina", lat: -34.58, lon: -58.66 },
    { city: "Brasilia", country: "Brazil", lat: -15.78, lon: -47.91 },
    { city: "Santiago", country: "Chile", lat: -33.45, lon: -70.66 },
    { city: "Bogota", country: "Colombia", lat: 4.6, lon: -74.08 },
    { city: "Caracas", country: "Venezuela", lat: 10.48, lon: -66.86 },
  ]),
});

import pandas as pd
unfolded_map.add_dataset({
  'label': 'Cities',
  'data': pd.DataFrame({
    'City': ['Buenos Aires', 'Brasilia', 'Santiago', 'Bogota', 'Caracas'],
    'Country': ['Argentina', 'Brazil', 'Chile', 'Colombia', 'Venezuela'],
    'Latitude': [-34.58, -15.78, -33.45, 4.60, 10.48],
    'Longitude': [-58.66, -47.91, -70.66, -74.08, -66.86]
    })
})

removeDataset

Remove dataset from the map.

UnfoldedMap.removeDataset(uuid: string): void

UnfoldedMap.remove_dataset(uuid: str) -> None:

Parameters

Parameter	Type	Description
`uuid`	`string`	UUID of the dataset to remove.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
  appendToDocument: true,
});
unfoldedMap.removeDataset("DATASET-UUID-GOES-HERE");

unfolded_map.remove_dataset('DATASET-UUID-GOES-HERE')

refreshMapData

Reloads the data displayed on the map. Useful if your data is updated frequently.

UnfoldedMap.refreshMapData(): void

UnfoldedMap.refresh_map_data() -> None:

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
  appendToDocument: true,
});
unfoldedMap.refreshMapData();

unfolded_map.refresh_map_data()

setFilter

Set filter value.

UnfoldedMap.setFilter(info: FilterInfo): Promise<boolean>

UnfoldedMap.set_filter(self, info: models.FilterInfo) -> None:

Types

type FilterInfo = {
  id: string,
  dataId?: string,
  field: string,
  value: FilterValueType,
};

class FilterInfo:
   id: str
   data_id: Optional[UUID]
   field: str
   value: FilterValueType

Parameters

Parameter	Prop	Type	Description
`info`	-	`object`	Specifies the filter settings.
	`id`	`string`	Unique filter id.
	`field`	`string`	Name of the field to apply to.
	`dataId`	`string`	Dataset id (if omitted, the first dataset which has a field with the name specified in field will be used)
	`value`	`List[float]`, `List[str]`, or `bool`	Range of values to use for data filtering. (the type depends on the filter kind, e.g. an array of two numbers for a range filter).

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
});
unfoldedMap.setFilter({
  id: "value-filter",
  field: "magnitude",
  value: [15, 20],
});

from unfolded.map_sdk import UnfoldedMap
unfolded_map = UnfoldedMap(mapUUID='MAP-UUID-GOES-HERE')
unfolded_map.set_filter({
  'id': 'value-filter',
  'field': 'magnitude',
  'value': [15, 20]
})

Layer Functions

This section contains detailed reference documentation covering the Map SDK's layer functions.

To view each function with a brief description and an example, visit the layer functions documentation.

addLayer

Add a new layer to the map.

To learn about configuring a specific layer programmatically, visit the Map and Layer Format Reference.

Note: The dataset specified in dataId must be added to the map in advance.

UnfoldedMap.addLayer(spec: LayerSpec): void

UnfoldedMap.add_layer(spec: unfolded.map_sdk.models.LayerSpec) -> None:

Types

type LayerSpec = {
  id: string,
  type: string,
  config: LayerConfig,
  visualChannels?: Record<string, VisualChannel>,
};
type LayerConfig = {
  dataId: string,
  label?: string,
  columns: object,
  isVisible?: boolean,
  visConfig?: object,
};
type VisualChannel = {
  colorField?: object,
  colorScale?: string,
};
type LayerType =
  | "point"
  | "arc"
  | "line"
  | "grid"
  | "hexagon"
  | "geojson"
  | "cluster"
  | "icon"
  | "heatmap"
  | "hexagonId"
  | "3D"
  | "trip"
  | "s2";

class LayerSpec:
    id: str
    type: LayerType
    config: LayerConfig
    visual_channels: Optional[Dict[str, VisualChannel]]
class LayerConfig:
    data_id: str
    label: Optional[str]
    columns: Dict[str, Any]
    is_visible: Optional[bool]
    vis_config: Optional[Dict[str, Any]]
class VisualChannel:
    color_field: Optional[Dict[str, Any]]
    color_scale: Optional[str]
class LayerType(str, Enum):
    POINT = 'point'
    ARC = 'arc'
    LINE = 'line'
    GRID = 'grid'
    HEXAGON = 'hexagon'
    GEOJSON = 'geojson'
    CLUSTER = 'cluster'
    ICON = 'icon'
    HEATMAP = 'heatmap'
    HEXAGONID = 'hexagonId'
    _3D = '3D'
    TRIP = 'trip'
    S2 = 's2'

Parameters

Parameter	Type	Description
`layerSpec`	`object`	Layer specification. For details see above types and the below examples. For details on how to programmatically specify layer properties, refer to the Studio Layer Configuration format specification.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
unfoldedMap.addLayer({
  id: "my-points-layer",
  type: "point",
  config: {
    dataId: "data_1",
    columns: {
      lat: "point_lat",
      lng: "point_lng",
      altitude: "point_altitude",
    },
    label: "my point layer",
    isVisible: true,
    visConfig: {
      radius: 10,
      opacity: 0.8,
      colorRange: {
        name: "Global Warming",
        type: "sequential",
        category: "Uber",
        colors: [
          "#5A1846",
          "#900C3F",
          "#C70039",
          "#E3611C",
          "#F1920E",
          "#FFC300",
        ],
      },
    },
  },
  visualChannels: {
    colorField: {
      name: "value",
      type: "real",
    },
    colorScale: "quantile",
  },
});

from unfolded.map_sdk import UnfoldedMap
dataset_id = 'data_1'
unfolded_map = UnfoldedMap(mapUUID='MAP-UUID-GOES-HERE')
unfolded_map.add_dataset(dataset_id)
unfolded_map.add_layer({
  "id": "layer_1",
  "type": "point",
  "config": {
    "dataId": dataset_id,
    "columns": {
      "lat": "point_lat",
      "lng": "point_lng",
      "altitude": "point_altitude"
    },
    "label": "my point layer",
    "isVisible": true,
    "visConfig": {
      "radius": 10,
      "opacity": 0.8,
      "colorRange": {
        "name": "Global Warming",
        "type": "sequential",
        "category": "Uber",
        "colors": ["#5A1846", "#900C3F", "#C70039", "#E3611C", "#F1920E", "#FFC300"]
      }
    }
  },
  "visualChannels": {
    "colorField": {
      "name": "value",
      "type": "real"
    },
    "colorScale": "quantile"
  }
})

getLayers

Returns the label, id and isVisible for each layer that is available on the map.

unfoldedMap.getLayers().then((layers) => {
  layers.forEach((layer) => {
    console.log(layer);
  });
});

layers = unfolded_map.get_layers()
# Then, in another cell you can call:
layers.result()

Types

interface Layer {
  label: string;
  id: string;
  isVisible: boolean;
}

class Layer:
   label: str
   id: str
   is_visible: bool

Returns

An array of Layer objects.

The layer ids can be passed to other SDK methods, e.g. setLayerVisibility.

Examples

unfoldedMap.getLayers().then((layers) => {
  layers.forEach((layer) => {
    console.log(layer);
  });
});

layers = unfolded_map.get_layers()
# Then, in another cell you can call:
layers.result()

setLayerVisibility

Shows or hides the layer for the provided layer id.

UnfoldedMap.setLayerVisibility(layerId: string, isVisible: boolean): void

UnfoldedMap.set_layer_visibility(layer_id: str, is_visible: bool) -> None:

Parameters

Parameter	Type	Description
`layerId`	`string`	Id of the layer. See getLayers.
`isVisible`	`boolean`	Determines the visibility of the layer. Can be `True` or `False`.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
unfoldedMap.setLayerVisibility("layer-id", true);

unfolded_map.set_layer_visibility(layer_id='layer-id', is_visible=True)

removeLayer

Remove a layer from the map.

UnfoldedMap.removeLayer(id: string): void

UnfoldedMap.remove_layer(layer_id: str) -> None:

Parameters

Parameter	Type	Description
`id`	`string`	UUID of the layer to remove

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
unfoldedMap.removeLayer("my-layer");

unfolded_map.remove_layer('my-layer')

Timeline Functions

This section contains detailed reference documentation covering the Map SDK's timeline functions.

To view each function with a brief description and an example, visit the timeline functions documentation.

setTimelineConfig

Sets time filter timeline configuration that allows us to set timeline visibility, play/pause the animation, set the speed, set the time interval, change the time format and timezone.

UnfoldedMap.setTimelineConfig(
  config: TimelineConfig
): Promise<TimelineConfig>

UnfoldedMap.set_timeline_config(
  config: unfolded.map_sdk.models.TimelineConfig
) -> None:

Types

interface TimeInterval {
  startTime: number;
  endTime: number;
}
interface TimelineConfig {
  idx: number;
  currentTimeInterval?: TimeInterval;
  isVisible?: boolean;
  isAnimating?: boolean;
  speed?: number;
  timezone?: string;
  timeFormat?: string;
}

class TimeInterval:
    start_time: float
    end_time: float
class TimelineConfig:
    idx: int
    current_time_interval: Optional[TimeInterval]
    is_visible: Optional[bool]
    is_animating: Optional[bool]
    speed: Optional[float]
    timezone: Optional[str]
    time_format: Optional[str]

Parameters

Parameter	Prop	Type	Description
`config`	-	TimelineConfig `object`	A `TimelineConfig` configuration object that is used to set the timeline options.
	idx	`int`	Index of the timeline filter you want to control. If there is only one added this will be `0` (zero).
	`isVisible`	`boolean`	Determines the visibility of the timeline. Can be `true` or `false`.
	`isAnimating`	`boolean`	If `true` the animation will play, if `false` the animation will pause.
	`speed`	`float`	Speed multiplier in range `[0 - 10]`.
	`timezone`	`string`	Timezone string value.
	`timeFormat`	`string`	`Moment.js` time format.
	`currentTimeInterval`	TimeInterval `object`	Contains a`startTime` defined as Unix timestamp in milliseconds and an `endTime`defined as Unix timestamp in milliseconds.

Returns

Promise with data defined as TimelineConfig.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
const startTime = new Date("2020.10.29").getTime();
const endTime = new Date("2020.10.31").getTime();
const config = {
  idx: 0,
  currentTimeInterval: {
    startTime: startTime,
    endTime: endTime,
  },
  timezone: "Europe/Berlin",
  timeFormat: "DD.MM.YYYY. HH:mm",
};
unfoldedMap.setTimelineConfig(config).then((data) => {
  console.log(data);
});

from unfolded.map_sdk import UnfoldedMap
unfolded_map=UnfoldedMap(
  mapUUID='4883beab-e8db-42e0-8a66-7093eea255f4'
)
unfolded_map
# ...
unfolded_map.set_layer_timeline_config({
  'current_time': 1567557949266.6873,
  'is_visible': True,
  'is_animating': True,
  'speed': 1,
})

setLayerTimelineConfig

Sets layer timeline configuration used with Trips layer that allows us to set timeline visibility, play/pause the animation, set the speed, set the current time, change the time format and timezone.

UnfoldedMap.setLayerTimelineConfig(config: LayerTimelineConfig): Promise<LayerTimelineConfig>

Not yet supported. Coming soon.

Types

interface LayerTimelineConfig {
  currentTime?: number;
  isVisible?: boolean;
  isAnimating?: boolean;
  speed?: number;
  timezone?: string;
  timeFormat?: string;
}

Not yet supported. Coming soon.

Parameters

Parameter	Prop	Type	Description
`config`	-	TimelineConfig `object`	A `TimelineConfig` configuration object that is used to set the timeline options.
	idx	`int`	Index of the timeline filter you want to control. If there is only one added this will be `0` (zero).
	`isVisible`	`boolean`	Determines the visibility of the timeline. Can be `true` or `false`.
	`isAnimating`	`boolean`	If `true` the animation will play, if `false` the animation will pause.
	`speed`	`float`	Speed multiplier in range `[0 - 10]`.
	`timezone`	`string`	Timezone string value.
	`timeFormat`	`string`	`Moment.js` time format.

Returns

Promise with data defined as LayerTimelineConfig.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
});
const time = new Date("2020.10.29").getTime();
const config = {
  currentTime: time,
  timezone: "Europe/Berlin",
  timeFormat: "DD.MM.YYYY. HH:mm",
};
unfoldedMap.setLayerTimelineConfig(config).then((data) => {
  console.log(data);
});

Not yet supported. Coming soon.

getTimelineInfo

Gets information object for the time filter timeline control.

UnfoldedMap.getTimelineInfo(): Promise<TimelineInfo>

Not yet supported. Coming soon.

Types

interface TimelineInfo {
  dataId: Array<string>;
  domain: Array<number>;
  isVisible: boolean;
  enlargedHistogram: Array<any>;
  histogram: Array<any>;
  value: Array<number>;
  speed: number;
  step: number;
  isAnimating: boolean;
}

Not yet supported. Coming soon.

Parameters

Parameter	Type	Description
`idx`	`int`	Index of the timeline filter you want to control. If there is only one added this will be `0` (zero).

Returns

Promise with data defined as TimelineInfo.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
  appendToDocument: true,
});
unfoldedMap.getTimelineInfo(0).then((data) => {
  console.log(data);
});

Not yet supported. Coming soon.

getLayerTimelineInfo

Gets information object for the layer timeline control used with Trips layer.

UnfoldedMap.getLayerTimelineInfo(): Promise<LayerTimelineInfo>

Not yet supported. Coming soon.

Types

interface LayerTimelineInfo {
  currentTime: number;
  defaultTimeFormat: string;
  domain: Array<number>;
  duration: number;
  isVisible: boolean;
  isAnimating: boolean;
  speed: number;
  timeFormat: string;
  timeSteps: null;
  timezone: string;
}

Not yet supported. Coming soon.

Returns

Promise with data defined as LayerTimelineInfo.

Examples

const unfoldedMap = new UnfoldedMap({
  mapUUID: "MAP-UUID-GOES-HERE",
  embed: true,
  appendToDocument: true,
});
unfoldedMap.getLayerTimelineInfo().then((data) => {
  console.log(data);
});

Not yet supported. Coming soon.

Event Operations

This section contains detailed reference documentation covering the Map SDK's event operations.

To view each function with a brief description and an example, visit the event operations documentation.

setMapEventHandlers

Sets event handlers to receive notifications for the specified map events.

Only one handler per event type can be registered, so subsequent calls will override previously set handlers for the specified event types. This method only updates handlers for those event types which are passed. The others will remain unchanged.

UnfoldedMap.setMapEventHandlers(
  eventHandlers: MapEventHandlers
}): Promise<void>

UnfoldedMap.set_map_event_handlers(
  map_event_handlers: unfolded.map_sdk.models.MapEventHandlers
) -> None

Types

type MapEventHandlers = {
  onLoad?: (() => void) | null,
  onHover?: ((info: HoverEvent) => void) | null,
  onClick?: ((info: ClickEvent) => void) | null,
  onFilter?: ((info: FilterChangeEvent) => void) | null,
  onGeometrySelection?: ((info: GeometrySelectionEvent) => void) | null,
  onTimelineIntervalChange?:
    | ((currentTimeInterval: Array<number>) => void)
    | null,
  onLayerTimelineTimeChange?: ((currentTime: number) => void) | null,
};

class MapEventHandlers:
  on_load: Optional[Callable[[None], None]]
  on_hover: Optional[Callable[[HoverEvent], None]]
  on_click: Optional[Callable[[ClickEvent], None]]
  on_filter: Optional[Callable[[FilterChangeEvent], None]]
  on_geometry_selection: Optional[Callable[[GeometrySelectionEvent], None]]
  on_timeline_interval_change: Optional[Callable[List[int], None]]
  on_layer_timeline_time_change: Optional[Callable[[int], None]]

Parameters

A promise or future.

Parameter	Type	Description
`onLoad`	event handler	Map load event handler
`onHover`	event handler	Map hover event handler
`onClick`	event handler	Map click event handler
`onFilter`	event handler	Map filter changes event handler
`onGeometrySelection`	event handler	Event handler for getting the GeoJSON features of the drawn polygons or rectangles using the Draw tool
`onTimelineIntervalChange`	event handler	Event handler for timeline interval change events. The handler is passed an array of two Unix timestamps as a parameter: `[intervalStartTime, intervalEndTime]` (in milliseconds).
`onLayerTimelineTimeChange`	event handler	Event handler for time change events in the layer timeline. The handler is passed the time as a Unix timestamp (in milliseconds) as a parameter.

Returns

A promise or future.

Examples

onLoad

Fire when map loads.

map.setMapEventHandlers({
  onLoad: () => {
    console.log("Map has loaded");
  },
});

import ipywidgets as widgets
output = widgets.Output()
@output.capture(clear_output=True)
def on_load():
   print('Map loaded')
unfolded_map.set_map_event_handlers({
  'on_load': on_load
})
output

onClick

Fires when the user clicks on the map.

map.setMapEventHandlers({
  onClick: (clickEvent: ClickEvent) => {
    console.log(clickEvent);
  },
});

from unfolded.map_sdk import models
def on_click(event: models.ClickEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_click': on_click
})

onHover

Fires when the cursor is being hovered over the map.

map.setMapEventHandlers({
  onHover: (hoverEvent: HoverEvent) => {
    console.log(hoverEvent);
  },
});

from unfolded.map_sdk import models
def on_hover(event: models.HoverEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_hover': on_hover
})

onGeometrySelection

Fires when the user draws a polygon or rectangle using the draw tool.

map.setMapEventHandlers({
  onGeometrySelection: (geometrySelectionEvent: GeometrySelectionEvent) => {
    console.log(geometrySelectionEvent);
  },
});

from unfolded.map_sdk import models
def on_geometry_selection(event: models.GeometrySelectionEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_geometry_selection': on_geometry_selection
})

onFilter

Fires when map filter changes.

map.setMapEventHandlers({
  onFilter: (filterChangeEvent: FilterChangeEvent) => {
    console.log(filterChangeEvent);
  },
});

from unfolded.map_sdk import models
def on_filter(event: models.FilterChangeEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_filter': on_filter
})

onTimelineIntervalChange

Fires when the timeline interval changes.

map.setMapEventHandlers({
  onTimelineIntervalChange: (timelineInterval) => {
    const startingDateTime = new Date(timelineInterval[0]);
    const endingDateTime = new Date(timelineInterval[1]);
    console.log("Starting datetime: " + startingDateTime);
    console.log("Ending datetime: " + endingDateTime);
  },
});

def on_timeline_interval_change(interval: List[int]):
  start_time = interval[0]
  end_time = interval[1]
  # do something
unfolded_map.set_map_event_handlers({
  'on_timeline_interval_change': on_timeline_interval_change
})

onLayerTimelineTimeChange

Fires when the "current" time change events in the layer timeline.

map.setMapEventHandlers({
  onLayerTimelineTimeChange: (currentDateTimeUnix) => {
    const currentDateTime = new Date(currentDateTimeUnix);
    console.log("Current datetime: " + currentDateTime);
  },
});

def on_layer_timeline_time_change(current_datetime_unix: int):
  # do something
unfolded_map.set_map_event_handlers({
  'on_layer_timeline_time_change': on_layer_timeline_time_change
})

Unregister an Event Handler

To unregister a specific event handler pass, null or undefined (or None in Python) to the appropriate parameter in the setMapEventHandlers function. The other event handlers will remain unchanged.

map.setMapEventHandlers({
  onLayerTimelineTimeChange: null,
  onFilter: null,
});

unfolded_map.set_map_event_handlers({
  'on_timeline_interval_change': None,
  'on_filter': None
})

In case you want to unregister all event handlers, pass null or undefined (or None in Python) to the setMapEventHandlers function.

LoadEvent

A "load event" indicates that an embedded Studio map has completed loading.

Usage

The onLoad function is usually supplied as a parameter to the UnfoldedMap() constructor, however it can also be registered with map.setMapEventHandlers().

map.setMapEventHandlers({
  onLoad: () => {
    console.log("Map has loaded");
  },
});

import ipywidgets as widgets
output = widgets.Output()
@output.capture(clear_output=True)
def on_load():
   print('Map loaded')
unfolded_map.set_map_event_handlers({
  'on_load': on_load
})
output

ClickEvent

A "click event" is sent when the user clicks on the map. The event provides information
on where the click happened, both on the screen and on the map, and which layer and data
row were clicked (if any).

type ClickEvent = {
  index: number /** Data row index */,
  coordinate: [number, number] /** Geospatial coordinates [lng, lat] */,
  x: number /** Mouse position x relative to the viewport. */,
  y: number /** Mouse position y relative to the viewport. */,
  /** The layer id that the clicked object belongs to (Optional) */
  layerId?: string,
  /** The object that was clicked on. (Optional) */
  data?: any,
};

class ClickEvent:
  index: int
  coordinate: Tuple[float, float]
  x: float
  y: float
  layer_id: Optional[str]
  data: Optional[Dict[str, Any]]

Usage

map.setMapEventHandlers({
  onClick: (clickEvent: ClickEvent) => {
    console.log(clickEvent);
  },
});

from unfolded.map_sdk import models
def on_click(event: models.ClickEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_click': on_click
})

Hover Event

A "hover event" is sent when the user hovers over the map. The event provides information
on where the click happened, both on the screen and on the map, and which layer and data
row were clicked (if any).

type HoverEvent = {
  index: number /** Data row index */,
  coordinate: [number, number] /** Geospatial coordinates [lng, lat] */,
  x: number /** Mouse position x relative to the viewport. */,
  y: number /** Mouse position y relative to the viewport. */,
  /** The layer id that the hovered object belongs to (Optional) */
  layerId?: string,
  /** The object that was hovered over. (Optional) */
  data?: any,
};

class HoverEvent:
  index: int
  coordinate: Tuple[float, float]
  x: float
  y: float
  layer_id: Optional[str]
  data: Optional[Dict[str, Any]]

Usage

map.setMapEventHandlers({
  onHover: (hoverEvent: HoverEvent) => {
    console.log(hoverEvent);
  },
});

from unfolded.map_sdk import models
def on_hover(event: models.HoverEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_hover': on_hover
})

GeometrySelectionEvent

A "geometry selection event" is sent when the geometry selection changes. The geometry selection is usually changed by the user using the Draw tool.

The event object contains an array of GeoJSON features representing the new selection. This array can be supplied to other libraries that understand geojson.

type GeometrySelectionEvent = {
  /** Array of drawn GeoJSON shapes */
  features: Feature[],
};
type Feature = {
  /** Unique identifier of the drawn shape */
  id: string,
  /** Type name */
  type: string,
  /** GeoJSON feature properties */
  properties: any,
  /** GeoJSON feature geometry */
  geometry: {
    type: string,
    coordinates: any,
  },
};

class GeometrySelectionEvent:
  features: List[Feature]
class Feature:
  id: str
  type: str
  properties: Any
  geometry: Geometry
class Geometry:
  type: str
  coordinates: Any

Usage

map.setMapEventHandlers({
  onGeometrySelection: (geometrySelectionEvent: GeometrySelectionEvent) => {
    console.log(geometrySelectionEvent);
  },
});

from unfolded.map_sdk import models
def on_geometry_selection(event: models.GeometrySelectionEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_geometry_selection': on_geometry_selection
})

FilterChangeEvent

A "filter change event" is sent when data filters are updated in the map.

type FilterChangeEvent = {
  id: string /** Filter ID */,
  name: string[] /** Field names the filter applies to */,
  dataId: string /** Dataset UUID */,
  prop /** Filter property that was changed */: "value" | "name" | string,
  type /** Filter type */:
    | "range"
    | "select"
    | "input"
    | "timeRange"
    | "multiSelect"
    | "polygon",
  value: any /** Value of the filter */,
};

class FilterChangeEvent:
  id: str
  name: List[str]
  dataId: UUID
  prop: str
  type: FilterType
  value: FilterValueType

Usage

map.setMapEventHandlers({
  onFilter: (filterChangeEvent: FilterChangeEvent) => {
    console.log(filterChangeEvent);
  },
});

from unfolded.map_sdk import models
def on_filter(event: models.FilterChangeEvent):
  # do something
unfolded_map.set_map_event_handlers({
  'on_filter': on_filter
})

TimelineIntervalChangeEvent

Event handler for timeline interval change events. The handler is passed an array of two Unix timestamps as a parameter: [intervalStartTime, intervalEndTime] (in milliseconds).

Usage

map.setMapEventHandlers({
  onTimelineIntervalChange: (timelineInterval) => {
    const startingDateTime = new Date(timelineInterval[0]);
    const endingDateTime = new Date(timelineInterval[1]);
    console.log("Starting datetime: " + startingDateTime);
    console.log("Ending datetime: " + endingDateTime);
  },
});

def on_timeline_interval_change(interval: List[int]):
  start_time = interval[0]
  end_time = interval[1]
  # do something
unfolded_map.set_map_event_handlers({
  'on_timeline_interval_change': on_timeline_interval_change
})

LayerTimelineChangeEvent

Time change events are sent when the layer timeline.

The event object includes the time as a Unix timestamp (in milliseconds) as a parameter.

Usage

map.setMapEventHandlers({
  onLayerTimelineTimeChange: (currentDateTimeUnix) => {
    const currentDateTime = new Date(currentDateTimeUnix);
    console.log("Current datetime: " + currentDateTime);
  },
});

def on_layer_timeline_time_change(current_datetime_unix: int):
  # do something
unfolded_map.set_map_event_handlers({
  'on_layer_timeline_time_change': on_layer_timeline_time_change
})