API Reference
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[ ,FilterTimelineUpdateProps dict, 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[ ,LayerTimelineUpdateProps dict, 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]
},
})
Updated 3 days ago