Dataset Functions

addDataset

Python: add_dataset

Add a local tabular or tiled dataset object to the map.

addDataset(
  dataset: DatasetCreationProps,
  options?: AddDatasetOptions
): Dataset;

add_dataset(
  self,
  dataset: Union[Dataset, Dict, None] = None,
  *,
  auto_create_layers: bool = True,
  center_map: bool = True,
  **kwargs: Any,
) -> Optional[Dataset]

Javascript

Arguments

Argument	Type	Description
`dataset`	`DatasetCreationProps`	Data used to create a dataset, in CSV, JSON, GeoJSON format (for local datasets), or a UUID string.
`options`	`AddDatasetOptions`	Options applicable when adding a new dataset.

Returns

Returns the Dataset object that was added to the map.

Python

Positional Arguments

Argument	Type	Description
`dataset`	`Union[`Dataset`, Dict, None]`	Data used to create a dataset, in CSV, JSON, or GeoJSON format (for local datasets) or a UUID string.

Keyword Arguments

Argument	Type	Description
`auto_create_layers`	`bool`	Whether to attempt to create new layers when adding a dataset. Defaults to `True`.
`center_map`	`bool`	Whether to center the map on the created dataset. Defaults to `True`.
`id`	`str`	Unique identifier of the dataset. If not provided, a random id will be generated.
`label`	`str`	Displayable dataset label.
`color`	`Tuple[float, float, float]`	Color label of the dataset.
`metadata`	`dict`	Object containing tileset metadata (for tiled datasets).

Returns

Returns the Dataset object that was added to the map.

Examples

// Assume dataset is a valid dataset

map.addDataset({
  id: "test-dataset-01",
  label: "Cities",
  color: [245, 166, 35],
  data: datasetData
},
{
  autoCreateLayers: true,
  centerMap: true
}
)

# Assume df is a valid dataframe

map.add_dataset({
    "id": "test-dataset-01",
    "label": "Cities",
    "color": [245, 166, 35],
    "data": df 
  },
  auto_create_layers = True,
  center_map = True
)

addTileDataset

Adds a new remote dataset to the map, fetching dataset information from the appropriate URL.

addTileDataset(
  dataset: TileDatasetCreationProps,
  options?: AddDatasetOptions
): Promise<Dataset>;`

add_tile_dataset(
  self,
  dataset: Union[Dataset, Dict, None] = None,
  *,
  auto_create_layers: bool = True,
  center_map: bool = True,
  **kwargs: Any,
) -> Dataset:

Javascript

Arguments

Argument	Type	Description
`dataset`	`TileDatasetCreationProps`	The dataset to add.
`options`	`AddDatasetOptions`	Optional map settings for the new dataset.

Returns

Returns a promise with the Dataset object that was added to the map.

Python

Positional Arguments

Argument	Type	Description
`dataset`	`[Union[`Dataset`, Dict, None]`	The dataset to add.

Keyword Arguments

Argument	Type	Description
`auto_create_layers`	`bool`	Whether to attempt to create new layers when adding a dataset. Defaults to `True`.
`center_map`	`bool`	Whether to center the map on the created dataset. Defaults to `True`.
`id`	`str`	Unique identifier of the dataset. If not provided, a random id will be generated.
`label`	`str`	Displayable dataset label.
`color`	`Tuple[float, float, float]`	Color label of the dataset.
`metadata`	`dict`	Object containing tileset metadata (for tiled datasets).

Returns

Returns a promise with the Dataset object that was added to the map.

Examples

map.addTileDataset(
  {
    id: 'foo',
    type: 'raster-tile',
    label: 'Dataset',
    color: [0, 92, 255],
    metadata: {
      // NOTE: This must be a live, reachable URL
      metadataUrl: 'https://path.to.metadata.json'
    }
  },
  {
    autoCreateLayers: true,
    centerMap: true
  }
)

# Initializing a dataset object
dataset = {
  "id": "dataset-id",
  "type": "vector-tile",
  "label": "dataset-label",
  "metadata": {
      "metadata_url": "http://example.com",
  },
}

map.add_tile_dataset(
    dataset,
    auto_create_layers = True,
    center_map = True
)

getDatasetById

Retrieves a dataset by its identifier if it exists.

getDatasetById(
  datasetId: string
): Dataset | null;

get_dataset_by_id(
  self,
  dataset_id: str
) -> Optional[Dataset]:

Javascript

Arguments

Argument	Type	Description
`datasetId`	`string`	The identifier of the dataset to retrieve.

Returns

Returns a Dataset object associated with the identifier, or null if no matching dataset was retrieved.

Python

Arguments

Argument	Type	Description
`dataset_id`	`string`	The identifier of the dataset to retrieve.

Returns

Returns a Dataset object associated with the identifier, or null if no matching dataset was retrieved.

Examples

dataset = map.getDatasetById('test-dataset-01');

dataset = map.get_dataset_by_id("test-dataset-01")

getDatasetWithData

Retrieves a dataset record with its data for a given dataset if it exists.

getDatasetWithData(
  datasetId: string
): DatasetWithData | null;`}

get_dataset_with_data(
  self,
  dataset_id: str
) -> Optional[DatasetWithData]

Javascript

Arguments

Argument	Type	Description
`datasetId`	`string`	The identifier of the dataset to retrieve.

Returns

Returns a DatasetWithData record along with its data associated with the identifier, or null if no matching dataset was retrieved.

Python

Argument	Type	Description
`dataset_id`	`string`	The identifier of the dataset to retrieve.

Returns

Returns a DatasetWithData record along with its data associated with the identifier, or null if no matching dataset was retrieved.

Examples

dataset = map.getDatasetWithData('test-dataset-01');

dataset = map.get_dataset_with_data('test-dataset-01')

getDatasets

Python: get_datasets

Gets all the datasets currently available in the map.

getDatasets(): Dataset[];

get_datasets(self) -> List[Dataset]

Returns

Returns an array of Dataset objects associated with the map.

Examples

datasets = map.getDatasets();

datasets = map.get_datasets()

removeDataset

Python: remove_dataset

Removes a specified dataset from the map.

removeDataset(
  datasetId: string
): void;

remove_dataset(
  self,
  dataset_id: str
)-> None

Javascript

Arguments

Argument	Type	Description
`datasetId`	`string`	The identifier of the dataset to remove.

Python

Argument	Type	Description
`dataset_id`	`string`	The identifier of the dataset to remove.

Examples

map.removeDataset('test-dataset-01');

map.remove_dataset('test-dataset-01')

replaceDataset

Python: replace_dataset

Replaces a given dataset with a new one.

replaceDataset(
  thisDatasetId: string,
  withDataset: DatasetCreationProps
  options?: ReplaceDatasetOptions
): Dataset;

replace_dataset(
  self,
    this_dataset_id: str,
    with_dataset: Union[Dataset, Dict, None] = None,
    *,
    force: bool = False,
    strict: bool = False,
    **kwargs: Any,
) -> Dataset

Javascript

Arguments

Argument	Type	Description
`thisDatasetId`	`string`	Identifier of the dataset to replace.
`withDataset`	`DatasetCreationProps`	Dataset details to replace the dataset with.
`options`	`ReplaceDatasetOptions`	Options available for dataset replacement.

Returns

Returns the Dataset object that is now in use.

Python

Arguments

Argument	Type	Description
`this_dataset_id`	`string`	Identifier of the dataset to replace.
`with_dataset`	`Union[Dataset, Dict, None]`	Dataset details to replace the dataset with.
`force`	`bool`	Whether to force a dataset replace, even if the compatibility check fails. Default: `false`.
`strict`	`bool`	Whether to ensure strict equality of types for each field being replaced. Default: `false`.

Returns

Returns the Dataset object that is now in use.

Examples

// suppose newDataset is a valid Dataset object
map.replaceDataset('old-dataset-01', newDataset);

## new_dataset is a valid Dataset object
  map.replace_dataset('old-dataset-01', new_dataset)

updateDataset

Python: update_dataset

Updates an existing dataset's settings.

updateDataset(
  datasetId: string,
  values: DatasetUpdateProps
): Dataset;

update_dataset(
    self,
    dataset_id: str,
    values: Union[_DatasetUpdateProps, dict, None] = None,
    **kwargs: Any,
) -> Dataset

Javascript

Arguments

Argument	Type	Description
`datasetId`	`string`	The identifier of the dataset to update.
`values`	`DatasetUpdateProps`	The values to update.

Returns

Returns the updated Dataset object.

Python

Positional Arguments

Argument	Type	Description
`dataset_id`	`string`	The identifier of the dataset to update.
`values`	`Union[_DatasetUpdateProps, dict, None]`	The values to update.

Keyword Arguments

Argument	Type	Description
`label`	`str`	Displayable dataset label.
`color`	`RGBColor`	Color label of the dataset.

Returns

For non-interactive (i.e. pure HTML) maps, nothing is returned.

Returns the updated Dataset object for interactive maps, or None for non-interactive HTML environments.

Examples

map.updateDataset(
  "test-dataset-01",
  {
    label: "Dataset",
    color: [245, 166, 35],
  }
);

map.update_dataset(
  "test-dataset-01",
  {
    "label": "Dataset",
    "color": [245, 166, 35],
  }
)

Filter Functions

addFilter

Python: add_filter

Add a filter to the map.

addFilter(filter: FilterCreationProps): Filter

add_filter(
  self,
  filter: Union[FilterCreationProps, dict, None] = None,
  **kwargs: Any,
) -> Filter:

Javascript

Arguments

Argument	Type	Description
`filter`	`FilterCreationProps`	The filter to add.

Returns

Returns the Filter object that was added to the map.

Python

Positional Arguments

Argument	Type	Description
`filter`	`Union[`FilterCreationProps`, dict, None]`	The filter to add.

Returns

Returns the Filter object that was added to the map.

Examples

map.addFilter({
  "type": "range",
  "sources": [
    {
      "dataId": "test-dataset-filter",
      "fieldName": "Magnitude"
    }
  ],
  "value": [
    4,
    5
  ]
});

# Creating a filter
filter = {
  "type": "range",
  "sources": [{"data_id": DATASET_UUID, "field_name": "test"}],
  "value": (0, 100)
}
# Adding the filter to the map
map.add_filter(
  filter
)

getFilterById

Python: get_filter_by_id

Retrieves a filter by its identifier if it exists.

getFilterById(
  filterId: string
): Filter | null;

get_filter_by_id(
  self,
  filter_id: str
) -> Optional[Filter]`}

Javascript

Arguments

Argument	Type	Description
`filterId`	`string`	Identifier of the filter to get.

Returns

Returns a Filter object associated a given identifier, or null if one doesn't exist.

Python

Arguments

Argument	Type	Description
`filter_id`	`string`	Identifier of the filter to get.

Returns

Returns a Filter object associated a given identifier, or null if one doesn't exist.

Examples

filter = map.getFilterById('test-filter-01');

filter = map.get_filter_by_id('test-filter-01')

getFilters

Python: get_filters

Gets all the filters currently available in the map.

getFilters(): Filter[];

get_filters(self) -> List[Filter]

Returns

Returns an array of Filter objects.

Examples

filters = map.getFilters();

filters = map.get_filters()

removeFilter

Python: remove_filter

Removes a filter from the map.

removeFilter(
  filterId: string
): void;

remove_filter(
  self,
  filter_id: str
) -> None

Javascript

Arguments

Argument	Type	Description
`filterId`	`string`	The id of the filter to remove.

Python

Arguments

Argument	Type	Description
`filterId`	`string`	The id of the filter to remove.

Examples

map.removeFilter('test-filter-01');

map.remove_filter('test-filter-01')

updateFilter

Python: update_filter

Updates an existing filter with given values.

updateFilter(
  filterId: string,
  values: FilterUpdateProps
): Filter;`

update_filter(
  self,
  filter_id: str,
  values: Union[FilterUpdateProps, dict, None] = None,
  **kwargs: Any,
) -> Filter

Javascript

Arguments

Argument	Type	Description
`filterId`	`string`	The id of the filter to update.
`values`	`FilterUpdateProps`	The new filter values.

Returns

Returns the updated Filter object.

Python

Arguments

Argument	Type	Description
`filter_id`	`string`	The id of the filter to update.
`values`	`Union[FilterUpdateProps, dict, None]`	The new filter values.

Returns

Returns the updated Filter object.

Examples

map.addFilter('test-filter-1',{
  "type": "range",
  "sources": [
    {
      "dataId": "test-dataset-filter",
      "fieldName": "Magnitude"
    }
  ],
  "value": [
    5,
    6
  ]
})

# Creating a filter
filter = {
  "type": "range",
  "sources": [{"data_id": DATASET_UUID, "field_name": "test"}],
  "value": (0, 100)
}
# Updating the existing filter on the map
map.add_filter(
  "test-filter-1", filter
)

updateTimeline

Python: update_timeline

Updates a time range filter timeline with given values.

updateTimeline(
  filterId: string,
  values: FilterTimelineUpdateProps
): TimeRangeFilter;

update_timeline(
  self,
  filter_id: str,
  values: Union[FilterTimelineUpdateProps, dict, None] = None,
  **kwargs: Any,
) -> TimeRangeFilter

Javascript

Arguments

Argument	Type	Description
`filterId`	`string`	The id of the time range filter to update.
`values`	`FilterTimelineUpdateProps`	The new layer timeline values.

Returns

Returns the updated TimeRangeFilter object.

Python

Positional Arguments

Argument	Type	Description
`filter_id`	`string`	The id of the time range filter to update.
`values`	`(Union[`,`FilterTimelineUpdatePropsdict, None]`	The new layer timeline values.

Keyword Arguments

Argument	Type	Description
`view`	`FilterView`	Current timeline presentation.
`time_format`	`string`	Time format that the timeline is using in day.js supported format. Reference: https://day.js.org/docs/en/display/format
`timezones`	`string`	Timezone that the timeline is using in tz format. Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
`is_animating`	`bool`	Flag indicating whether the timeline is animating or not.
`animation_speed`	`Number`	Speed at which timeline is animating.

Returns

Returns the updated TimeRangeFilter object.

Examples

map.updateTimeline('test-timeline-1', {
  timeFormat: 'DD/MM/YYYY',
  isAnimating: false
});

map.update_timeline(
  "test-timeline-1",
  {
    "time_format": "DD/MM/YYYY",
    "is_animating": False
  }
)

Layer Functions

addLayer

Python: add_layer

Add a new layer to the map. This function requires at least one valid layer configuration to be supplied.

To learn about configuring a specific layer programmatically, visit Layer Configuration documentation.

addLayer(
  layer: LayerCreationProps
): Layer;

add_layer(
    self,
    layer: Union[LayerCreationProps, dict, None] = None,
    **kwargs: Any
) -> Layer

Javascript

Arguments

Argument	Type	Description
`layer`	`LayerCreationProps`	A set of properties used to create a layer.

Returns

The Layer object that was added to the map.

Python

Arguments

Argument	Type	Description
`layer`	`Union[LayerCreationProps, dict, None]`	A set of properties used to create a layer.

Returns

The Layer object that was added to the map.

Examples

map.addLayer({
  id: 'test-layer-01',
  type: 'point',
  dataId: 'test-dataset-01',
  label: 'New Layer',
  isVisible: true,
  fields: {
    lat: 'latitude',
    lng: 'longitude'
  },
  config: {
    visualChannels: {
      colorField: {
        name: 'cityName',
        type: 'string'
      },
      colorScale: 'ordinal'
    }
  }
});

map.add_layer({
  "id": "test-layer-01",
  "type": "point",
  "data_id": "test-dataset-01",
  "label": "New Layer",
  "is_visible": True,
  "fields": {
    "lat": "latitude",
    "lng": "longitude"
  },
  "config": {
    "visual_channels": {
      "color_field": {
        "name": "city_name",
        "type": "string"
      },
      "color_scale": "ordinal"
    }
  }
})

addLayerGroup

Python: add_layer_group

Adds a new layer group to the map.

addLayerGroup(layerGroup: LayerGroup): LayerGroup;

add_layer_group(
  self,
  layer_group: Union[LayerGroup, dict, None] = None,
  **kwargs: Any
) -> Optional[LayerGroup]:

Returns

Returns the LayerGroup object added to the map.

Examples

map.addLayerGroup({
  id: 'layer-group-1',
  label: 'Layer Group 1',
  isVisible: true,
  layerIds: ['layer1', 'layer2', 'layer3']
});

map.add_layer_group(
  {
    "id": "layer-group-1",
    "label": "Layer Group 1",
    "is_visible": True,
    "layer_ids": ["layer1", "layer2", "layer3"]
  }
)

getLayerById

Python: get_layer_by_id

Retrieves a layer by its identifier if it exists.

getLayerById(
  layerId: string
): Layer | null;

def get_layer_by_id(
  self,
  layer_id: str
) -> Optional[Layer]

Javascript

Arguments

Parameter	Type	Description
`layerId`	`string`	Identifier of the layer to get.

Python

Arguments

Parameter	Type	Description
`layer_id`	`string`	Identifier of the layer to get.

Returns

Returns the Layer object associated with the identifier, or null if one doesn't exist.

Examples

layer = map.getLayerById('test-layer-01');

layer = map.get_layer_by_id('test-layer-01')

getLayerGroupById

Python: get_layer_group_by_id

Retrieves a layer group by its identifier if it exists.

getLayerGroupById(layerGroupId: string): LayerGroup | null;

get_layer_group_by_id(self, layer_group_id: str) -> Optional[LayerGroup]:

Returns

Returns a LayerGroup associated with the identifer, or null if one doesn't exist.

Examples

layerGroup = map.getLayerGroupById('layer-group-1');

layer_group = map.get_layer_group_by_id("layer-group-1")

getLayerGroups

Python: get_layer_groups

Gets all the layer groups currently available in the map.

getLayerGroups(): LayerGroup[];

get_layer_groups(self) -> List[LayerGroup]

Returns

Returns an array of LayerGroup objects associated with the map.

Examples

layerGroups = map.getLayerGroups();

layer_groups = map.get_layer_groups()

getLayerTimeline

Python: get_layer_timeline

Gets all the layers currently available in the map.

getLayerTimeline(): LayerTimeline | null;

get_layer_timeline(self) -> Optional[LayerTimeline]:

Returns

Returns a LayerTimeLine object associated with the map.

Examples

layerTimeline = map.getLayerTimeline();

layer_timeline = map.get_layer_timeline()

getLayers

Python: get_layers

Gets all the layers currently available in the map.

getLayers(): Layer[];

get_layers(self) -> List[Layer]

Returns

Returns an array of Layer objects associated with the map.

Examples

layers = map.getLayers();

layers = map.get_layers()

getLayerTimeline

Python: get_layer_timeline

Gets all the layers currently available in the map.

getLayerTimeline(): LayerTimeline | null;

get_layer_timeline(self) -> Optional[LayerTimeline]:

Returns

Returns a LayerTimeLine object associated with the map.

Examples

layerTimeline = map.getLayerTimeline();

layer_timeline = map.get_layer_timeline()

removeLayer

Python: remove_layer

Removes a layer from the map.

removeLayer(
  layerId: string
): void;

remove_layer(
  self,
  layer_id: str
) -> None

Javascript

Arguments

Argument	Type	Description
`layerId`	`string`	The id of the layer to remove.

Python

Arguments

Argument	Type	Description
`layer_id`	`string`	The id of the layer to remove.

Examples

map.removeLayer('test-layer-01');

map.remove_layer('test-layer-01')

removeLayerGroup

Python: remove_layer_group

Removes a layer group from the map. This operation does not remove the layers itself; only the layer group.

removeLayerGroup(layerGroupId: string): void;

remove_layer_group(self, layer_group_id: str) -> None:

Examples

map.removeLayerGroup('layer-group-1');

remove_layer_group(self, layer_group_id: str) -> None:

updateLayer

Python: update_layer

Updates an existing layer with given values.

updateLayer(
  layerId: string,
  values: LayerUpdateProps
): Layer;

update_layer(
  self,
  layer_id: str,
  values: Union[LayerUpdateProps, dict, None],
  **kwargs: Any
) -> Layer

Javascript

Arguments

Argument	Type	Description
`layerId`	`string`	The id of the layer to update.
`values`	`LayerUpdateProps`	The values to update.

Returns

Returns the updated Layer object.

Python

Positional Arguments

Argument	Type	Description
`layer_id`	`string`	The id of the layer to update.
`values`	`Union[LayerUpdateProps, dict, None]`	The values to update.

Keyword Arguments

Argument	Type	Description
`type`	`LayerType`	The type of layer.
`data_id`	`string`	Unique identifier of the dataset this layer visualizes.
`fields`	`Dict [string, Optional[string]]`	Dictionary that maps fields that the layer requires for visualization to appropriate dataset fields.
`label`	`string`	Canonical label of this layer
`is_visible`	`bool`	Whether the layer is visible or not.
`config`	`LayerConfig`	Layer configuration specific to its type.

Returns

Returns the updated Layer object.

Examples

map.updateLayer({
  type: 'point',
  dataId: 'test-dataset-01',
  label: 'Updated Layer',
  isVisible: true,
  fields: {
    lat: 'latitude',
    lng: 'longitude',
    alt: 'altitude'
  },
  config: {
    visualChannels: {
      colorField: {
        name: 'cityName',
        type: 'string'
      }
    },
    visConfig: {
      radius: 10,
      fixedRadius: false,
      opacity: 0.8,
      outline: false,
      thickness: 2
    }
  }
});

map.update_layer(
  {
  "type": "point",
  "data_id": "test-dataset-01",
  "label": "Updated Layer",
  "is_visible": True,
  "fields": {
    "lat": "latitude",
    "lng": "longitude",
    "alt": "altitude"
  },
  "config": {
    "visual_channels": {
      "color_field": {
        "name": "city_name",
        "type": "string"
      },
    },
    "vis_config": {
      "radius": 10,
      "fixed_radius": False,
      "opacity": 0.8,
      "outline": False,
      "thickness": 2
    }
  }
})

updateLayerGroup

Python: update_layer_group

Updates an existing layer group with given values.

map.updateLayerGroup(
    "layer-group-1",
    {
      id: "layer-group-1",
      label: "Layer Group 1",
      isVisible: false,
      layerIds: ["layer1", "layer2". "layer3"]
    }
);

map.update_layer_group(
    "layer-group-1",
    {
      "id": "layer-group-1",
      "label": "Layer Group 1",
      "is_visible": False,
      "layers": ["layer1", "layer2". "layer3"]
    }
)

Returns

Returns the updated LayerGroup.

Examples

map.updateLayerGroup(
    "layer-group-1",
    {
      id: "layer-group-1",
      label: "Layer Group 1",
      isVisible: false,
      layerIds: ["layer1", "layer2". "layer3"]
    }
);

map.updateLayerGroup(
    "layer-group-1",
    {
      "id": "layer-group-1",
      "label": "Layer Group 1",
      "is_visible": False,
      "layers": ["layer1", "layer2". "layer3"]
    }
)

updateLayerTimeline

Python: update_layer_timeline

Updates the current layer timeline configuration.

map.updateLayerTimeline({
    currentTime: 1660637600498,
    isAnimating: true,
    isVisible: true,
    animationSpeed: 1,
    timeFormat: "YYYY-MM-DDTHH:mm:ss",
    timezone: "America/Los_Angeles"
  }
);

map.update_layer_timeline({
    "current_time": 1660637600498,
    "is_animating": True,
    "is_visible": True,
    "animation_speed": 1,
    "time_format": "YYYY-MM-DDTHH:mm:ss",
    "timezone": "America/Los_Angeles"
  })

Javascript

Arguments

Argument	Type	Description
`values`	`LayerTimelineUpdateProps`	The new layer timeline values.

Returns

Returns the updated LayerTimeline object.

Python

Positional Arguments

Argument	Type	Description
`values`	`(Union[`,`LayerTimelineUpdatePropsdict, None]`	The new layer timeline values.

Keyword Arguments

Argument	Type	Description
`current_time`	`Number`	Current time on the timeline in milliseconds
`is_animating`	`bool`	Flag indicating whether the timeline is animating or not.
`is_visibile`	`bool`	Flag indicating whether the timeline is visible or not
`animation_speed`	`Number`	Speed at which timeline is animating.
`time_format`	`string`	Time format that the timeline is using in day.js supported format. Reference: https://day.js.org/docs/en/display/format
`timezone`	`string`	Timezone that the timeline is using in tz format. https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Returns

Returns the updated LayerTimeline object.

Examples

map.updateLayerTimeline({
    currentTime: 1660637600498,
    isAnimating = true,
    isVisible = true,
    animationSpeed = 1,
    timeFormat = "YYYY-MM-DDTHH:mm:ss",
    timezone = "America/Los_Angeles"
  }
);

map.update_layer_timeline({
    "current_time": 1660637600498,
    "is_animating" = True,
    "is_visible" = True,
    "animation_speed" = 1,
    "time_format" = "YYYY-MM-DDTHH:mm:ss",
    "timezone" = "America/Los_Angeles"
  })

Map Functions

addToDOM

Javascript-exclusive function.

Adds a map into a container element provided as an argument.

Note: This is normally done in the constructor and does not need to be called explicitly.

addToDOM(
  container: HTMLElement,
  style?: CSSProperties
): void;

Javascript

Arguments

Argument	Type	Description
`container`	`HTMLElement`	The container element to embed the map into.
`style`	`CSSProperties`	An optional set of CSS properties.

Returns

Returns the container element to embed the map into.

Examples

map.addToDOM(container, foo.style);

addEffect

Python: add_effect

Add a new visual post-processing effect to the map.

addEffect(
  effect: EffectCreationProps
): Effect;

add_effect(
  effect: Union[_EffectCreationProps, dict, None] = None,
) -> Optional[Effect]:

Javascript

Arguments

Argument	Type	Description
`effect`	`EffectCreationProps`	A set of properties used to create an effect.

Returns

Returns the effect that was added.

Python

Argument	Type	Description
`effect`	`EffectCreationProps`	A set of properties used to create an effect.

Returns

Examples

map.addEffect({
  id: "example-effect",
  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({
  "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",
  },
})

createMap

Python: create_map

Creates a new map instance based on given Arguments.

createMap(
  props: MapCreationProps
): Promise<MapApi>

create_map(
    *,
    renderer: Literal["html", "widget", None] = None,
    **kwargs: Any
) -> Union[HTMLMap, SyncWidgetMap]:

Javascript

Arguments

Argument	Type	Description
`props`	`MapCreationProps`	A set of properties used to create a layer.

Returns

Returns a new map instance that can be interacted with.

Python

Arguments

Argument	Type	Description
`renderer`	`string`	The rendering method to use for map rendering, either `"html"` or `"widget"`. Defaults to `None`, automatically rendering a widget unless a Databricks environment is detected.

Keyword Arguments

Keyword arguments reflect the parameters found in SyncWidgetMap or most of the parameters found in HTMLMap:

Argument	Type	Description
`style`	`Dict`	Optional map container CSS style customization. Uses camelCase as this is React standard.
`basemaps`	`Dict`	Basemap customization settings.
`basemaps["custom_map_styles"]`	`List[MapStyleCreationProps]`	A set of properties required when specifying a map style.
`basemaps["initial_map_styles"]`	`string`	A mapbox style ID.
`raster`	`Dict`	Customization related to raster datasets and tiles. Not available when `renderer = "html"`.
`raster.server_urls`	`List[string]`	URLs to custom servers to target when serving raster tiles.
`raster.stac_search_url`	`string`	URL to pass to the backend for searching a STAC Collection.
`urls`	`Dict`	Customization of URLs used in the application.
`urls.static_asset_url_base`	`string`	Custom URL base for static assets.
`urls.application_url_base`	`string`	Custom URL base for workers and other script resources loaded by the SDK.

Note: HTML rendering is provided for those working in a Databricks environment. While using this rendering method, API endpoints will not provide any return values. Using the default "widget" rendering method is strongly suggested.

Returns

Returns a SyncWidgetMap for most notebook environments, or an HTMLMap object for a Databricks environment or when renderer = "html".

Examples

const map = createMap();

map = create_map()

getEffectByID

Python: get_effect_by_id

Retrieves a visual effect from the map.

getEffectById(effectId: string): Effect | null;

get_effect_by_id(effect_id: str) -> Optional[Effect]:

Returns

Returns the effect associated with the ID.

Examples

effect = map.getEffectByID();

effect = map.get_effect_by_id()

getEffects

Python: get_effects

Retrieves all visual effects from the map.

getEffects(): Effect[];

get_effects(self) -> List[Effect]:

Returns

Returns an array of effects added to the map.

Examples

effects = map.getEffects();

effects = map.get_effects()

getMapConfig

Python: get_map_config

Gets the configuration representing the current map state.

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

getMapConfig(): unknown;

get_map_config(self) -> dict:

Returns

Returns the map configuration file.

Examples

mapConfig = map.getMapConfig();

map_config = map.get_map_config()

getMapControlVisibility

Python: get_map_control_visibility

Gets the current map control visibility settings.

getMapControlVisibility(): MapControlVisibility;

get_map_control_visibility(self) -> MapControlVisibility

Returns

Returns a MapControlVisibility object containing current map control visibility settings.

Examples

mapVisibilitySettings = map.getMapControlVisibility();

map_visibility_settings = map.get_map_control_visibility()

getMapStyles

Python: get_map_styles

Gets the current map control visibility settings.

getMapStyles(): MapStyle[];

get_map_styles(self) -> List[MapStyle]

Returns

Returns an array of MapStyle objects.

Examples

mapStyles = map.getMapStyles();

map_styles = map.get_map_styles()

getSplitMode

Python: get_split_mode

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

getSplitMode(): SplitModeProps;

get_split_mode(self) -> SplitModeProps

Returns

Returns a SplitModeProps object containing split mode settings for each associated layers.

Examples

splitMode = map.getSplitMode();

split_mode = map.get_split_mode();

getView

Python: get_view

Gets the current view state of the map.

getView(): View;

get_view(self) -> View

Returns

Returns a View object containing view state settings.

Examples

view = map.getView();

view = map.get_view()

getViewLimits

Python: get_view_limits

Gets the current view limits of the map.

getViewLimits(): ViewLimits;

get_view_limits(self) -> ViewLimits

Returns

Returns a ViewLimits object containing the view limits setting of the map.

Examples

viewLimits = map.getViewLimits();

view_limits = map.get_view_limits()

getViewMode

Python: get_view_mode

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

getViewMode(): ViewMode;

get_view_mode(self) -> ViewMode

Returns

Returns a ViewMode object containing the view mode setting of the map.

Examples

viewMode = map.getViewMode();

view_mode = map.get_view_mode()

remove_event_handlers

Python exclusive function.

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

remove_event_handlers(
  self, event_handlers: Sequence[str]
) -> None:

Arguments

Argument	Type	Description
`event_handlers`	`Sequence[string]`	A list of event handlers to remove. Passed in as a list of strings.

Examples

map.remove_event_handlers(["on_view_update"])

set_event_handlers

Python exclusive function.

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

set_event_handlers(
  self, event_handlers: Union[dict, EventHandlers, None], **kwargs: Any
) -> None:

Arguments

Argument	Type	Description
`event_handlers`	`MapEventHandlers`, `LayerEventHandlers`, `FilterEventHandlers`, `dict`	Event handlers to set. Can be passed as in through the aforementioned objects, as a dict, or through keyword arguments.

Examples

map.set_event_handlers(on_view_update = do_something)

setMapConfig

Python: set_map_config

Loads the given configuration into the current map.

setMapConfig(
  config: object,
  options?: SetMapConfigOptions
): void;

set_map_config(
  self,
  config: dict,
  options: Optional[Union[dict, SetMapConfigOptions]] = None
) -> None:

Javascript

Arguments

Argument	Type	Description
`config`	`object`	Configuration to load into the map. For details around the format see the map format reference.
`options`	`SetMapConfigOptions`	A set of options for the map configuration.

Python

Arguments

Argument	Type	Description
`config`	`dict`	Configuration to load into the map. For details around the format see the map format reference.
`options`	`Union[dict,SetMapConfigOptions]`	A set of options for the map configuration.

Examples

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": {}
    }
  }

setMapControlVisibility

Python: set_map_control_visibility

setMapControlVisibility(
  visibility: Partial<MapControlVisibility>
): MapControlVisibility;

set_map_control_visibility(
  self,
  visibility: Union[MapControlVisibility, dict, None] = None,
  **kwargs: bool
) -> MapControlVisibility

Javascript

Arguments

Argument	Type	Description
`visibility`	`MapControlVisibility`	The new map control visibility settings.

Returns

Returns a MapControlVisibility object containing the updated map control visibility settings.

Python

Positional Arguments

Argument	Type	Description
`visibility`	`Union[MapControlVisibility, dict, None]`	MapControlVisibility model instance or a dict with the same attributes, all optional.

Keyword Arguments

Argument	Type	Description
`legend`	`bool`	Whether the legend is visible.
`toggle_3d`	`bool`	Whether the 3D toggle is visible.
`split_map`	`bool`	Whether the split map button is visible.
`map_draw`	`bool`	Whether the map draw button is visible.

Returns

Returns a MapControlVisibility object containing the updated map control visibility settings.

Examples

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

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

setSplitMode

Python: set_split_mode

Sets the split mode of the map.

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

options = {
    "layers": [['left_layer'], ['right_layer']],
    "is_view_synced": True,
    "is_zoom_synced": True,
}
map.set_split_mode("swipe", options)

Javascript

Arguments

Argument	Type	Description
`splitMode`	`SplitMode`	Split map mode with associated layers.
`options`	`Partial<SplitModeContext>`	A set of options to use when setting the split mode.

Returns

Returns a SplitModeDetails object containing the updated split mode of the map along with its associated layers.

Python

Positional Arguments

Argument	Type	Description
`split_mode_props`	`SplitModeProps`	Split map mode with associated layers.

Keyword Arguments

Argument	Type	Description
`mode`	`SplitMode`	Split map mode with associated layers.
`layers`	`SplitLayers`	Arrays with layer Ids per each post-split map section.

Returns

Returns a SplitModeProps object containing the updated split mode of the map along with its associated layers, or null for

Examples

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

map.set_split_mode(
  mode = "swipe",
  layers: ["left_layer", "right_layer"]
)

setTheme

Python: set_theme

Sets the UI theme of the map.

setTheme(
  theme: ThemeUpdateProps
): void;

set_theme(
  self,
  *,
  preset: Optional[ThemePresets] = None,
  background_color: Optional[str] = None,
) -> None

Javascript

Arguments

Argument	Type	Description
`theme`	`ThemeUpdateProps`	New UI theme settings.

Python

Arguments

Argument	Type	Description
`preset`	`ThemePresets`	A preset theme, either "light" or "dark"
`background_color`	`string`	Optional. A background color.

Examples

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

map.set_theme(
    {"preset": 'light'},
    background_color: 'lightseagreen'
)

setView

Python: set_view

Sets the view state of the map.

setView(
  view: Partial<View>
): View;

set_view(
  self,
  view: Union[View, dict, None] = None,
  **kwargs: Number
) -> View

Javascript

Arguments

Argument	Type	Description
`view`	`View`	Type encapsulating view properties.

Returns

Returns the updated View state object.

Python

Positional Arguments

Argument	Type	Description
`view`	`Union[View, dict, None]`	View model instance or a dict with the same attributes

Keyword Arguments

Argument	Type	Description
`latitude`	`number`	Longitude of the view center [-180, 180].
`longitude`	`number`	Latitude of the view center [-90, 90].
`zoom`	`number`	View zoom level [0-22].
`pitch`	`number`	View pitch value [0-90].
`bearing`	`number`	View bearing [0-360].

Returns

Returns the updated View state object.

Examples

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

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

setView

Python: set_view

Sets the view state of the map.

setView(
  view: Partial<View>
): View;

set_view(
  self,
  view: Union[View, dict, None] = None,
  **kwargs: Number
) -> View

Javascript

Arguments

Argument	Type	Description
`view`	`View`	Type encapsulating view properties.

Returns

Returns the updated View state object.

Python

Positional Arguments

Argument	Type	Description
`view`	`Union[View, dict, None]`	View model instance or a dict with the same attributes

Keyword Arguments

Argument	Type	Description
`latitude`	`number`	Longitude of the view center [-180, 180].
`longitude`	`number`	Latitude of the view center [-90, 90].
`zoom`	`number`	View zoom level [0-22].
`pitch`	`number`	View pitch value [0-90].
`bearing`	`number`	View bearing [0-360].

Returns

Returns the updated View state object.

Examples

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

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

setViewLimits

Python: set_view_limits

Sets the view state of the map.

setViewLimits(
  viewLimits: Partial<ViewLimits>,
  options?: SetViewLimitsOptions
): ViewLimits;

set_view_limits(
    self,
    view_limits: Union[ViewLimits, dict, None] = None,
    **kwargs: Union[Number, Bounds, dict],
) -> ViewLimits:

Javascript

Arguments

Argument	Type	Description
`viewLimits`	`Partial<ViewLimits>`	Type encapsulating view properties.
`options`	`SetViewLimitsOptions`	A set of options to use when setting the view limit.

Returns

Returns the updated ViewLimits state object.

Python

Positional Arguments

Argument	Type	Description
`view_limits`	`Union[ViewLimits, dict, None]`	ViewLimits model instance or a dict with the same attributes, all optional.

Keyword Arguments

Argument	Type	Description
`min_zoom`	`Number`	Minimum zoom of the map [0-22].
`max_zoom`	`Number`	Maximum zoom of the map [0-22].
`max_bounds`	`Bounds`, `dict`	a Bounds object or a dict with the keys (`min_longitude`, `max_longitude`, `min_latitude`, `max_latitude`).

Returns

Returns the updated ViewLimits state object.

Examples

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

map.set_view_limits({
  "min_zoom": 0,
  "max_zoom": 22,
  "max_bounds": {
    "min_longitude": -122.4845632122524,
    "max_longitude": -121.7461580455235,
    "min_latitude": 37.49028773126059,
    "max_latitude": 37.94131376494916
  }
})

setViewMode

Python: set_view_mode

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

setViewMode(
  viewMode: ViewMode
): ViewMode;

set_view_mode(
    self,
    view_mode: ViewMode
) -> Optional[ViewMode]:

Javascript

Arguments

Argument	Type	Description
`viewMode`	`viewMode`	The view mode for the map, either `"2D"`, `"3D"`, or `"globe"`.

Returns

Returns the updated ViewMode state object.

Python

Arguments

Argument	Type	Description
`viewMode`	`viewMode`	The view mode for the map, either `"2D"`, `"3D"`, or `"globe"`.

Returns

Returns the updated ViewMode state object.

Examples

map.setViewMode("3d");

map.set_view_mode("3d")

updateEffect

Python: update_effect

Updates a visual post-processing effect to the map.

updateEffect(
  effectId: string,
  values: EffectUpdateProps
): Effect;

update_effect(
    effect_id: str,
    values: Union[_EffectUpdateProps, dict, None] = None,
) -> Optional[Effect]:

Javascript

Arguments

Argument	Type	Description
`effectId`	`string`	The ID for the effect to update.
`values`	`EffectUpdateProps`	A set of properties used to update an effect.

Returns

Returns the updated effect.

Python

Argument	Type	Description
`effect_id`	`string`	The ID for the effect to update.
`values`	`EffectUpdateProps`	A set of properties used to update an effect.

Returns

Returns the updated effect.

Examples

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

map.update_effect({
  "id": "effect-id",
  "is_enabled": False,
  "parameters": {
    "shadowIntensity": 0.75,
    "shadowColor": [25, 50, 75]
  },
})