API Reference

class maplibreum.choropleth.Choropleth(geojson, data, key_on='id', colors=None, color_scale='linear', legend_title='')

Bases: object

Simple choropleth renderer for GeoJSON data.

Parameters:

  • geojson (dict) – FeatureCollection containing polygon features.

  • data (dict) – Mapping from feature key to numeric value.

  • key_on (str, optional) – Feature key to match in data. Default "id".

  • colors (list of str, optional) – Sequence of colors used for bins.

  • color_scale (str, optional) – "linear" for equal-interval bins or "quantile" for quantile bins.

  • legend_title (str, optional) – Title shown on the legend.

add_to(map_instance)

Add the choropleth layer to a map instance.

This method calculates bins, assigns colors to features, and adds the necessary source and fill layer to the map. It also generates and adds a legend.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the choropleth will be added.

Return type:

self

class maplibreum.cluster.ClusteredGeoJson(data, name=None, cluster_radius=50, cluster_max_zoom=14)

Bases: object

Cluster arbitrary GeoJSON features using MapLibre’s clustering.

add_to(map_instance)

Add the clustered GeoJSON to a map instance.

This method creates the GeoJSON source and layers for clustering features and adds them to the map.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the clustered GeoJSON will be added.

Return type:

self

class maplibreum.cluster.MarkerCluster(name=None, cluster_radius=50, cluster_max_zoom=14)

Bases: object

Group markers into clusters using MapLibre’s built-in clustering.

add_marker(marker)

Add a marker to the cluster.

Parameters:

marker (maplibreum.Marker) – The marker to add to the cluster.

add_to(map_instance)

Add the marker cluster to a map instance.

This method creates the GeoJSON source and layers for clustering markers and adds them to the map.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the cluster will be added.

Return type:

self

maplibreum.cluster.cluster_features(features, radius=40, max_zoom=16)

Cluster features using a simple grid-based algorithm.

This is a lightweight stand-in for supercluster suitable for testing and benchmarking purposes.

class maplibreum.controls.ButtonControl(label, action=None, position='top-left', css_class='maplibreum-button', style=None, onclick_js=None)

Bases: object

A button control that can trigger Python API actions.

This control provides an alternative to JavaScript injection for interactive buttons on the map.

to_dict()

Serialize configuration for template usage.

class maplibreum.controls.GlobeControl(**options)

Bases: object

Configuration wrapper for maplibregl.GlobeControl.

class maplibreum.controls.LayerColorControl(layers, colors, position='top-left', title='Select layer')

Bases: object

A control for changing layer colors interactively.

This control provides an alternative to JavaScript injection for changing layer paint properties with a color picker interface.

to_dict()

Serialize configuration for template usage.

class maplibreum.controls.MeasureControl(**options)

Bases: object

Configuration for the map measure tool.

to_dict()

Serialize configuration for template usage.

class maplibreum.controls.MiniMapControl(style='basic', zoom_level=6)

Bases: object

Configuration object for the MiniMap plugin control.

to_dict()

Serialize configuration for template usage.

class maplibreum.controls.SearchControl(provider='maptiler', api_key=None, **options)

Bases: object

Configuration for a search/geocoder control.

to_dict()

Serialize configuration for template usage.

Returns:

The dictionary representation of the search control options.

Return type:

dict

class maplibreum.controls.TextFilterControl(layer_ids, placeholder='Filter by name', position='top-right', match_mode='contains')

Bases: object

A text input control for filtering map layers or features.

This control provides an alternative to JavaScript injection for text-based filtering of layers.

to_dict()

Serialize configuration for template usage.

class maplibreum.controls.ToggleControl(label, on_action=None, off_action=None, initial_state=False, position='top-left')

Bases: object

A toggle control for switching between two states.

to_dict()

Serialize configuration for template usage.

class maplibreum.core.Circle(location, radius=1000, color='#3388ff', fill=True, fill_color=None, fill_opacity=0.5, popup=None, tooltip=None)

Bases: object

Draw a circle with radius in meters.

add_to(map_instance)

Add the circle to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the circle will be added.

class maplibreum.core.CircleMarker(location, radius=6, color='#3388ff', fill=True, fill_color=None, fill_opacity=1.0, popup=None, tooltip=None)

Bases: object

Circle marker with radius in pixels.

add_to(map_instance)

Add the circle marker to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the circle marker will be added.

class maplibreum.core.EventBinding(id, event, layer_id=None, js=None, send_to_python=False, toggles=<factory>, once=False)

Bases: object

Representation of a MapLibre event binding produced from Python.

to_render_dict()

Convert to the structure used by the template.

class maplibreum.core.FeatureGroup(name=None)

Bases: object

Group multiple layers so they can be toggled together.

add_layer(layer_definition, source=None, before=None)

Add a layer to the feature group.

Parameters:

  • layer_definition (dict) – A dictionary describing a MapLibre GL style layer.

  • source (dict or str, optional) – A dictionary describing a MapLibre source, or a string referencing an existing source.

  • before (str, optional) – The ID of an existing layer before which this layer should be placed.

Returns:

The ID of the added layer.

Return type:

str

add_popup(html=None, coordinates=None, layer_id=None, events=None, options=None, prop=None, template=None, context=None)

Add a popup to the feature group.

Parameters:

  • html (str or object with render method) – HTML content of the popup.

  • coordinates (list, optional) – [lng, lat] for a fixed popup position.

  • layer_id (str, optional) – The ID of the layer to which the popup is bound.

  • events (list, optional) – List of events that trigger the popup (e.g., ['click']).

  • options (dict, optional) – A dictionary of popup options.

  • prop (str, optional) – The name of a feature property to use as the popup content.

  • template (str, optional) – A Jinja2 template string for the popup content.

  • context (dict, optional) – The rendering context for templates.

add_source(name, definition)

Add a source to the feature group.

Parameters:

  • name (str) – The name of the source.

  • definition (dict) – The source definition.

add_to(map_instance)

Add the feature group to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the feature group will be added.

Return type:

self

add_tooltip(tooltip=None, layer_id=None, options=None, prop=None)

Add a tooltip to the feature group.

Parameters:

  • tooltip (str or Tooltip) – The tooltip content.

  • layer_id (str, optional) – The ID of the layer to which the tooltip is bound.

  • options (dict, optional) – A dictionary of tooltip options.

  • prop (str, optional) – The name of a feature property to use as the tooltip content.

class maplibreum.core.FloatImage(image_url, position='top-left', width=None)

Bases: object

Add an image floating above the map at a fixed position.

add_to(map_instance)

Add the floating image to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the floating image will be added.

Return type:

self

property style

Get the CSS style for the floating image.

class maplibreum.core.GeoJson(data, style_function=None, name=None, popup=None, tooltip=None)

Bases: object

Representation of a GeoJSON overlay.

add_to(map_instance)

Add this GeoJSON object to a map instance.

The geometry type of each feature is inspected and appropriate layers (fill for polygons, line for polylines and circle for points) are created. The style_function is used to populate feature properties such as stroke, weight and fillColor which are then referenced by the layer paint definitions.

class maplibreum.core.GeoJsonPopup(fields, aliases=None, labels=True, style='')

Bases: object

Generate HTML snippets from GeoJSON feature properties.

render(feature)

Render the popup content from a GeoJSON feature.

Parameters:

feature (dict) – A GeoJSON feature.

Returns:

The rendered HTML content.

Return type:

str

class maplibreum.core.GeoJsonTooltip(fields, aliases=None, labels=True, style='')

Bases: GeoJsonPopup

Generate tooltips from GeoJSON feature properties.

render(feature)

Render the tooltip content from a GeoJSON feature.

Parameters:

feature (dict) – A GeoJSON feature.

Returns:

The rendered HTML content.

Return type:

str

class maplibreum.core.ImageOverlay(image, bounds=None, coordinates=None, opacity=1.0, attribution=None, name=None)

Bases: object

Overlay a georeferenced image on the map.

add_to(map_instance)

Add the image overlay to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the image overlay will be added.

Return type:

self

class maplibreum.core.LatLngPopup

Bases: object

Display a popup with latitude and longitude when the map is clicked.

add_to(map_instance)

Add the LatLngPopup to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the LatLngPopup will be added.

Return type:

self

class maplibreum.core.LayerControl

Bases: object

Simple layer control to toggle tile and overlay layers.

add_overlay(layer, name=None)

Register an overlay layer or group by ID and display name.

add_to(map_instance)

Add the layer control to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the layer control will be added.

Return type:

self

class maplibreum.core.Legend(content)

Bases: object

Map legend supporting raw HTML or label/color pairs.

add_to(map_instance)

Add the legend to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the legend will be added.

Return type:

self

render()

Render the legend to HTML.

class maplibreum.core.Map(title='MapLibreum Map', map_style='basic', center=[0, 0], zoom=2, pitch=None, bearing=None, elevation=None, center_clamped_to_ground=None, width='100%', height='500px', controls=None, layers=None, popups=None, tooltips=None, extra_js='', custom_css='', maplibre_version='3.4.0', map_options=None)

Bases: object

The main Map class.

add_animation(animation)

Register an animation or temporal loop to run after load.

Return type:

None

add_button_control(label, action, position='top-left', css_class='maplibreum-button', style=None)

Add a button control that can trigger map actions.

This provides a Python API alternative to JavaScript injection for interactive buttons.

Parameters:

  • label (str) – The text label for the button.

  • action (callable) – A function that takes the map instance as parameter.

  • position (str, optional) – Position on the map (e.g. ‘top-left’, ‘top-right’).

  • css_class (str, optional) – CSS class for styling the button.

  • style (dict, optional) – Inline CSS styles for the button.

Returns:

A unique identifier for this button control.

Return type:

str

add_circle_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a circle layer to the map.

Parameters:

  • name (str) – The name of the layer.

  • source (str or dict) – The source for the layer.

  • paint (dict, optional) – The paint properties for the layer.

  • layout (dict, optional) – The layout properties for the layer.

  • before (str, optional) – The ID of an existing layer to insert this layer before.

  • filter (list, optional) – A MapLibre GL filter expression.

add_clustered_geojson(data, name=None, radius=50, max_zoom=14)

Add a clustered GeoJSON source and layers to the map.

Parameters:

  • data (dict) – GeoJSON FeatureCollection to cluster.

  • name (str, optional) – Base name for generated source and layers.

  • radius (int, optional) – Cluster radius in pixels passed to Supercluster.

  • max_zoom (int, optional) – Maximum zoom level at which clustering occurs.

add_control(control, position='top-right', options=None)

Add a UI control to the map. :type control: :param control: Either a control instance or a known control alias such as "navigation". :type control: object or str :type position: :param position: Position on the map (e.g. 'top-right' or 'bottom-left'). :type position: str, optional :type options: :param options: Additional configuration forwarded to the control when control

is provided as a string alias.

add_dem_source(name, url=None, *, tiles=None, tile_size=512, attribution=None, **kwargs)

Add a raster-dem source for terrain rendering.

Parameters:

  • name (str) – Identifier for the source.

  • url (str or list, optional) – Tile JSON URL or template string. When the URL ends with .json it is treated as a TileJSON endpoint; otherwise it is interpreted as a tile template.

  • tiles (str or sequence, optional) – Explicit tile URL template or list of templates. When provided it takes precedence over url.

  • tile_size (int, optional) – Tile size in pixels, defaults to 512.

  • attribution (str, optional) – Attribution string for the DEM source.

  • kwargs (dict, optional) – Additional source parameters forwarded to MapLibre.

add_draw_control(options=None)

Enable a draw control on the map.

add_event_listener(event, *, layer_id=None, js=None, state_toggles=None, once=False, event_id=None)

Attach a pure JavaScript handler for a MapLibre event.

Parameters:

  • event (str) – Name of the MapLibre event to listen for (e.g., 'click').

  • layer_id (str, optional) – If provided, the handler listens to events bound to the given rendered layer ID.

  • js (str, optional) – JavaScript snippet executed inside the handler. The snippet has access to map (the map instance), event (the MapLibre event object) and data (the payload sent to Python callbacks).

  • state_toggles (iterable, optional) – Collection of StateToggle objects or dictionaries that describe DOM state changes (class toggles, attribute updates, etc.) to execute alongside the handler.

  • once (bool, optional) – When True the handler is registered with map.once instead of map.on.

  • event_id (str, optional) – Explicit identifier for the handler. Defaults to "{event}@{layer}" when layer_id is provided or simply event otherwise.

Returns:

The identifier of the registered handler, useful for debugging or manual inspection.

Return type:

str

add_external_script(src, *, defer=False, async_=False, module=False, attributes=None)

Load an additional JavaScript bundle before the map initialises.

Parameters:

  • src (str) – Absolute or relative URL of the script to include.

  • defer (bool, optional) – Add the defer attribute so the browser defers execution until after parsing the document.

  • async (bool, optional) – Add the async attribute for asynchronous loading.

  • module (bool, optional) – Mark the script as an ES module by setting type="module".

  • attributes (mapping, optional) – Extra HTML attributes (e.g. integrity) to attach to the tag.

Return type:

str

add_fill_extrusion_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a fill-extrusion layer to the map.

add_fill_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a fill layer to the map.

Parameters:

  • name (str) – The name of the layer.

  • source (str or dict) – The source for the layer.

  • paint (dict, optional) – The paint properties for the layer.

  • layout (dict, optional) – The layout properties for the layer.

  • before (str, optional) – The ID of an existing layer to insert this layer before.

  • filter (list, optional) – A MapLibre GL filter expression.

add_float_image(image_url, position='top-left', width=None)

Add a floating image anchored to a map corner.

Parameters:

  • image_url (str) – URL of the image to display.

  • position (str, optional) – One of 'top-left', 'top-right', 'bottom-left' or 'bottom-right'. Defaults to 'top-left'.

  • width (int, optional) – Width of the image in pixels.

add_heatmap_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a heatmap layer to the map.

Parameters:

  • name (str) – Layer identifier.

  • source (dict or str) – Source definition or the name of an existing source.

  • paint (dict, optional) – Heatmap paint properties. Missing properties fall back to sensible defaults.

  • layout (dict, optional) – Layout properties for the layer.

  • before (str, optional) – ID of an existing layer before which this layer should be placed.

  • filter (list, optional) – MapLibre filter expression.

add_image(name, url=None, data=None, options=None)

Register a style image so it can be referenced by layers.

Parameters:

  • name (str) – Identifier to use from layer icon-image or fill-pattern.

  • url (str, optional) – Remote image URL to be loaded via map.loadImage at runtime.

  • data (Any, optional) – Direct image data to pass to map.addImage.

  • options (dict, optional) – Extra parameters forwarded to map.addImage (e.g. sdf or pixelRatio).

add_lat_lng_popup()

Enable a popup showing latitude and longitude on click.

add_layer(layer_definition, source=None, before=None)

Add a layer to the map.

Parameters:

  • layer_definition (dict) – A dictionary describing a MapLibre GL style layer.

  • source (dict or str, optional) – A dictionary describing a MapLibre source, or a string referencing an existing source.

  • before (str, optional) – The ID of an existing layer before which this layer should be placed.

Returns:

The ID of the added layer.

Return type:

str

add_legend(legend)

Add a legend to the map.

add_line_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a line layer to the map.

Parameters:

  • name (str) – The name of the layer.

  • source (str or dict) – The source for the layer.

  • paint (dict, optional) – The paint properties for the layer.

  • layout (dict, optional) – The layout properties for the layer.

  • before (str, optional) – The ID of an existing layer to insert this layer before.

  • filter (list, optional) – A MapLibre GL filter expression.

add_marker(coordinates=None, popup=None, color='#007cbf', cluster=None, icon=None, tooltip=None, draggable=False)

Add a marker to the map.

Parameters:

  • coordinates (list or tuple, optional) – [lng, lat] pair where the marker will be placed. Defaults to the map’s center if not provided.

  • popup (str, optional) – HTML content for a popup bound to the marker.

  • color (str, optional) – Color of the marker, defaults to MapLibre blue.

  • cluster (MarkerCluster, optional) – Marker cluster to which the marker will be added. When provided, the marker is added to the cluster instead of directly to the map.

  • icon (Icon, optional) – Custom icon for the marker. If provided, color is ignored.

  • tooltip (str or Tooltip, optional) – Text for a tooltip bound to the marker.

  • draggable (bool, optional) – Whether the marker should be draggable.

add_on_load_js(code)

Schedule raw JavaScript to execute within the load handler.

Return type:

None

add_popup(html=None, coordinates=None, layer_id=None, events=None, options=None, prop=None, template=None, context=None)

Add a popup to the map.

Parameters:

  • html (str or object with render method) – HTML content of the popup.

  • coordinates (list, optional) – [lng, lat] for a fixed popup position.

  • layer_id (str, optional) – The ID of the layer to which the popup is bound.

  • events (list, optional) – List of events that trigger the popup (e.g., ['click']).

  • options (dict, optional) – A dictionary of popup options.

  • prop (str, optional) – The name of a feature property to use as the popup content.

  • template (str, optional) – A Jinja2 template string for the popup content.

  • context (dict, optional) – The rendering context for templates.

add_sky_layer(name='sky', paint=None, layout=None, before=None)

Add a sky layer to the map.

add_source(name, definition)

Add a source definition to the style.

Parameters:

  • name (str) – The name of the source.

  • definition (dict or maplibreum.sources.Source) – The source definition. Instances of Source are converted to the underlying dictionary automatically so both the plain MapLibre dictionaries and the convenience wrappers are supported.

add_symbol_layer(name, source, paint=None, layout=None, before=None, filter=None)

Add a symbol layer to the map.

Parameters:

  • name (str) – The name of the layer.

  • source (str or dict) – The source for the layer.

  • paint (dict, optional) – The paint properties for the layer.

  • layout (dict, optional) – The layout properties for the layer.

  • before (str, optional) – The ID of an existing layer to insert this layer before.

  • filter (list, optional) – A MapLibre GL filter expression.

add_tile_layer(url, name=None, attribution=None, subdomains=None, *, tile_size=256, min_zoom=None, max_zoom=None, bounds=None, scheme=None, volatile=None, **source_options)

Add a raster tile layer to the map.

Parameters:

  • url (str) – Tile URL template. May contain {s} as a placeholder for subdomains.

  • name (str, optional) – Name of the layer. If omitted, a unique ID is generated.

  • attribution (str, optional) – Attribution text for the layer.

  • subdomains (list of str, optional) – Subdomains to replace {s} in the URL. If provided and {s} exists in url, multiple tile URLs will be generated.

  • tile_size (int, optional) – Tile size in pixels. Defaults to 256 which matches the MapLibre GL JS default for raster sources.

  • min_zoom (int, optional) – Optional zoom constraints forwarded to the underlying source.

  • max_zoom (int, optional) – Optional zoom constraints forwarded to the underlying source.

  • bounds (sequence of float, optional) – Geographic bounds of the tile set as [west, south, east, north].

  • scheme (str, optional) – Tile scheme ('xyz' or 'tms').

  • volatile (bool, optional) – Whether tiles may change frequently.

  • **source_options – Additional keyword arguments forwarded to maplibreum.sources.RasterSource for advanced configuration.

add_time_dimension(data, options=None)

Store timestamped GeoJSON data for simple animation playback.

Parameters:

  • data (dict) – GeoJSON FeatureCollection whose features include a time property.

  • options (dict, optional) – Configuration dictionary. Supports interval in milliseconds for playback speed.

add_tooltip(tooltip=None, layer_id=None, options=None, prop=None)

Add a tooltip to the map.

add_wms_layer(base_url, layers, name=None, styles='', version='1.1.1', format='image/png', transparent=True, attribution=None, extra_params=None)

Add a WMS layer to the map as raster tiles.

Parameters:

  • base_url (str) – Base URL of the WMS service without query parameters.

  • layers (str) – Comma-separated layer names to request.

  • name (str, optional) – Name of the layer. If omitted, a unique ID is generated.

  • styles (str, optional) – Comma-separated style names.

  • version (str, optional) – WMS version, defaults to 1.1.1.

  • format (str, optional) – Image format for tiles, defaults to image/png.

  • transparent (bool, optional) – Whether the background should be transparent.

  • attribution (str, optional) – Attribution text for the layer.

  • extra_params (dict, optional) – Additional query parameters for the WMS request.

disable_rotation(*, drag_rotate=True, touch_zoom_rotate=True, keyboard_rotate=True)

Disable map rotation interactions.

This method provides a Python API alternative to JavaScript injection for disabling rotation controls.

Parameters:

  • drag_rotate (bool, optional) – Whether to disable drag rotation (default True).

  • touch_zoom_rotate (bool, optional) – Whether to disable touch zoom rotation (default True).

  • keyboard_rotate (bool, optional) – Whether to disable keyboard rotation (default True).

display_in_notebook(width='100%', height='500px')

Display the map in a Jupyter Notebook with a specific size.

This method writes the map to a temporary HTML file and displays it in an IFrame.

Parameters:

  • width (str, optional) – The width of the IFrame.

  • height (str, optional) – The height of the IFrame.

property drawn_features

Get the features drawn on the map.

Returns:

A GeoJSON FeatureCollection of the drawn features.

Return type:

dict

ease_to(**options)

Queue a MapLibre easeTo camera animation.

enable_globe(*, projection='globe', add_control=False, control_position='top-left', control_options=None)

Switch the map projection to globe and optionally add a control.

enable_rtl_text_plugin(url='https://unpkg.com/maplibre-gl-rtl-text@latest/dist/maplibre-gl-rtl-text.js', *, callback=<object object>, lazy=False, force=False)

Register the MapLibre RTL text plugin.

Parameters:

  • url (str, optional) – URL for the maplibre-gl-rtl-text plugin script.

  • callback (str or None, optional) – JavaScript callback invoked once the plugin is loaded. Pass None to emit null and lazy=True when replicating the official example snippet.

  • lazy (bool, optional) – When True the plugin is only fetched on demand, matching the third argument of maplibregl.setRTLTextPlugin.

  • force (bool, optional) – Force re-registering the plugin even if MapLibre reports that it has already been loaded.

export_png(filepath, width=None, height=None)

Export the map to a PNG image using the MapLibre export CLI.

Parameters:

  • filepath (str) – Destination path for the PNG file.

  • width (int, optional) – Dimensions for the exported image in pixels.

  • height (int, optional) – Dimensions for the exported image in pixels.

fit_bounds(bounds, padding=None)

Store bounds and optional padding for later rendering.

Parameters:

  • bounds (list) – Bounds in the form [[west, south], [east, north]].

  • padding (int or dict, optional) – Padding to apply in pixels. Can be a number or an options dictionary accepted by map.fitBounds.

fly_to(**options)

Queue a MapLibre flyTo camera animation.

on(event, callback, *, layer_id=None, js=None, state_toggles=None, once=False, event_id=None)

Register a Python callback for a MapLibre event.

The callback receives a dictionary with lngLat (when available), current center and zoom information. Extra JavaScript snippets or DOM state toggles can be chained to the same event using the js and state_toggles arguments.

Parameters:

  • event (str) – MapLibre event name.

  • callback (callable) – Python callable invoked when the event fires. Executed via the Jupyter kernel in notebook environments.

  • layer_id (str, optional) – Restrict the listener to features rendered by this layer.

  • js (str, optional) – JavaScript snippet executed after the callback payload is queued.

  • state_toggles (iterable, optional) – DOM toggle definitions applied whenever the event fires.

  • once (bool, optional) – Register a one-shot listener using map.once.

  • event_id (str, optional) – Explicit identifier for this handler. Defaults to "{event}@{layer}" for layer-bound handlers or event for map-wide listeners.

Returns:

The identifier associated with the handler.

Return type:

str

on_click(callback, **kwargs)

Convenience method for click events.

on_hover(callback, **kwargs)

Convenience method for mouseenter events (hover).

on_mousemove(callback, **kwargs)

Convenience method for mousemove events.

on_mouseout(callback, **kwargs)

Convenience method for mouseout events.

on_mouseover(callback, **kwargs)

Convenience method for mouseover events.

on_move(callback, **kwargs)

Convenience method for move events.

pan_to(center, **options)

Queue a MapLibre panTo camera movement.

query_rendered_features_at_point(point, layers=None, filter=None)

Create a JavaScript snippet to query rendered features at a point.

This method provides a helper for generating feature query JavaScript that can be used in event handlers.

Parameters:

  • point (str) – JavaScript expression for the point (e.g., “event.point”).

  • layers (list, optional) – List of layer IDs to query.

  • filter (dict, optional) – Filter expression to apply.

Returns:

JavaScript code snippet for querying features.

Return type:

str

register_overlay(layer_id, name=None, layers=None)

Register a non-tile overlay layer or group for the layer control.

render()

Render the map to an HTML string.

Returns:

The rendered HTML.

Return type:

str

save(filepath)

Save the map to an HTML file.

Parameters:

filepath (str) – The path to the output HTML file.

property search_result

Get the result of the last geocoder search.

Returns:

A [lng, lat] coordinate pair.

Return type:

list

set_fog(options=None)

Set global fog options for the map.

set_mobile_behavior(*, cooperative_gestures=None, touch_zoom_rotate=None, touch_pitch=None, pitch_with_rotate=None)

Toggle mobile-friendly MapLibre constructor flags.

Parameters:

  • cooperative_gestures (bool, optional) – Enable cooperativeGestures for friendlier embedded mobile maps.

  • touch_zoom_rotate (bool, optional) – Toggle touchZoomRotate which controls pinch gestures.

  • touch_pitch (bool, optional) – Toggle touchPitch to enable two-finger pitch gestures.

  • pitch_with_rotate (bool, optional) – Toggle pitchWithRotate to control pitch during rotation.

set_projection(projection, *, add_globe_control=False, control_position='top-left', control_options=None)

Set the map projection used by MapLibre.

Parameters:

  • projection (str or mapping) – Either the name of the projection (e.g. "globe" or "mercator") or a mapping describing projection parameters. The mapping is passed straight through to MapLibre allowing custom projections such as Albers.

  • add_globe_control (bool, optional) – When True and projection is "globe", the globe control is added to the map UI.

  • control_position (str, optional) – Position for the optional globe control.

  • control_options (dict, optional) – Additional options forwarded to the globe control.

set_source_tile_lod_params(max_zoom_levels, tile_count_ratio)

Set the LOD parameters for source tiles.

This is a wrapper around the MapLibre GL JS setSourceTileLodParams method.

Parameters:

  • max_zoom_levels (int) – The maximum number of zoom levels to show on screen.

  • tile_count_ratio (float) – The ratio of tiles to render at high pitch angles.

set_terrain(source_name, exaggeration=1.0, **options)

Enable 3D terrain using the given raster-dem source.

class maplibreum.core.Marker(coordinates, popup=None, color='#007cbf', icon=None, tooltip=None, draggable=False)

Bases: object

A marker on the map.

add_to(map_instance)

Add the marker to a map or marker cluster.

Parameters:

map_instance (maplibreum.Map or maplibreum.MarkerCluster) – The map or marker cluster to which the marker will be added.

Return type:

self

class maplibreum.core.PolyLine(locations, color='#3388ff', weight=2, popup=None, tooltip=None)

Bases: object

A polyline on the map.

add_to(map_instance)

Add the polyline to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the polyline will be added.

class maplibreum.core.Polygon(locations, color='#3388ff', weight=2, fill=True, fill_color=None, fill_opacity=0.5, popup=None, tooltip=None)

Bases: object

A polygon on the map.

add_to(map_instance)

Add the polygon to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the polygon will be added.

class maplibreum.core.Popup(html=None, template=None)

Bases: object

Representation of a popup with optional Jinja2 templating.

render(context=None)

Render the popup content.

If a template is provided, it is rendered with the given context. Otherwise, the plain HTML is returned.

Parameters:

context (dict, optional) – Context for rendering the template.

Returns:

The rendered HTML content.

Return type:

str

class maplibreum.core.Rectangle(southwest, northeast, color='#3388ff', weight=2, fill=True, fill_color=None, fill_opacity=0.5, popup=None, tooltip=None)

Bases: object

Axis-aligned rectangle defined by southwest and northeast corners.

add_to(map_instance)

Add the rectangle to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the rectangle will be added.

class maplibreum.core.StateToggle(selector, class_name=None, state=None, attribute=None, value=None, dataset=None, text=None)

Bases: object

Describe DOM state changes that should occur when an event fires.

to_dict()

Return a JSON-serialisable representation.

class maplibreum.core.Tooltip(text, options=None)

Bases: object

Simple representation of a tooltip bound to a layer.

class maplibreum.core.VideoOverlay(videos, bounds=None, coordinates=None, opacity=1.0, attribution=None, name=None)

Bases: object

Overlay a georeferenced video on the map.

add_to(map_instance)

Add the video overlay to a map instance.

Parameters:

map_instance (maplibreum.Map) – The map instance to which the video overlay will be added.

Return type:

self

Utility functions for building and validating MapLibre expressions.

MapLibre expressions are represented as nested lists following the MapLibre GL JS style specification. This module provides small helper functions to create these lists while ensuring they are well formed.

maplibreum.expressions.expression(op, *args)

Build and validate a raw expression.

Return type:

List[Any]

maplibreum.expressions.get(property, context=None)

Return a get expression for property within context.

Parameters:

  • property (str) – Name of the property to read.

  • context (Any, optional) – Optional context, such as ["properties"].

Return type:

List[Any]

maplibreum.expressions.interpolate(method, input_expr, stops)

Return an interpolate expression.

Parameters:

  • method (str or sequence) – Interpolation method, e.g. "linear" or ["linear"].

  • input_expr (Any) – Input expression that provides the value to interpolate.

  • stops (iterable of (stop, value)) – Sequence of pairs defining interpolation stops.

Return type:

List[Any]

maplibreum.expressions.validate(expr)

Validate that expr is a well-formed MapLibre expression.

Parameters:

expr (Any) – Expression to validate.

Returns:

True if validation succeeds. A ValueError is raised if the expression structure is invalid.

Return type:

bool

maplibreum.expressions.var(name)

Return an expression referencing a variable or attribute.

Return type:

List[Any]

Marker icon classes for MapLibreum.

class maplibreum.markers.BeautifyIcon(icon='', icon_shape='marker', border_color='#b8b8b8', text_color='white', background_color='#2a81cb')

Bases: DivIcon

A simple BeautifyIcon similar to Leaflet’s plugin.

Parameters:

  • icon (str) – CSS class for an inner icon element.

  • icon_shape (str, optional) – Shape of the marker. Only "marker" is implemented.

  • border_color (str, optional) – Border color for the marker.

  • text_color (str, optional) – Color of the icon text.

  • background_color (str, optional) – Background color of the marker.

class maplibreum.markers.DivIcon(html='', class_name='maplibreum-div-icon')

Bases: object

HTML/CSS based icon rendered with a DOM element.

class maplibreum.markers.Icon(icon_image, icon_size=None, icon_anchor=None)

Bases: object

Representation of an image-based icon used for symbol markers.

Parameters:

  • icon_image (str) – Name of the image to use for the icon.

  • icon_size (float, optional) – Size of the icon relative to its original resolution.

  • icon_anchor (str, optional) – Part of the icon that should be placed at the marker’s geographical location (e.g. "bottom").

class maplibreum.timedimension.TimeDimension(data, options=None)

Bases: object

Wrapper for timestamped GeoJSON data enabling simple playback.

Parameters:

  • data (dict) – GeoJSON FeatureCollection with features carrying a time property.

  • options (dict, optional) – Additional options for playback, such as interval in milliseconds.

add_to(map_instance)

Add this time dimension data to a map instance.

Return type:

TimeDimension