plugins

Folium plugins

Wrap some of the most popular leaflet external plugins.

class folium.plugins.BeautifyIcon(icon=None, icon_shape=None, border_width=3, border_color='#000', text_color='#000', background_color='#FFF', inner_icon_style='', spin=False, number=None)

Bases: branca.element.MacroElement

Create a BeautifyIcon that can be added to a Marker

Parameters:
  • icon (string, default None) – the Font-Awesome icon name to use to render the marker.
  • icon_shape (string, default None) – the icon shape
  • border_width (integer, default 3) – the border width of the icon
  • border_color (string with hexadecimal RGB, default '#000') – the border color of the icon
  • text_color (string with hexadecimal RGB, default '#000') – the text color of the icon
  • background_color (string with hexadecimal RGB, default '#FFF') – the background color of the icon
  • inner_icon_style (string with css styles for the icon, default '') – the css styles of the icon
  • spin (boolean, default False) – allow the icon to be spinning.
  • number (integer, default None) – the number of the icon.

Examples

Plugin Website: https://github.com/marslan390/BeautifyMarker >>> BeautifyIcon(text_color=’#000’, border_color=’transparent’,

background_color=’#FFF’).add_to(marker)
>>> number_icon = BeautifyIcon(text_color='#000', border_color='transparent',
                                background_color='#FFF', number=10,
                                inner_icon_style='font-size:12px;padding-top:-5px;')
>>> Marker(location=[45.5, -122.3], popup=folium.Popup('Portland, OR'), icon=number_icon)
>>> BeautifyIcon(icon='arrow-down', icon_shape='marker').add_to(marker)
ICON_SHAPE_TYPES = ['circle', 'circle-dot', 'doughnut', 'rectangle-dot', 'marker', None]
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.BoatMarker(location, popup=None, icon=None, heading=0, wind_heading=None, wind_speed=0, **kwargs)

Bases: folium.map.Marker

Creates a BoatMarker plugin to append into a map with Map.add_plugin.

Parameters:
  • location (tuple of length 2, default None) – The latitude and longitude of the marker. If None, then the middle of the map is used.
  • heading (int, default 0) – Heading of the boat to an angle value between 0 and 360 degrees
  • wind_heading (int, default None) – Heading of the wind to an angle value between 0 and 360 degrees If None, then no wind is represented.
  • wind_speed (int, default 0) – Speed of the wind in knots.
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.Draw(export=False)

Bases: branca.element.MacroElement

Vector drawing and editing plugin for Leaflet.

Parameters:export (bool, default False) – Add a small button that exports the drawn shapes as a geojson file.

Examples

>>> m = folium.Map()
>>> Draw(export=True).add_to(m)

For more info please check https://leaflet.github.io/Leaflet.draw/docs/leaflet-draw-latest.html

render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.FastMarkerCluster(data, callback=None, options=None, name=None, overlay=True, control=True, show=True)

Bases: folium.plugins.marker_cluster.MarkerCluster

Add marker clusters to a map using in-browser rendering. Using FastMarkerCluster it is possible to render 000’s of points far quicker than the MarkerCluster class.

Be aware that the FastMarkerCluster class passes an empty list to the parent class’ __init__ method during initialisation. This means that the add_child method is never called, and no reference to any marker data are retained. Methods such as get_bounds() are therefore not available when using it.

Parameters:
  • data (list) – List of list of shape [[], []]. Data points should be of the form [[lat, lng]].
  • callback (string, default None) – A string representation of a valid Javascript function that will be passed a lat, lon coordinate pair. See the FasterMarkerCluster for an example of a custom callback.
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls.
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).
  • options (dict, default None) – A dictionary with options for Leaflet.markercluster. See https://github.com/Leaflet/Leaflet.markercluster for options.
class folium.plugins.FeatureGroupSubGroup(group, name=None, overlay=True, control=True, show=True)

Bases: folium.map.Layer

Creates a Feature Group that adds its child layers into a parent group when added to a map (e.g. through LayerControl). Useful to create nested groups, or cluster markers from multiple overlays. From [0].

[0] https://github.com/ghybs/Leaflet.FeatureGroup.SubGroup

Parameters:
  • group (Layer) – The MarkerCluster or FeatureGroup containing this subgroup.
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).

Examples

>>> fg = folium.FeatureGroup()                          # Main group
>>> g1 = folium.plugins.FeatureGroupSubGroup(fg, 'g1')  # First subgroup of fg
>>> g2 = folium.plugins.FeatureGroupSubGroup(fg, 'g2')  # Second subgroup of fg
>>> m.add_child(fg)
>>> m.add_child(g1)
>>> m.add_child(g2)
>>> g1.add_child(folium.Marker([0,0]))
>>> g2.add_child(folium.Marker([0,1]))
>>> folium.LayerControl().add_to(m)
>>> mcg = folium.plugins.MarkerCluster(control=False)   # Marker Cluster, hidden in controls
>>> g1 = folium.plugins.FeatureGroupSubGroup(mcg, 'g1') # First group, in mcg
>>> g2 = folium.plugins.FeatureGroupSubGroup(mcg, 'g2') # Second group, in mcg
>>> m.add_child(mcg)
>>> m.add_child(g1)
>>> m.add_child(g2)
>>> g1.add_child(folium.Marker([0,0]))
>>> g2.add_child(folium.Marker([0,1]))
>>> folium.LayerControl().add_to(m)
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.FloatImage(image, bottom=75, left=75)

Bases: branca.element.MacroElement

Adds a floating image in HTML canvas on top of the map.

class folium.plugins.Fullscreen(position='topleft', title='Full Screen', title_cancel='Exit Full Screen', force_separate_button=False)

Bases: branca.element.MacroElement

Adds a fullscreen button to your map.

Parameters:
  • position (str) – change the position of the button can be: ‘topleft’, ‘topright’, ‘bottomright’ or ‘bottomleft’ default: ‘topleft’
  • title (str) – change the title of the button, default: ‘Full Screen’
  • title_cancel (str) – change the title of the button when fullscreen is on, default: ‘Exit Full Screen’
  • force_separate_button (boolean) – force seperate button to detach from zoom buttons, default: False
  • https (See) –
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.HeatMap(data, name=None, min_opacity=0.5, max_zoom=18, max_val=1.0, radius=25, blur=15, gradient=None, overlay=True, control=True, show=True)

Bases: folium.map.Layer

Create a Heatmap layer

Parameters:
  • data (list of points of the form [lat, lng] or [lat, lng, weight]) – The points you want to plot. You can also provide a numpy.array of shape (n,2) or (n,3).
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls.
  • min_opacity (default 1.) – The minimum opacity the heat will start at.
  • max_zoom (default 18) – Zoom level where the points reach maximum intensity (as intensity scales with zoom), equals maxZoom of the map by default
  • max_val (float, default 1.) – Maximum point intensity
  • radius (int, default 25) – Radius of each “point” of the heatmap
  • blur (int, default 15) – Amount of blur
  • gradient (dict, default None) – Color gradient config. e.g. {0.4: ‘blue’, 0.65: ‘lime’, 1: ‘red’}
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.HeatMapWithTime(data, index=None, name=None, radius=15, min_opacity=0, max_opacity=0.6, scale_radius=False, gradient=None, use_local_extrema=False, auto_play=False, display_index=True, index_steps=1, min_speed=0.1, max_speed=10, speed_step=0.1, position='bottomleft', overlay=True, control=True, show=True)

Bases: folium.map.Layer

Create a HeatMapWithTime layer

Parameters:
  • data (list of list of points of the form [lat, lng] or [lat, lng, weight]) – The points you want to plot. The outer list corresponds to the various time steps in sequential order. (weight is in (0, 1] range and defaults to 1 if not specified for a point)
  • index (Index giving the label (or timestamp) of the elements of data. Should have) – the same length as data, or is replaced by a simple count if not specified.
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls.
  • radius (default 15.) – The radius used around points for the heatmap.
  • min_opacity (default 0) – The minimum opacity for the heatmap.
  • max_opacity (default 0.6) – The maximum opacity for the heatmap.
  • scale_radius (default False) – Scale the radius of the points based on the zoom level.
  • gradient (dict, default None) – Match point density values to colors. Color can be a name (‘red’), RGB values (‘rgb(255,0,0)’) or a hex number (‘#FF0000’).
  • use_local_extrema (default False) – Defines whether the heatmap uses a global extrema set found from the input data OR a local extrema (the maximum and minimum of the currently displayed view).
  • auto_play (default False) – Automatically play the animation across time.
  • display_index (default True) – Display the index (usually time) in the time control.
  • index_steps (default 1) – Steps to take in the index dimension between aimation steps.
  • min_speed (default 0.1) – Minimum fps speed for animation.
  • max_speed (default 10) – Maximum fps speed for animation.
  • speed_step (default 0.1) – Step between different fps speeds on the speed slider.
  • position (default 'bottomleft') – Position string for the time slider. Format: ‘bottom/top’+’left/right’.
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.MarkerCluster(locations=None, popups=None, icons=None, name=None, overlay=True, control=True, show=True, icon_create_function=None, options=None)

Bases: folium.map.Layer

Provides Beautiful Animated Marker Clustering functionality for maps.

Parameters:
  • locations (list of list or array of shape (n, 2)) – Data points of the form [[lat, lng]].
  • popups (list of length n, default None) – Popup for each marker, either a Popup object or a string or None.
  • icons (list of length n, default None) – Icon for each marker, either an Icon object or a string or None.
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).
  • icon_create_function (string, default None) – Override the default behaviour, making possible to customize markers colors and sizes.
  • options (dict, default None) – A dictionary with options for Leaflet.markercluster. See https://github.com/Leaflet/Leaflet.markercluster for options.

Example

>>> icon_create_function = '''
...     function(cluster) {
...     return L.divIcon({html: '<b>' + cluster.getChildCount() + '</b>',
...                       className: 'marker-cluster marker-cluster-small',
...                       iconSize: new L.Point(20, 20)});
...     }
... '''
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.MeasureControl(position='topright', primary_length_unit='meters', secondary_length_unit='miles', primary_area_unit='sqmeters', secondary_area_unit='acres')

Bases: branca.element.MacroElement

Adds a measurem widget on the map.

Parameters:
  • position (location of the widget) – default is ‘topright’.
  • and secondary_length_unit (primary_length_unit) – defaults are ‘meters’ and ‘miles’ respectively.
  • and secondary_area_unit (primary_area_unit) – defaults are ‘sqmeters’ and ‘acres’ respectively.
  • https (See) –
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.MousePosition(position='bottomright', separator=' : ', empty_string='Unavailable', lng_first=False, num_digits=5, prefix='', lat_formatter=None, lng_formatter=None)

Bases: branca.element.MacroElement

Add a field that shows the coordinates of the mouse position.

Uses the Leaflet plugin by Ardhi Lukianto under MIT license. https://github.com/ardhi/Leaflet.MousePosition

Parameters:
  • position (str, default 'bottomright') – The standard Control position parameter for the widget.
  • separator (str, default ' : ') – Character used to separate latitude and longitude values.
  • empty_string (str, default 'Unavailable') – Initial text to display.
  • lng_first (bool, default False) – Whether to put the longitude first or not. Set as True to display longitude before latitude.
  • num_digits (int, default '5') – Number of decimal places included in the displayed longitude and latitude decimal degree values.
  • prefix (str, default '') – A string to be prepended to the coordinates.
  • lat_formatter (str, default None) – Custom Javascript function to format the latitude value.
  • lng_formatter (str, default None) – Custom Javascript function to format the longitude value.

Examples

>>> fmtr = "function(num) {return L.Util.formatNum(num, 3) + ' º ';};"
>>> MousePosition(position='topright', separator=' | ', prefix="Mouse:",
...               lat_formatter=fmtr, lng_formatter=fmtr)
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.PolyLineTextPath(polyline, text, repeat=False, center=False, below=False, offset=0, orientation=0, attributes=None)

Bases: branca.element.MacroElement

Shows a text along a PolyLine.

Parameters:
  • polyline (folium.features.PolyLine object) – The folium.features.PolyLine object to attach the text to.
  • text (string) – The string to be attached to the polyline.
  • repeat (bool, default False) – Specifies if the text should be repeated along the polyline.
  • center (bool, default False) – Centers the text according to the polyline’s bounding box
  • below (bool, default False) – Show text below the path
  • offset (int, default 0) – Set an offset to position text relative to the polyline.
  • orientation (int, default 0) – Rotate text to a specified angle.
  • attributes (dict) – Object containing the attributes applied to the text tag. Check valid attributes here: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/text#Attributes Example: {‘fill’: ‘#007DEF’, ‘font-weight’: ‘bold’, ‘font-size’: ‘24’}
  • https (See) –
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.ScrollZoomToggler

Bases: branca.element.MacroElement

Creates a button for enabling/disabling scroll on the Map.

class folium.plugins.Terminator

Bases: branca.element.MacroElement

Leaflet.Terminator is a simple plug-in to the Leaflet library to overlay day and night regions on maps.

render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.TimeSliderChoropleth(data, styledict, name=None, overlay=True, control=True, show=True)

Bases: folium.features.GeoJson

Creates a TimeSliderChoropleth plugin to append into a map with Map.add_child.

Parameters:
  • data (str) – geojson string
  • styledict (dict) – A dictionary where the keys are the geojson feature ids and the values are dicts of {time: style_options_dict}
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls.
  • overlay (bool, default False) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).
render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.TimestampedGeoJson(data, transition_time=200, loop=True, auto_play=True, add_last_point=True, period='P1D', min_speed=0.1, max_speed=10, loop_button=False, date_options='YYYY-MM-DD HH:mm:ss', time_slider_drag_update=False, duration=None)

Bases: branca.element.MacroElement

Creates a TimestampedGeoJson plugin from timestamped GeoJSONs to append into a map with Map.add_child.

A geo-json is timestamped if: * it contains only features of types LineString, MultiPoint, MultiLineString,

Polygon and MultiPolygon.
  • each feature has a ‘times’ property with the same length as the coordinates array.
  • each element of each ‘times’ property is a timestamp in ms since epoch, or in ISO string.

Eventually, you may have Point features with a ‘times’ property being an array of length 1.

Parameters:
  • data (file, dict or str.) –

    The timestamped geo-json data you want to plot. * If file, then data will be read in the file and fully embedded in

    Leaflet’s javascript.
    • If dict, then data will be converted to json and embedded in the javascript.
    • If str, then data will be passed to the javascript as-is.
  • transition_time (int, default 200.) – The duration in ms of a transition from between timestamps.
  • loop (bool, default True) – Whether the animation shall loop.
  • auto_play (bool, default True) – Whether the animation shall start automatically at startup.
  • add_last_point (bool, default True) – Whether a point is added at the last valid coordinate of a LineString.
  • period (str, default "P1D") – Used to construct the array of available times starting from the first available time. Format: ISO8601 Duration ex: ‘P1M’ 1/month, ‘P1D’ 1/day, ‘PT1H’ 1/hour, and ‘PT1M’ 1/minute
  • duration (str, default None) – Period of time which the features will be shown on the map after their time has passed. If None, all previous times will be shown. Format: ISO8601 Duration ex: ‘P1M’ 1/month, ‘P1D’ 1/day, ‘PT1H’ 1/hour, and ‘PT1M’ 1/minute

Examples

>>> TimestampedGeoJson({
...     'type': 'FeatureCollection',
...     'features': [
...       {
...         'type': 'Feature',
...         'geometry': {
...           'type': 'LineString',
...           'coordinates': [[-70,-25],[-70,35],[70,35]],
...           },
...         'properties': {
...           'times': [1435708800000, 1435795200000, 1435881600000]
...           }
...         }
...       ]
...     })

See https://github.com/socib/Leaflet.TimeDimension for more information.

render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.TimestampedWmsTileLayers(data, transition_time=200, loop=False, auto_play=False, period='P1D', time_interval=False, name=None, overlay=True, control=True, show=True)

Bases: folium.map.Layer

Creates a TimestampedWmsTileLayer that takes a WmsTileLayer and adds time control with the Leaflet.TimeDimension plugin.

Parameters:
  • data (WmsTileLayer.) – The WmsTileLayer that you want to add time support to. Must be created like a typical WmsTileLayer and added to the map before being passed to this class.
  • transition_time (int, default 200.) – The duration in ms of a transition from between timestamps.
  • loop (bool, default False) – Whether the animation shall loop, default is to reduce load on WMS services.
  • auto_play (bool, default False) – Whether the animation shall start automatically at startup, default is to reduce load on WMS services.
  • period (str, default 'P1D') – Used to construct the array of available times starting from the first available time. Format: ISO8601 Duration ex: ‘P1M’ -> 1/month, ‘P1D’ -> 1/day, ‘PT1H’ -> 1/hour, and ‘PT1M’ -> 1/minute Note: this seems to be overridden by the WMS Tile Layer GetCapabilities.
  • name (string, default None) – The name of the Layer, as it will appear in LayerControls.
  • overlay (bool, default True) – Adds the layer as an optional overlay (True) or the base layer (False).
  • control (bool, default True) – Whether the Layer will be included in LayerControls.
  • show (bool, default True) – Whether the layer will be shown on opening (only for overlays).

Examples

>>> w0 = features.WmsTileLayer(
...          'http://this.wms.server/ncWMS/wms',
...          name='Test WMS Data',
...          styles='',
...          fmt='image/png',
...          transparent=True,
...          layers='test_data',
...          COLORSCALERANGE='0,10',
...)
>>> w0.add_to(m)
>>> w1 = features.WmsTileLayer(
...          'http://this.wms.server/ncWMS/wms',
...          name='Test WMS Data',
...          styles='',
...          fmt='image/png',
...          transparent=True,
...          layers='test_data_2',
...          COLORSCALERANGE='0,5',
...)
>>> w1.add_to(m)
>>> # Add WmsTileLayers to time control.
>>> time = plugins.TimestampedWmsTileLayers([w0, w1])
>>> time.add_to(m)

See https://github.com/socib/Leaflet.TimeDimension for more information.

render(**kwargs)

Renders the HTML representation of the element.

class folium.plugins.Search(data, search_zoom=12, search_label='name', geom_type='Point', position='topleft')

Bases: branca.element.MacroElement

Adds a search tool to your map.

Parameters:
  • data (str/JSON) – GeoJSON strings
  • search_zoom (int) – zoom level when searching features, default 12
  • search_label (str) – label to index the search, default ‘name’
  • geom_type (str) – geometry type, default ‘Point’
  • position (str) – Change the position of the search bar, can be: ‘topleft’, ‘topright’, ‘bottomright’ or ‘bottomleft’, default ‘topleft’
  • https (See) –
render(**kwargs)

Renders the HTML representation of the element.