geemap package¶

Submodules¶

geemap.basemaps module¶

Module for basemaps.

Each basemap is defined as an item in the basemaps dictionary.

For example, to access Google basemaps, use the following:

basemaps[‘ROADMAP’]

basemaps[‘SATELLITE’]

basemaps[‘HYBRID’]

More WMS basemaps can be found at the following websites:

USGS National Map: https://viewer.nationalmap.gov/services/

MRLC NLCD Land Cover data: https://viewer.nationalmap.gov/services/

FWS NWI Wetlands data: https://www.fws.gov/wetlands/Data/Web-Map-Services.html

geemap.basemaps.get_qms(service_id)[source]¶

geemap.basemaps.get_xyz_dict(free_only=True, france=False)[source]¶

Returns a dictionary of xyz services.

Parameters:	free_only (bool, optional) – Whether to return only free xyz tile services that do not require an access token. Defaults to True. france (bool, optional) – Whether to include Geoportail France basemaps. Defaults to False.
Returns:	A dictionary of xyz services.
Return type:	dict

geemap.basemaps.qms_to_geemap(service_id)[source]¶

Convert a qms service to an ipyleaflet tile layer.

Parameters:	service_id (str) – Service ID.
Returns:	An ipyleaflet tile layer.
Return type:	ipyleaflet.TileLayer

geemap.basemaps.search_qms(keywords, limit=10)[source]¶

Search qms files for keywords. Reference: https://github.com/geopandas/xyzservices/issues/65

Parameters:	keywords (str) – Keywords to search for. limit (int) – Number of results to return.

geemap.basemaps.xyz_to_folium()[source]¶

Convert xyz tile services to folium tile layers.

Returns:	A dictionary of folium tile layers.
Return type:	dict

geemap.basemaps.xyz_to_leaflet()[source]¶

Convert xyz tile services to ipyleaflet tile layers.

Returns:	A dictionary of ipyleaflet tile layers.
Return type:	dict

geemap.basemaps.xyz_to_plotly()[source]¶

Convert xyz tile services to plotly tile layers.

Returns:	A dictionary of plotly tile layers.
Return type:	dict

geemap.basemaps.xyz_to_pydeck()[source]¶

Convert xyz tile services to pydeck custom tile layers.

Returns:	A dictionary of pydeck tile layers.
Return type:	dict

geemap.cli module¶

Console script for geemap.

geemap.conversion module¶

Module for converting Google Earth Engine (GEE) JavaScripts to Python scripts and Jupyter notebooks. - To convert a GEE JavaScript to Python script: js_to_python(in_file out_file) - To convert all GEE JavaScripts in a folder recursively to Python scripts: js_to_python_dir(in_dir, out_dir) - To convert a GEE Python script to Jupyter notebook: py_to_ipynb(in_file, template_file, out_file) - To convert all GEE Python scripts in a folder recursively to Jupyter notebooks: py_to_ipynb_dir(in_dir, template_file, out_dir) - To execute a Jupyter notebook and save output cells: execute_notebook(in_file) - To execute all Jupyter notebooks in a folder recursively: execute_notebook_dir(in_dir)

geemap.conversion.check_map_functions(input_lines)[source]¶

Extracts Earth Engine map function

Parameters:	input_lines (list) – List of Earth Engine JavaScrips
Returns:	Output JavaScript with map function
Return type:	list

geemap.conversion.convert_for_loop(line)[source]¶

Converts JavaScript for loop to Python for loop.

Parameters:	line (str) – Input JavaScript for loop
Returns:	Converted Python for loop.
Return type:	str

geemap.conversion.create_new_cell(contents, replace=False)[source]¶

Create a new cell in Jupyter notebook based on the contents.

Parameters:	contents (str) – A string of Python code.

geemap.conversion.download_gee_app(url, out_file=None)[source]¶

Downloads JavaScript source code from a GEE App

Parameters:	url (str) – The URL of the GEE App. out_file (str, optional) – The output file path for the downloaded JavaScript. Defaults to None.

geemap.conversion.execute_notebook(in_file)[source]¶

Executes a Jupyter notebook and save output cells

Parameters:	in_file (str) – Input Jupyter notebook.

geemap.conversion.execute_notebook_dir(in_dir)[source]¶

Executes all Jupyter notebooks in the given directory recursively and save output cells.

Parameters:	in_dir (str) – Input folder containing notebooks.

geemap.conversion.find_matching_bracket(lines, start_line_index, start_char_index, matching_char='{')[source]¶

Finds the position of the matching closing bracket from a list of lines.

Parameters:	lines (list) – The input list of lines. start_line_index (int) – The line index where the starting bracket is located. start_char_index (int) – The position index of the starting bracket. matching_char (str, optional) – The starting bracket to search for. Defaults to ‘{‘.
Returns:	The line index where the matching closing bracket is located. matching_char_index (int): The position index of the matching closing bracket.
Return type:	matching_line_index (int)

geemap.conversion.format_params(line, sep=':')[source]¶

Formats keys in a dictionary and adds quotes to the keys. For example, {min: 0, max: 10} will result in (‘min’: 0, ‘max’: 10)

Parameters:	line (str) – A string. sep (str, optional) – Separator. Defaults to ‘:’.
Returns:	A string with keys quoted
Return type:	[str]

geemap.conversion.get_js_examples(out_dir=None)[source]¶

Gets Earth Engine JavaScript examples from the geemap package.

Parameters:	out_dir (str, optional) – The folder to copy the JavaScript examples to. Defaults to None.
Returns:	The folder containing the JavaScript examples.
Return type:	str

geemap.conversion.get_nb_template(download_latest=False, out_file=None)[source]¶

Get the Earth Engine Jupyter notebook template.

Parameters:	download_latest (bool, optional) – If True, downloads the latest notebook template from GitHub. Defaults to False. out_file (str, optional) – Set the output file path of the notebook template. Defaults to None.
Returns:	The file path of the template.
Return type:	str

geemap.conversion.js_snippet_to_py(in_js_snippet, add_new_cell=True, import_ee=True, import_geemap=False, show_map=True)[source]¶

Converts an Earth Engine JavaScript snippet wrapped in triple quotes to Python directly on a Jupyter notebook.

Parameters:	in_js_snippet (str) – Earth Engine JavaScript within triple quotes. add_new_cell (bool, optional) – Whether add the converted Python to a new cell. import_ee (bool, optional) – Whether to import ee. Defaults to True. import_geemap (bool, optional) – Whether to import geemap. Defaults to False. show_map (bool, optional) – Whether to show the map. Defaults to True.
Returns:	A list of Python script.
Return type:	list

geemap.conversion.js_to_python(in_file, out_file=None, use_qgis=True, github_repo=None, show_map=True, import_geemap=False)[source]¶

Converts an Earth Engine JavaScript to Python script.

Args:

in_file (str): File path of the input JavaScript. out_file (str, optional): File path of the output Python script. Defaults to None. use_qgis (bool, optional): Whether to add “from ee_plugin import Map

” to the output script. Defaults to True.

github_repo (str, optional): GitHub repo url. Defaults to None. show_map (bool, optional): Whether to add “Map” to the output script. Defaults to True. import_geemap (bool, optional): Whether to add “import geemap” to the output script. Defaults to False.

Returns:: list: Python script

geemap.conversion.js_to_python_dir(in_dir, out_dir=None, use_qgis=True, github_repo=None)[source]¶

Converts all Earth Engine JavaScripts in a folder recursively to Python scripts.

Args:

in_dir (str): The input folder containing Earth Engine JavaScripts. out_dir (str, optional): The output folder containing Earth Engine Python scripts. Defaults to None. use_qgis (bool, optional): Whether to add “from ee_plugin import Map

” to the output script. Defaults to True.: github_repo (str, optional): GitHub repo url. Defaults to None.

geemap.conversion.py_to_ipynb(in_file, template_file=None, out_file=None, github_username=None, github_repo=None)[source]¶

Converts Earth Engine Python script to Jupyter notebook.

Parameters:	in_file (str) – Input Earth Engine Python script. template_file (str) – Input Jupyter notebook template. out_file (str, optional)) – Output Jupyter notebook. github_username (str, optional) – GitHub username. Defaults to None. github_repo (str, optional) – GitHub repo name. Defaults to None.

geemap.conversion.py_to_ipynb_dir(in_dir, template_file=None, out_dir=None, github_username=None, github_repo=None)[source]¶

Converts Earth Engine Python scripts in a folder recursively to Jupyter notebooks.

Parameters:	in_dir (str) – Input folder containing Earth Engine Python scripts. str, optional) (out_dir) – Output folder. Defaults to None. template_file (str) – Input jupyter notebook template file. github_username (str, optional) – GitHub username. Defaults to None. github_repo (str, optional) – GitHub repo name. Defaults to None.

geemap.conversion.remove_qgis_import(in_file)[source]¶

Removes ‘from ee_plugin import Map’ from an Earth Engine Python script.

Parameters:	in_file (str) – Input file path of the Python script.
Returns:	List of lines ‘from ee_plugin import Map’ removed.
Return type:	list

geemap.conversion.template_footer(in_template)[source]¶

Extracts footer from the notebook template.

Parameters:	in_template (str) – Input notebook template file path.
Returns:	List of lines.
Return type:	list

geemap.conversion.template_header(in_template)[source]¶

Extracts header from the notebook template.

Parameters:	in_template (str) – Input notebook template file path.
Returns:	List of lines.
Return type:	list

geemap.conversion.update_nb_header(in_file, github_username=None, github_repo=None)[source]¶

Updates notebook header (binder and Google Colab URLs).

Parameters:	in_file (str) – The input Jupyter notebook. github_username (str, optional) – GitHub username. Defaults to None. github_repo (str, optional) – GitHub repo name. Defaults to None.

geemap.conversion.update_nb_header_dir(in_dir, github_username=None, github_repo=None)[source]¶

Updates header (binder and Google Colab URLs) of all notebooks in a folder .

Parameters:	in_dir (str) – The input directory containing Jupyter notebooks. github_username (str, optional) – GitHub username. Defaults to None. github_repo (str, optional) – GitHub repo name. Defaults to None.

geemap.conversion.use_math(lines)[source]¶

Checks if an Earth Engine uses Math library

Parameters:	lines (list) – An Earth Engine JavaScript.
Returns:	Returns True if the script contains ‘Math.’. For example ‘Math.PI’, ‘Math.pow’
Return type:	[bool]

geemap.foliumap module¶

Module for creating interactive maps with the folium library.

class geemap.foliumap.CustomControl(html, position='bottomleft')[source]¶

Bases: branca.element.MacroElement

Put any HTML on the map as a Leaflet Control. Adopted from https://github.com/python-visualization/folium/pull/1662

class geemap.foliumap.FloatText(text, bottom=75, left=75)[source]¶

Bases: branca.element.MacroElement

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

class geemap.foliumap.Map(**kwargs)[source]¶

Bases: folium.folium.Map

The Map class inherits from folium.Map. By default, the Map will add Google Maps as the basemap. Set add_google_map = False to use OpenStreetMap as the basemap.

Returns:	folium map object.
Return type:	object

addLayer(ee_object, vis_params={}, name='Layer untitled', shown=True, opacity=1.0, **kwargs)¶

Adds a given EE object to the map as a layer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer untitled’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

addLayerControl()¶: Adds layer control to the map.

add_basemap(basemap='HYBRID')[source]¶

Adds a basemap to the map.

Parameters:	basemap (str, optional) – Can be one of string from ee_basemaps. Defaults to ‘HYBRID’.

add_census_data(wms, layer, census_dict=None, **kwargs)[source]¶

Adds a census data layer to the map.

Parameters:	wms (str) – The wms to use. For example, “Current”, “ACS 2021”, “Census 2020”. See the complete list at https://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_wms.html layer (str) – The layer name to add to the map. census_dict (dict, optional) – A dictionary containing census data. Defaults to None. It can be obtained from the get_census_dict() function.

add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, tooltip=None, min_width=100, max_width=200, **kwargs)[source]¶

Adds a marker cluster to the map.

Parameters:

data (str | pd.DataFrame) – A csv or Pandas DataFrame containing x, y, z values.
x (str, optional) – The column name for the x values. Defaults to “longitude”.
y (str, optional) – The column name for the y values. Defaults to “latitude”.
radius (int, optional) – The radius of the circle. Defaults to 10.
popup (list, optional) – A list of column names to be used as the popup. Defaults to None.
tooltip (list, optional) – A list of column names to be used as the tooltip. Defaults to None.
min_width (int, optional) – The minimum width of the popup. Defaults to 100.
max_width (int, optional) – The maximum width of the popup. Defaults to 200.

add_cog_layer(url, name='Untitled', attribution='.', opacity=1.0, shown=True, bands=None, titiler_endpoint=None, **kwargs)[source]¶

Adds a COG TileLayer to the map.

Parameters:

url (str) – The URL of the COG tile layer.
name (str, optional) – The layer name to use for the layer. Defaults to ‘Untitled’.
attribution (str, optional) – The attribution to use. Defaults to ‘.’.
opacity (float, optional) – The opacity of the layer. Defaults to 1.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
bands (list, optional) – A list of bands to use. Defaults to None.
titiler_endpoint (str, optional) – Titiler endpoint. Defaults to “https://titiler.xyz”.

add_cog_mosaic(**kwargs)[source]¶

add_colorbar(vis_params, index=None, label='', categorical=False, step=None, background_color=None, **kwargs)[source]¶

Add a colorbar to the map.

Parameters:

colors (list) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)
vmin (int, optional) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].. Defaults to 0.
vmax (float, optional) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.
index (list, optional) – The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.. Defaults to None.
label (str, optional) – The caption for the colormap. Defaults to “”.
categorical (bool, optional) – Whether or not to create a categorical colormap. Defaults to False.
step (int, optional) – The step to split the LinearColormap into a StepColormap. Defaults to None.

add_colorbar_branca(vis_params, index=None, label='', categorical=False, step=None, background_color=None, **kwargs)¶

Add a colorbar to the map.

Parameters:

colors (list) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)
vmin (int, optional) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].. Defaults to 0.
vmax (float, optional) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.
index (list, optional) – The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.. Defaults to None.
label (str, optional) – The caption for the colormap. Defaults to “”.
categorical (bool, optional) – Whether or not to create a categorical colormap. Defaults to False.
step (int, optional) – The step to split the LinearColormap into a StepColormap. Defaults to None.

add_colormap(width=4.0, height=0.3, vmin=0, vmax=1.0, palette=None, vis_params=None, cmap='gray', discrete=False, label=None, label_size=10, label_weight='normal', tick_size=8, bg_color='white', orientation='horizontal', dpi='figure', transparent=False, position=(70, 5), **kwargs)[source]¶

Add a colorbar to the map. Under the hood, it uses matplotlib to generate the colorbar, save it as a png file, and add it to the map using m.add_image().

Parameters:	width (float) – Width of the colorbar in inches. Default is 4.0. height (float) – Height of the colorbar in inches. Default is 0.3. vmin (float) – Minimum value of the colorbar. Default is 0. vmax (float) – Maximum value of the colorbar. Default is 1.0. palette (list) – List of colors to use for the colorbar. It can also be a cmap name, such as ndvi, ndwi, dem, coolwarm. Default is None. vis_params (dict) – Visualization parameters as a dictionary. See https://developers.google.com/earth-engine/guides/image_visualization for options. cmap (str, optional) – Matplotlib colormap. Defaults to “gray”. See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py for options. discrete (bool, optional) – Whether to create a discrete colorbar. Defaults to False. label (str, optional) – Label for the colorbar. Defaults to None. label_size (int, optional) – Font size for the colorbar label. Defaults to 12. label_weight (str, optional) – Font weight for the colorbar label, can be “normal”, “bold”, etc. Defaults to “normal”. tick_size (int, optional) – Font size for the colorbar tick labels. Defaults to 10. bg_color (str, optional) – Background color for the colorbar. Defaults to “white”. orientation (str, optional) – Orientation of the colorbar, such as “vertical” and “horizontal”. Defaults to “horizontal”. dpi (float \| str, optional) – The resolution in dots per inch. If ‘figure’, use the figure’s dpi value. Defaults to “figure”. transparent (bool, optional) – Whether to make the background transparent. Defaults to False. position (tuple, optional) – The position of the colormap in the format of (x, y), the percentage ranging from 0 to 100, starting from the lower-left corner. Defaults to (0, 0). **kwargs – Other keyword arguments to pass to matplotlib.pyplot.savefig().
Returns:	Path to the output image.
Return type:	str

add_data(data, column, colors=None, labels=None, cmap=None, scheme='Quantiles', k=5, add_legend=True, legend_title=None, legend_kwds=None, classification_kwds=None, style_function=None, highlight_function=None, layer_name='Untitled', info_mode='on_hover', encoding='utf-8', **kwargs)[source]¶

Add vector data to the map with a variety of classification schemes.

Parameters:

data (str | pd.DataFrame | gpd.GeoDataFrame) – The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.
column (str) – The column to classify.
cmap (str, optional) – The name of a colormap recognized by matplotlib. Defaults to None.
colors (list, optional) – A list of colors to use for the classification. Defaults to None.
labels (list, optional) – A list of labels to use for the legend. Defaults to None.
scheme (str, optional) – Name of a choropleth classification scheme (requires mapclassify). Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. ‘BoxPlot’, ‘EqualInterval’, ‘FisherJenks’, ‘FisherJenksSampled’, ‘HeadTailBreaks’, ‘JenksCaspall’, ‘JenksCaspallForced’, ‘JenksCaspallSampled’, ‘MaxP’, ‘MaximumBreaks’, ‘NaturalBreaks’, ‘Quantiles’, ‘Percentiles’, ‘StdMean’, ‘UserDefined’). Arguments can be passed in classification_kwds.
k (int, optional) – Number of classes (ignored if scheme is None or if column is categorical). Default to 5.
legend_kwds (dict, optional) –
Keyword arguments to pass to matplotlib.pyplot.legend() or matplotlib.pyplot.colorbar. Defaults to None. Keyword arguments to pass to matplotlib.pyplot.legend() or Additional accepted keywords when scheme is specified: fmt : string

A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals: {"fmt": "{:.0f}"}.

labels : list-like

A list of legend labels to override the auto-generated labblels. Needs to have the same number of elements as the number of classes (k).

interval : boolean (default False)

An option to control brackets from mapclassify legend. If True, open/closed interval brackets are shown in the legend.
classification_kwds (dict, optional) – Keyword arguments to pass to mapclassify. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style_function (function, optional) –
Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None. style_callback is a function that takes the feature as argument and should return a dictionary of the following form: style_callback = lambda feat: {“fillColor”: feat[“properties”][“color”]} style is a dictionary of the following form:

style = { “stroke”: False, “color”: “#ff0000”, “weight”: 1, “opacity”: 1, “fill”: True, “fillColor”: “#ffffff”, “fillOpacity”: 1.0, “dashArray”: “9” “clickable”: True,

}
hightlight_function (function, optional) – Highlighting function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None. highlight_function is a function that takes the feature as argument and should return a dictionary of the following form: highlight_function = lambda feat: {“fillColor”: feat[“properties”][“color”]}
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding of the GeoJSON file. Defaults to “utf-8”.

add_gdf(gdf, layer_name='Untitled', zoom_to_layer=True, info_mode='on_hover', fields=None, **kwargs)[source]¶

Adds a GeoPandas GeoDataFrame to the map.

Parameters:

gdf (GeoDataFrame) – A GeoPandas GeoDataFrame.
layer_name (str, optional) – The layer name to be used. Defaults to “Untitled”.
zoom_to_layer (bool, optional) – Whether to zoom to the layer.
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
fields (list, optional) – The fields to be displayed in the popup. Defaults to None.

add_gdf_from_postgis(sql, con, layer_name='Untitled', zoom_to_layer=True, **kwargs)[source]¶

Adds a GeoPandas GeoDataFrameto the map.

Parameters:	sql (str) – SQL query to execute in selecting entries from database, or name of the table to read from the database. con (sqlalchemy.engine.Engine) – Active connection to the database to query. layer_name (str, optional) – The layer name to be used. Defaults to “Untitled”. zoom_to_layer (bool, optional) – Whether to zoom to the layer.

add_geojson(in_geojson, layer_name='Untitled', encoding='utf-8', info_mode='on_hover', fields=None, **kwargs)[source]¶

Adds a GeoJSON file to the map.

Parameters:

in_geojson (str) – The input file path to the GeoJSON.
layer_name (str, optional) – The layer name to be used. Defaults to “Untitled”.
encoding (str, optional) – The encoding of the GeoJSON file. Defaults to “utf-8”.
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
fields (list, optional) – The fields to be displayed in the popup. Defaults to None.

Raises:

FileNotFoundError – The provided GeoJSON file could not be found.

add_heatmap(data, latitude='latitude', longitude='longitude', value='value', name='Heat map', radius=25, **kwargs)[source]¶

Adds a heat map to the map. Reference: https://stackoverflow.com/a/54756617

Parameters:

data (str | list | pd.DataFrame) – File path or HTTP URL to the input file or a list of data points in the format of [[x1, y1, z1], [x2, y2, z2]]. For example, https://raw.githubusercontent.com/giswqs/leafmap/master/examples/data/world_cities.csv
latitude (str, optional) – The column name of latitude. Defaults to “latitude”.
longitude (str, optional) – The column name of longitude. Defaults to “longitude”.
value (str, optional) – The column name of values. Defaults to “value”.
name (str, optional) – Layer name to use. Defaults to “Heat map”.
radius (int, optional) – Radius of each “point” of the heatmap. Defaults to 25.

Raises:

ValueError – If data is not a list.

add_html(html, position='bottomright', **kwargs)[source]¶

Add HTML to the map.

Parameters:	html (str) – The HTML to add. position (str, optional) – The position of the widget. Defaults to “bottomright”.

add_image(image, position=(0, 0), **kwargs)[source]¶

Add an image to the map.

Parameters:	image (str \| ipywidgets.Image) – The image to add. position (tuple, optional) – The position of the image in the format of (x, y), the percentage ranging from 0 to 100, starting from the lower-left corner. Defaults to (0, 0).

add_kml(in_kml, layer_name='Untitled', info_mode='on_hover', fields=None, **kwargs)[source]¶

Adds a KML file to the map.

Parameters:

in_kml (str) – The input file path to the KML.
layer_name (str, optional) – The layer name to be used. Defaults to “Untitled”.
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
fields (list, optional) – The fields to be displayed in the popup. Defaults to None.

Raises:

FileNotFoundError – The provided KML file could not be found.

add_labels(data, column, font_size='12pt', font_color='black', font_family='arial', font_weight='normal', x='longitude', y='latitude', draggable=True, layer_name='Labels', **kwargs)[source]¶

Adds a label layer to the map. Reference: https://python-visualization.github.io/folium/modules.html#folium.features.DivIcon

Parameters:

data (pd.DataFrame | ee.FeatureCollection) – The input data to label.
column (str) – The column name of the data to label.
font_size (str, optional) – The font size of the labels. Defaults to “12pt”.
font_color (str, optional) – The font color of the labels. Defaults to “black”.
font_family (str, optional) – The font family of the labels. Defaults to “arial”.
font_weight (str, optional) – The font weight of the labels, can be normal, bold. Defaults to “normal”.
x (str, optional) – The column name of the longitude. Defaults to “longitude”.
y (str, optional) – The column name of the latitude. Defaults to “latitude”.
draggable (bool, optional) – Whether the labels are draggable. Defaults to True.
layer_name (str, optional) – The name of the layer. Defaults to “Labels”.

add_layer(ee_object, vis_params={}, name='Layer untitled', shown=True, opacity=1.0, **kwargs)[source]¶

Adds a given EE object to the map as a layer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer untitled’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

add_layer_control()[source]¶: Adds layer control to the map.

add_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, style={})[source]¶

Adds a customized legend to the map. Reference: https://bit.ly/3oV6vnH.: If you want to add multiple legends to the map, you need to set the draggable argument to False.

Parameters:

title (str, optional) – Title of the legend. Defaults to ‘Legend’. Defaults to “Legend”.
colors (list, optional) – A list of legend colors. Defaults to None.
labels (list, optional) – A list of legend labels. Defaults to None.
legend_dict (dict, optional) – A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.
builtin_legend (str, optional) – Name of the builtin legend to add to the map. Defaults to None.
opacity (float, optional) – The opacity of the legend. Defaults to 1.0.
position (str, optional) – The position of the legend, can be one of the following: “topleft”, “topright”, “bottomleft”, “bottomright”. Defaults to “bottomright”.
draggable (bool, optional) – If True, the legend can be dragged to a new position. Defaults to True.
style –
Additional keyword arguments to style the legend, such as position, bottom, right, z-index, border, background-color, border-radius, padding, font-size, etc. The default style is: style = {

’position’: ‘fixed’, ‘z-index’: ‘9999’, ‘border’: ‘2px solid grey’, ‘background-color’: ‘rgba(255, 255, 255, 0.8)’, ‘border-radius’: ‘5px’, ‘padding’: ‘10px’, ‘font-size’: ‘14px’, ‘bottom’: ‘20px’, ‘right’: ‘5px’

}

add_local_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Local COG', **kwargs)¶

Add a local raster dataset to the map.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = ‘proxy/{port}’

Parameters:

source (str) – The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to ‘Local COG’.

add_marker(location, popup=None, tooltip=None, icon=None, draggable=False, **kwargs)[source]¶

Adds a marker to the map. More info about marker options at https://python-visualization.github.io/folium/modules.html#folium.map.Marker.

Parameters:	location (list \| tuple) – The location of the marker in the format of [lat, lng]. popup (str, optional) – The popup text. Defaults to None. tooltip (str, optional) – The tooltip text. Defaults to None. icon (str, optional) – The icon to use. Defaults to None. draggable (bool, optional) – Whether the marker is draggable. Defaults to False.

add_markers_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Markers', icon=None, icon_shape='circle-dot', border_width=3, border_color='#0000ff', **kwargs)[source]¶

Adds markers to the map from a csv or Pandas DataFrame containing x, y values.

Parameters:

data (str | pd.DataFrame) – A csv or Pandas DataFrame containing x, y, z values.
x (str, optional) – The column name for the x values. Defaults to “longitude”.
y (str, optional) – The column name for the y values. Defaults to “latitude”.
popup (list, optional) – A list of column names to be used as the popup. Defaults to None.
min_width (int, optional) – The minimum width of the popup. Defaults to 100.
max_width (int, optional) – The maximum width of the popup. Defaults to 200.
layer_name (str, optional) – The name of the layer. Defaults to “Marker Cluster”.
icon (str, optional) – The Font-Awesome icon name to use to render the marker. Defaults to None.
icon_shape (str, optional) – The shape of the marker, such as “retangle-dot”, “circle-dot”. Defaults to ‘circle-dot’.
border_width (int, optional) – The width of the border. Defaults to 3.
border_color (str, optional) – The color of the border. Defaults to ‘#0000ff’.
kwargs (dict, optional) – Additional keyword arguments to pass to BeautifyIcon. See https://python-visualization.github.io/folium/plugins.html#folium.plugins.BeautifyIcon.

add_netcdf(filename, variables=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='NetCDF layer', shift_lon=True, lat='lat', lon='lon', **kwargs)[source]¶

Generate an ipyleaflet/folium TileLayer from a netCDF file.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer), try adding to following two lines to the beginning of the notebook if the raster does not render properly.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = f’{os.environ[‘JUPYTERHUB_SERVICE_PREFIX’].lstrip(‘/’)}/proxy/{{port}}’

Parameters:

filename (str) – File path or HTTP URL to the netCDF file.
variables (int, optional) – The variable/band names to extract data from the netCDF file. Defaults to None. If None, all variables will be extracted.
port (str, optional) – The port to use for the server. Defaults to “default”.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to “netCDF layer”.
shift_lon (bool, optional) – Flag to shift longitude values from [0, 360] to the range [-180, 180]. Defaults to True.
lat (str, optional) – Name of the latitude variable. Defaults to ‘lat’.
lon (str, optional) – Name of the longitude variable. Defaults to ‘lon’.

add_osm(query, layer_name='Untitled', which_result=None, by_osmid=False, buffer_dist=None, to_ee=False, geodesic=True, **kwargs)[source]¶

Adds OSM data to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
which_result (INT, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
by_osmid (bool, optional) – If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
to_ee (bool, optional) – Whether to convert the csv to an ee.FeatureCollection.
geodesic (bool, optional) – Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.

add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within some distance N, S, E, W of address to the map.

Parameters:

address (str) – The address to geocode and use as the central point around which to get the geometries.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
dist (int, optional) – Distance in meters. Defaults to 1000.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_bbox(north, south, east, west, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within a N, S, E, W bounding box to the map.

Parameters:

north (float) – Northern latitude of bounding box.
south (float) – Southern latitude of bounding box.
east (float) – Eastern longitude of bounding box.
west (float) – Western longitude of bounding box.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_geocode(query, which_result=None, by_osmid=False, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM data of place(s) by name or ID to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
which_result (int, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
by_osmid (bool, optional) – If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_place(query, tags, which_result=None, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within boundaries of geocodable place(s) to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
which_result (int, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within some distance N, S, E, W of a point to the map.

Parameters:

center_point (tuple) – The (lat, lng) center point around which to get the geometries.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
dist (int, optional) – Distance in meters. Defaults to 1000.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_polygon(polygon, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within boundaries of a (multi)polygon to the map.

Parameters:

polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon) – Geographic boundaries to fetch geometries within
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_planet_by_month(year=2016, month=1, name=None, api_key=None, token_name='PLANET_API_KEY')[source]¶

Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

year (int, optional) – The year of Planet global mosaic, must be >=2016. Defaults to 2016.
month (int, optional) – The month of Planet global mosaic, must be 1-12. Defaults to 1.
name (str, optional) – The layer name to use. Defaults to None.
api_key (str, optional) – The Planet API key. Defaults to None.
token_name (str, optional) – The environment variable name of the API key. Defaults to “PLANET_API_KEY”.

add_planet_by_quarter(year=2016, quarter=1, name=None, api_key=None, token_name='PLANET_API_KEY')[source]¶

Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

year (int, optional) – The year of Planet global mosaic, must be >=2016. Defaults to 2016.
quarter (int, optional) – The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
name (str, optional) – The layer name to use. Defaults to None.
api_key (str, optional) – The Planet API key. Defaults to None.
token_name (str, optional) – The environment variable name of the API key. Defaults to “PLANET_API_KEY”.

add_points_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], angle=0, prefix='fa', add_legend=True, **kwargs)[source]¶

Adds a marker cluster to the map.

Parameters:

data (str | pd.DataFrame) – A csv or Pandas DataFrame containing x, y, z values.
x (str, optional) – The column name for the x values. Defaults to “longitude”.
y (str, optional) – The column name for the y values. Defaults to “latitude”.
popup (list, optional) – A list of column names to be used as the popup. Defaults to None.
min_width (int, optional) – The minimum width of the popup. Defaults to 100.
max_width (int, optional) – The maximum width of the popup. Defaults to 200.
layer_name (str, optional) – The name of the layer. Defaults to “Marker Cluster”.
color_column (str, optional) – The column name for the color values. Defaults to None.
marker_colors (list, optional) – A list of colors to be used for the markers. Defaults to None.
icon_colors (list, optional) – A list of colors to be used for the icons. Defaults to [‘white’].
icon_names (list, optional) – A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons or https://getbootstrap.com/docs/3.3/components/?utm_source=pocket_mylist. Defaults to [‘info’].
angle (int, optional) – The angle of the icon. Defaults to 0.
prefix (str, optional) – The prefix states the source of the icon. ‘fa’ for font-awesome or ‘glyphicon’ for bootstrap 3. Defaults to ‘fa’.
add_legend (bool, optional) – If True, a legend will be added to the map. Defaults to True.

add_raster(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Local COG', **kwargs)[source]¶

Add a local raster dataset to the map.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = ‘proxy/{port}’

Parameters:

source (str) – The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to ‘Local COG’.

add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs)[source]¶

Add a remote Cloud Optimized GeoTIFF (COG) to the map.

Parameters:

source (str) – The path to the remote Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to None.

add_shapefile(in_shp, layer_name='Untitled', **kwargs)[source]¶

Adds a shapefile to the map. See https://python-visualization.github.io/folium/modules.html#folium.features.GeoJson for more info about setting style.

Parameters:	in_shp (str) – The input file path to the shapefile. layer_name (str, optional) – The layer name to be used. Defaults to “Untitled”.
Raises:	`FileNotFoundError` – The provided shapefile could not be found.

add_stac_layer(url=None, collection=None, item=None, assets=None, bands=None, titiler_endpoint=None, name='STAC Layer', attribution='.', opacity=1.0, shown=True, **kwargs)[source]¶

Adds a STAC TileLayer to the map.

Parameters:

url (str) – HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
collection (str) – The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
item (str) – The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
assets (str | list) – The Microsoft Planetary Computer STAC asset ID, e.g., [“SR_B7”, “SR_B5”, “SR_B4”].
bands (list) – A list of band names, e.g., [“SR_B7”, “SR_B5”, “SR_B4”]
titiler_endpoint (str, optional) – Titiler endpoint, e.g., “https://titiler.xyz”, “planetary-computer”, “pc”. Defaults to None.
name (str, optional) – The layer name to use for the layer. Defaults to ‘STAC Layer’.
attribution (str, optional) – The attribution to use. Defaults to ‘’.
opacity (float, optional) – The opacity of the layer. Defaults to 1.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.

add_styled_vector(ee_object, column, palette, layer_name='Untitled', shown=True, opacity=1.0, **kwargs)[source]¶

Adds a styled vector to the map.

Parameters:	ee_object (object) – An ee.FeatureCollection. column (str) – The column name to use for styling. palette (list \| dict) – The palette (e.g., list of colors or a dict containing label and color pairs) to use for styling. layer_name (str, optional) – The name to be used for the new layer. Defaults to “Untitled”.

add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs)[source]¶

Add text to the map.

Parameters:

text (str) – The text to add.
fontsize (int, optional) – The font size. Defaults to 20.
fontcolor (str, optional) – The font color. Defaults to “black”.
bold (bool, optional) – Whether to use bold font. Defaults to False.
padding (str, optional) – The padding. Defaults to “5px”.
background (bool, optional) – Whether to use background. Defaults to True.
bg_color (str, optional) – The background color. Defaults to “white”.
border_radius (str, optional) – The border radius. Defaults to “5px”.
position (str, optional) – The position of the widget. Defaults to “bottomright”.

add_tile_layer(tiles='OpenStreetMap', name='Untitled', attribution='.', overlay=True, control=True, shown=True, opacity=1.0, API_key=None, **kwargs)[source]¶

Add a XYZ tile layer to the map.

Parameters:

tiles (str) – The URL of the XYZ tile service.
name (str, optional) – The layer name to use on the layer control. Defaults to ‘Untitled’.
attribution (str, optional) – The attribution of the data layer. Defaults to ‘.’.
overlay (str, optional) – Allows overlay. Defaults to True.
control (str, optional) – Adds the layer to the layer control. Defaults to True.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – Sets the opacity for the layer.
API_key (str, optional) – – API key for Cloudmade or Mapbox tiles. Defaults to True.

add_time_slider(ee_object, vis_params={}, region=None, layer_name='Time series', labels=None, time_interval=1, position='bottomright', slider_length='150px', date_format='YYYY-MM-dd', opacity=1.0, **kwargs)[source]¶

add_widget(content, position='bottomright', **kwargs)[source]¶

Add a widget (e.g., text, HTML, figure) to the map.

Parameters:	content (str) – The widget to add. position (str, optional) – The position of the widget. Defaults to “bottomright”.

add_wms_layer(url, layers, name=None, attribution='', overlay=True, control=True, shown=True, format='image/png', transparent=True, version='1.1.1', styles='', **kwargs)[source]¶

Add a WMS layer to the map.

Parameters:

url (str) – The URL of the WMS web service.
layers (str) – Comma-separated list of WMS layers to show.
name (str, optional) – The layer name to use on the layer control. Defaults to None.
attribution (str, optional) – The attribution of the data layer. Defaults to ‘’.
overlay (str, optional) – Allows overlay. Defaults to True.
control (str, optional) – Adds the layer to the layer control. Defaults to True.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
format (str, optional) – WMS image format (use ‘image/png’ for layers with transparency). Defaults to ‘image/png’.
transparent (bool, optional) – Whether the layer shall allow transparency. Defaults to True.
version (str, optional) – Version of the WMS service to use. Defaults to “1.1.1”.
styles (str, optional) – Comma-separated list of WMS styles. Defaults to “”.

add_xyz_service(provider, **kwargs)[source]¶

Add a XYZ tile layer to the map.

Parameters:	provider (str) – A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,
Raises:	`ValueError` – The provider is not valid. It must start with xyz or qms.

basemap_demo()[source]¶: A demo for using geemap basemaps.

centerObject(ee_object, zoom=None)¶

Centers the map view on a given object.

Parameters:	ee_object (Element\|Geometry) – An Earth Engine object to center on a geometry, image or feature. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

center_object(ee_object, zoom=None)[source]¶

Centers the map view on a given object.

Parameters:	ee_object (Element\|Geometry) – An Earth Engine object to center on a geometry, image or feature. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

extract_values_to_points(filename)[source]¶

publish(name='Folium Map', description='', source_url='', tags=None, source_file=None, open=True, formatting=None, token=None, **kwargs)[source]¶

Publish the map to datapane.com

Parameters:

name (str, optional) – The document name - can include spaces, caps, symbols, etc., e.g. “Profit & Loss 2020”. Defaults to “Folium Map”.
description (str, optional) – A high-level description for the document, this is displayed in searches and thumbnails. Defaults to ‘’.
source_url (str, optional) – A URL pointing to the source code for the document, e.g. a GitHub repo or a Colab notebook. Defaults to ‘’.
tags (bool, optional) – A list of tags (as strings) used to categorise your document. Defaults to None.
source_file (str, optional) – Path of jupyter notebook file to upload. Defaults to None.
open (bool, optional) – Whether to open the map. Defaults to True.
formatting (ReportFormatting, optional) – Set the basic styling for your report.
token (str, optional) – The token to use to datapane to publish the map. See https://docs.datapane.com/tut-getting-started. Defaults to None.

remove_labels(**kwargs)[source]¶: Removes a layer from the map.

setCenter(lon, lat, zoom=10)¶

Centers the map view at a given coordinates with the given zoom level.

Parameters:	lon (float) – The longitude of the center, in degrees. lat (float) – The latitude of the center, in degrees. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to 10.

setControlVisibility(layerControl=True, fullscreenControl=True, latLngPopup=True)¶

Sets the visibility of the controls on the map.

Parameters:

layerControl (bool, optional) – Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
fullscreenControl (bool, optional) – Whether to show the control that allows the user to make the map full-screen. Defaults to True.
latLngPopup (bool, optional) – Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.

setOptions(mapTypeId='HYBRID', styles={}, types=[])[source]¶

Adds Google basemap to the map.

Parameters:

mapTypeId (str, optional) – A mapTypeId to set the basemap to. Can be one of “ROADMAP”, “SATELLITE”, “HYBRID” or “TERRAIN” to select one of the standard Google Maps API map types. Defaults to ‘HYBRID’.
styles ([type], optional) – A dictionary of custom MapTypeStyle objects keyed with a name that will appear in the map’s Map Type Controls. Defaults to None.
types ([type], optional) – A list of mapTypeIds to make available. If omitted, but opt_styles is specified, appends all of the style keys to the standard Google Maps API map types.. Defaults to None.

set_center(lon, lat, zoom=10)[source]¶

Centers the map view at a given coordinates with the given zoom level.

Parameters:	lon (float) – The longitude of the center, in degrees. lat (float) – The latitude of the center, in degrees. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to 10.

set_control_visibility(layerControl=True, fullscreenControl=True, latLngPopup=True)[source]¶

Sets the visibility of the controls on the map.

Parameters:

layerControl (bool, optional) – Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
fullscreenControl (bool, optional) – Whether to show the control that allows the user to make the map full-screen. Defaults to True.
latLngPopup (bool, optional) – Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.

set_options(mapTypeId='HYBRID', styles={}, types=[])¶

Adds Google basemap to the map.

Parameters:

mapTypeId (str, optional) – A mapTypeId to set the basemap to. Can be one of “ROADMAP”, “SATELLITE”, “HYBRID” or “TERRAIN” to select one of the standard Google Maps API map types. Defaults to ‘HYBRID’.
styles ([type], optional) – A dictionary of custom MapTypeStyle objects keyed with a name that will appear in the map’s Map Type Controls. Defaults to None.
types ([type], optional) – A list of mapTypeIds to make available. If omitted, but opt_styles is specified, appends all of the style keys to the standard Google Maps API map types.. Defaults to None.

set_plot_options(**kwargs)[source]¶: Sets plotting options.

split_map(left_layer='TERRAIN', right_layer='OpenTopoMap', left_args={}, right_args={}, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', **kwargs)[source]¶

Adds a split-panel map.

Parameters:

left_layer (str, optional) – The left tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to ‘TERRAIN’.
right_layer (str, optional) – The right tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to ‘OpenTopoMap’.
left_args (dict, optional) – The arguments for the left tile layer. Defaults to {}.
right_args (dict, optional) – The arguments for the right tile layer. Defaults to {}.

st_draw_features(st_component)[source]¶

Get the draw features of the map.

Parameters:	st_folium (streamlit-folium) – The streamlit component.
Returns:	The draw features of the map.
Return type:	list

st_fit_bounds()[source]¶

Fit the map to the bounds of the map.

Returns:	The map.
Return type:	folium.Map

st_last_click(st_component)[source]¶

Get the last click feature of the map.

Parameters:	st_folium (streamlit-folium) – The streamlit component.
Returns:	The last click of the map.
Return type:	str

st_last_draw(st_component)[source]¶

Get the last draw feature of the map.

Parameters:	st_folium (streamlit-folium) – The streamlit component.
Returns:	The last draw of the map.
Return type:	str

st_map_bounds(st_component)[source]¶

Get the bounds of the map in the format of (miny, minx, maxy, maxx).

Parameters:	st_folium (streamlit-folium) – The streamlit component.
Returns:	The bounds of the map.
Return type:	tuple

st_map_center(st_component)[source]¶

Get the center of the map.

Parameters:	st_folium (streamlit-folium) – The streamlit component.
Returns:	The center of the map.
Return type:	tuple

to_gradio(width='100%', height='500px', **kwargs)[source]¶

Converts the map to an HTML string that can be used in Gradio. Removes unsupported elements, such as: attribution and any code blocks containing functions. See https://github.com/gradio-app/gradio/issues/3190

Parameters:	width (str, optional) – The width of the map. Defaults to ‘100%’. height (str, optional) – The height of the map. Defaults to ‘500px’.
Returns:	The HTML string to use in Gradio.
Return type:	str

to_html(filename=None, **kwargs)[source]¶

Exports a map as an HTML file.

Parameters:	filename (str, optional) – File path to the output HTML. Defaults to None.
Raises:	`ValueError` – If it is an invalid HTML file.
Returns:	A string containing the HTML code.
Return type:	str

to_streamlit(width=None, height=600, scrolling=False, add_layer_control=True, bidirectional=False, **kwargs)[source]¶

Renders folium.Figure or folium.Map in a Streamlit app. This method is a static Streamlit Component, meaning, no information is passed back from Leaflet on browser interaction.

Parameters:	width (int, optional) – Width of the map. Defaults to None. height (int, optional) – Height of the map. Defaults to 600. scrolling (bool, optional) – Whether to allow the map to scroll. Defaults to False. add_layer_control (bool, optional) – Whether to add the layer control. Defaults to True. bidirectional (bool, optional) – Whether to add bidirectional functionality to the map. The streamlit-folium package is required to use the bidirectional functionality. Defaults to False.
Raises:	`ImportError` – If streamlit is not installed.
Returns:	components.html object.
Return type:	streamlit.components

ts_inspector(left_ts, right_ts, left_names, right_names, left_vis={}, right_vis={}, width='130px', **kwargs)[source]¶

zoom_to_bounds(bounds)[source]¶

Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

Parameters:	bounds (list \| tuple) – A list/tuple containing minx, miny, maxx, maxy values for the bounds.

zoom_to_gdf(gdf)[source]¶

Zooms to the bounding box of a GeoPandas GeoDataFrame.

Parameters:	gdf (GeoDataFrame) – A GeoPandas GeoDataFrame.

class geemap.foliumap.SideBySideLayers(layer_left, layer_right)[source]¶

Bases: folium.elements.JSCSSMixin, folium.map.Layer

Creates a SideBySideLayers that takes two Layers and adds a sliding control with the leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin https://github.com/digidem/leaflet-side-by-side. Adopted from https://github.com/python-visualization/folium/pull/1292/files. :param layer_left: The left Layer within the side by side control.

Must be created and added to the map before being passed to this class.

Parameters:	layer_right (Layer.) – The right Layer within the side by side control. Must be created and added to the map before being passed to this class.

Examples

>>> sidebyside = SideBySideLayers(layer_left, layer_right)
>>> sidebyside.add_to(m)

default_js = [('leaflet.sidebyside', 'https://cdn.jsdelivr.net/gh/digidem/leaflet-side-by-side@gh-pages/leaflet-side-by-side.min.js')]¶

class geemap.foliumap.SplitControl(layer_left, layer_right, name=None, overlay=True, control=False, show=True)[source]¶

Bases: folium.map.Layer

Creates a SplitControl that takes two Layers and adds a sliding control with the leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin https://github.com/digidem/leaflet-side-by-side Parameters. The source code is adapted from https://github.com/python-visualization/folium/pull/1292 ———- layer_left: Layer.

The left Layer within the side by side control. Must be created and added to the map before being passed to this class.

layer_right: Layer.: The right Layer within the side by side control. Must be created and added to the map before being passed to this class.
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

>>> sidebyside = SideBySideLayers(layer_left, layer_right)
>>> sidebyside.add_to(m)

render(**kwargs)[source]¶: Renders the HTML representation of the element.

geemap.foliumap.delete_dp_report(name)[source]¶

Deletes a datapane report.

Parameters:	name (str) – Name of the report to delete.

geemap.foliumap.delete_dp_reports()[source]¶: Deletes all datapane reports.

geemap.foliumap.ee_tile_layer(ee_object, vis_params={}, name='Layer untitled', shown=True, opacity=1.0, **kwargs)[source]¶

Converts and Earth Engine layer to ipyleaflet TileLayer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer untitled’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

geemap.foliumap.linked_maps(rows=2, cols=2, height='400px', ee_objects=[], vis_params=[], labels=[], label_position='topright', **kwargs)[source]¶

geemap.foliumap.st_map_center(lat, lon)[source]¶

Returns the map center coordinates for a given latitude and longitude. If the system variable ‘map_center’ exists, it is used. Otherwise, the default is returned.

Parameters:	lat (float) – Latitude. lon (float) – Longitude.
Raises:	`Exception` – If streamlit is not installed.
Returns:	The map center coordinates.
Return type:	list

geemap.foliumap.st_save_bounds(st_component)[source]¶

Saves the map bounds to the session state.

Parameters:	map (folium.folium.Map) – The map to save the bounds from.

geemap.geemap module¶

Main module for interactive mapping using Google Earth Engine Python API and ipyleaflet. Keep in mind that Earth Engine functions use both camel case and snake case, such as setOptions(), setCenter(), centerObject(), addLayer(). ipyleaflet functions use snake case, such as add_tile_layer(), add_wms_layer(), add_minimap().

class geemap.geemap.ImageOverlay(**kwargs)[source]¶

Bases: ipyleaflet.leaflet.ImageOverlay

ImageOverlay class.

Parameters:	url (str) – http URL or local file path to the image. bounds (tuple) – bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)). name (str) – The name of the layer.

class geemap.geemap.Map(**kwargs)[source]¶

Bases: ipyleaflet.leaflet.Map

The Map class inherits the ipyleaflet Map class. The arguments you can pass to the Map initialization: can be found at https://ipyleaflet.readthedocs.io/en/latest/map_and_basemaps/map.html. By default, the Map will add Google Maps as the basemap. Set add_google_map = False to use OpenStreetMap as the basemap.

Returns:	ipyleaflet map object.
Return type:	object

add(object)[source]¶

Adds a layer or control to the map.

Parameters:	object (object) – The layer or control to add to the map.

addLayer(ee_object, vis_params={}, name=None, shown=True, opacity=1.0)¶

Adds a given EE object to the map as a layer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer N’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

addLayerControl(position='topright')¶

Adds a layer control to the map.

Parameters:	position (str, optional) – _description_. Defaults to “topright”.

add_basemap(basemap='HYBRID', show=True, **kwargs)[source]¶

Adds a basemap to the map.

Parameters:	basemap (str, optional) – Can be one of string from basemaps. Defaults to ‘HYBRID’. visible (bool, optional) – Whether the basemap is visible or not. Defaults to True. **kwargs – Keyword arguments for the TileLayer.

add_census_data(wms, layer, census_dict=None, **kwargs)[source]¶

Adds a census data layer to the map.

Parameters:	wms (str) – The wms to use. For example, “Current”, “ACS 2021”, “Census 2020”. See the complete list at https://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_wms.html layer (str) – The layer name to add to the map. census_dict (dict, optional) – A dictionary containing census data. Defaults to None. It can be obtained from the get_census_dict() function.

add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, **kwargs)[source]¶

Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/api_reference/circle_marker.html

Parameters:

data (str | pd.DataFrame) – A csv or Pandas DataFrame containing x, y, z values.
x (str, optional) – The column name for the x values. Defaults to “longitude”.
y (str, optional) – The column name for the y values. Defaults to “latitude”.
radius (int, optional) – The radius of the circle. Defaults to 10.
popup (list, optional) – A list of column names to be used as the popup. Defaults to None.

add_cog_layer(url, name='Untitled', attribution='', opacity=1.0, shown=True, bands=None, titiler_endpoint=None, **kwargs)[source]¶

Adds a COG TileLayer to the map.

Parameters:

url (str) – The URL of the COG tile layer.
name (str, optional) – The layer name to use for the layer. Defaults to ‘Untitled’.
attribution (str, optional) – The attribution to use. Defaults to ‘’.
opacity (float, optional) – The opacity of the layer. Defaults to 1.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
bands (list, optional) – A list of bands to use for the layer. Defaults to None.
titiler_endpoint (str, optional) – Titiler endpoint. Defaults to “https://titiler.xyz”.
**kwargs – Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale, color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/ and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3]

add_cog_mosaic(**kwargs)[source]¶

add_colorbar(vis_params=None, cmap='gray', discrete=False, label=None, orientation='horizontal', position='bottomright', transparent_bg=False, layer_name=None, font_size=9, axis_off=False, max_width=None, **kwargs)[source]¶

Add a matplotlib colorbar to the map

Parameters:

vis_params (dict) – Visualization parameters as a dictionary. See https://developers.google.com/earth-engine/guides/image_visualization for options.
cmap (str, optional) – Matplotlib colormap. Defaults to “gray”. See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py for options.
discrete (bool, optional) – Whether to create a discrete colorbar. Defaults to False.
label (str, optional) – Label for the colorbar. Defaults to None.
orientation (str, optional) – Orientation of the colorbar, such as “vertical” and “horizontal”. Defaults to “horizontal”.
position (str, optional) – Position of the colorbar on the map. It can be one of: topleft, topright, bottomleft, and bottomright. Defaults to “bottomright”.
transparent_bg (bool, optional) – Whether to use transparent background. Defaults to False.
layer_name (str, optional) – The layer name associated with the colorbar. Defaults to None.
font_size (int, optional) – Font size for the colorbar. Defaults to 9.
axis_off (bool, optional) – Whether to turn off the axis. Defaults to False.
max_width (str, optional) – Maximum width of the colorbar in pixels. Defaults to None.

Raises:

TypeError – If the vis_params is not a dictionary.
ValueError – If the orientation is not either horizontal or vertical.
TypeError – If the provided min value is not scalar type.
TypeError – If the provided max value is not scalar type.
TypeError – If the provided opacity value is not scalar type.
TypeError – If cmap or palette is not provided.

add_colorbar_branca(colors, vmin=0, vmax=1.0, index=None, caption='', categorical=False, step=None, height='45px', transparent_bg=False, position='bottomright', layer_name=None, **kwargs)[source]¶

Add a branca colorbar to the map.

Parameters:

colors (list) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)
vmin (int, optional) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].. Defaults to 0.
vmax (float, optional) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.
index (list, optional) – The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.. Defaults to None.
caption (str, optional) – The caption for the colormap. Defaults to “”.
categorical (bool, optional) – Whether or not to create a categorical colormap. Defaults to False.
step (int, optional) – The step to split the LinearColormap into a StepColormap. Defaults to None.
height (str, optional) – The height of the colormap widget. Defaults to “45px”.
transparent_bg (bool, optional) – Whether to use transparent background for the colormap widget. Defaults to True.
position (str, optional) – The position for the colormap widget. Defaults to “bottomright”.
layer_name (str, optional) – Layer name of the colorbar to be associated with. Defaults to None.

add_controls(controls, position='topleft')[source]¶

Adds a list of controls to the map.

Parameters:	controls (list) – A list of controls to add to the map. position (str, optional) – The position of the controls on the map. Defaults to ‘topleft’.

add_data(data, column, colors=None, labels=None, cmap=None, scheme='Quantiles', k=5, add_legend=True, legend_title=None, legend_kwds=None, classification_kwds=None, layer_name='Untitled', style=None, hover_style=None, style_callback=None, info_mode='on_hover', encoding='utf-8', **kwargs)[source]¶

Add vector data to the map with a variety of classification schemes.

Parameters:

data (str | pd.DataFrame | gpd.GeoDataFrame) – The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.
column (str) – The column to classify.
cmap (str, optional) – The name of a colormap recognized by matplotlib. Defaults to None.
colors (list, optional) – A list of colors to use for the classification. Defaults to None.
labels (list, optional) – A list of labels to use for the legend. Defaults to None.
scheme (str, optional) – Name of a choropleth classification scheme (requires mapclassify). Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. ‘BoxPlot’, ‘EqualInterval’, ‘FisherJenks’, ‘FisherJenksSampled’, ‘HeadTailBreaks’, ‘JenksCaspall’, ‘JenksCaspallForced’, ‘JenksCaspallSampled’, ‘MaxP’, ‘MaximumBreaks’, ‘NaturalBreaks’, ‘Quantiles’, ‘Percentiles’, ‘StdMean’, ‘UserDefined’). Arguments can be passed in classification_kwds.
k (int, optional) – Number of classes (ignored if scheme is None or if column is categorical). Default to 5.
legend_kwds (dict, optional) –
Keyword arguments to pass to matplotlib.pyplot.legend() or matplotlib.pyplot.colorbar. Defaults to None. Keyword arguments to pass to matplotlib.pyplot.legend() or Additional accepted keywords when scheme is specified: fmt : string

A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals: {"fmt": "{:.0f}"}.

labels : list-like

A list of legend labels to override the auto-generated labblels. Needs to have the same number of elements as the number of classes (k).

interval : boolean (default False)

An option to control brackets from mapclassify legend. If True, open/closed interval brackets are shown in the legend.
classification_kwds (dict, optional) – Keyword arguments to pass to mapclassify. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) –
A dictionary specifying the style to be used. Defaults to None. style is a dictionary of the following form:

style = { “stroke”: False, “color”: “#ff0000”, “weight”: 1, “opacity”: 1, “fill”: True, “fillColor”: “#ffffff”, “fillOpacity”: 1.0, “dashArray”: “9” “clickable”: True,

}
hover_style (dict, optional) –
Hover style dictionary. Defaults to {}. hover_style is a dictionary of the following form:

hover_style = {“weight”: style[“weight”] + 1, “fillOpacity”: 0.5}
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None. style_callback is a function that takes the feature as argument and should return a dictionary of the following form: style_callback = lambda feat: {“fillColor”: feat[“properties”][“color”]}
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding of the GeoJSON file. Defaults to “utf-8”.

add_draw_control(position='topleft')[source]¶

Add a draw control to the map

Parameters:	position (str, optional) – The position of the draw control. Defaults to “topleft”.

add_draw_control_lite(position='topleft')[source]¶

Add a lite version draw control to the map for the plotting tool.

Parameters:	position (str, optional) – The position of the draw control. Defaults to “topleft”.

add_ee_layer(ee_object, vis_params={}, name=None, shown=True, opacity=1.0)[source]¶

Adds a given EE object to the map as a layer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer N’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

add_gdf(gdf, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', zoom_to_layer=True, encoding='utf-8')[source]¶

Adds a GeoDataFrame to the map.

Parameters:

gdf (GeoDataFrame) – A GeoPandas GeoDataFrame.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
zoom_to_layer (bool, optional) – Whether to zoom to the layer.
encoding (str, optional) – The encoding of the GeoDataFrame. Defaults to “utf-8”.

add_gdf_from_postgis(sql, con, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', zoom_to_layer=True, **kwargs)[source]¶

Reads a PostGIS database and returns data as a GeoDataFrame to be added to the map.

Parameters:

sql (str) – SQL query to execute in selecting entries from database, or name of the table to read from the database.
con (sqlalchemy.engine.Engine) – Active connection to the database to query.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
zoom_to_layer (bool, optional) – Whether to zoom to the layer.

add_geojson(in_geojson, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8')[source]¶

Adds a GeoJSON file to the map.

Parameters:

in_geojson (str | dict) – The file path or http URL to the input GeoJSON or a dictionary containing the geojson.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding of the GeoJSON file. Defaults to “utf-8”.

Raises:

FileNotFoundError – The provided GeoJSON file could not be found.

add_gui(name, position='topright', opened=True, show_close_button=True, **kwargs)[source]¶

Add a GUI to the map.

Parameters:

name (str) – The name of the GUI. Options include “layer_manager”, “inspector”, “plot”, and “timelapse”.
position (str, optional) – The position of the GUI. Defaults to “topright”.
opened (bool, optional) – Whether the GUI is opened. Defaults to True.
show_close_button (bool, optional) – Whether to show the close button. Defaults to True.

add_heatmap(data, latitude='latitude', longitude='longitude', value='value', name='Heat map', radius=25, **kwargs)[source]¶

Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

Parameters:

data (str | list | pd.DataFrame) – File path or HTTP URL to the input file or a list of data points in the format of [[x1, y1, z1], [x2, y2, z2]]. For example, https://raw.githubusercontent.com/giswqs/leafmap/master/examples/data/world_cities.csv
latitude (str, optional) – The column name of latitude. Defaults to “latitude”.
longitude (str, optional) – The column name of longitude. Defaults to “longitude”.
value (str, optional) – The column name of values. Defaults to “value”.
name (str, optional) – Layer name to use. Defaults to “Heat map”.
radius (int, optional) – Radius of each “point” of the heatmap. Defaults to 25.

Raises:

ValueError – If data is not a list.

add_html(html, position='bottomright', **kwargs)[source]¶

Add HTML to the map.

Parameters:	html (str) – The HTML to add. position (str, optional) – The position of the HTML, can be one of “topleft”, “topright”, “bottomleft”, “bottomright”. Defaults to “bottomright”.

add_image(image, position='bottomright', **kwargs)[source]¶

Add an image to the map.

Parameters:	image (str \| ipywidgets.Image) – The image to add. position (str, optional) – The position of the image, can be one of “topleft”, “topright”, “bottomleft”, “bottomright”. Defaults to “bottomright”.

add_inspector(names=None, visible=True, decimals=2, position='topright', opened=True, show_close_button=True)[source]¶

Add the Inspector GUI to the map.

Parameters:

names (str | list, optional) – The names of the layers to be included. Defaults to None.
visible (bool, optional) – Whether to inspect visible layers only. Defaults to True.
decimals (int, optional) – The number of decimal places to round the coordinates. Defaults to 2.
position (str, optional) – The position of the Inspector GUI. Defaults to “topright”.
opened (bool, optional) – Whether the control is opened. Defaults to True.

add_kml(in_kml, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds a GeoJSON file to the map.

Parameters:

in_kml (str) – The input file path to the KML.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

Raises:

FileNotFoundError – The provided KML file could not be found.

add_labels(data, column, font_size='12pt', font_color='black', font_family='arial', font_weight='normal', x='longitude', y='latitude', draggable=True, layer_name='Labels', **kwargs)[source]¶

Adds a label layer to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/divicon.html

Parameters:

data (pd.DataFrame | ee.FeatureCollection) – The input data to label.
column (str) – The column name of the data to label.
font_size (str, optional) – The font size of the labels. Defaults to “12pt”.
font_color (str, optional) – The font color of the labels. Defaults to “black”.
font_family (str, optional) – The font family of the labels. Defaults to “arial”.
font_weight (str, optional) – The font weight of the labels, can be normal, bold. Defaults to “normal”.
x (str, optional) – The column name of the longitude. Defaults to “longitude”.
y (str, optional) – The column name of the latitude. Defaults to “latitude”.
draggable (bool, optional) – Whether the labels are draggable. Defaults to True.
layer_name (str, optional) – Layer name to use. Defaults to “Labels”.

add_landsat_ts_gif(layer_name='Timelapse', roi=None, label=None, start_year=1984, end_year=2021, start_date='06-10', end_date='09-20', bands=['NIR', 'Red', 'Green'], vis_params=None, dimensions=768, frames_per_second=10, font_size=30, font_color='white', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, out_gif=None, download=False, apply_fmask=True, nd_bands=None, nd_threshold=0, nd_palette=['black', 'blue'])[source]¶

Adds a Landsat timelapse to the map.

Parameters:

layer_name (str, optional) – Layer name to show under the layer control. Defaults to ‘Timelapse’.
roi (object, optional) – Region of interest to create the timelapse. Defaults to None.
label (str, optional) – A label to show on the GIF, such as place name. Defaults to None.
start_year (int, optional) – Starting year for the timelapse. Defaults to 1984.
end_year (int, optional) – Ending year for the timelapse. Defaults to 2021.
start_date (str, optional) – Starting date (month-day) each year for filtering ImageCollection. Defaults to ‘06-10’.
end_date (str, optional) – Ending date (month-day) each year for filtering ImageCollection. Defaults to ‘09-20’.
bands (list, optional) – Three bands selected from [‘Blue’, ‘Green’, ‘Red’, ‘NIR’, ‘SWIR1’, ‘SWIR2’, ‘pixel_qa’]. Defaults to [‘NIR’, ‘Red’, ‘Green’].
vis_params (dict, optional) – Visualization parameters. Defaults to None.
dimensions (int, optional) – a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
frames_per_second (int, optional) – Animation speed. Defaults to 10.
font_size (int, optional) – Font size of the animated text and label. Defaults to 30.
font_color (str, optional) – Font color of the animated text and label. Defaults to ‘black’.
add_progress_bar (bool, optional) – Whether to add a progress bar at the bottom of the GIF. Defaults to True.
progress_bar_color (str, optional) – Color for the progress bar. Defaults to ‘white’.
progress_bar_height (int, optional) – Height of the progress bar. Defaults to 5.
out_gif (str, optional) – File path to the output animated GIF. Defaults to None.
download (bool, optional) – Whether to download the gif. Defaults to False.
apply_fmask (bool, optional) – Whether to apply Fmask (Function of mask) for automated clouds, cloud shadows, snow, and water masking.
nd_bands (list, optional) – A list of names specifying the bands to use, e.g., [‘Green’, ‘SWIR1’]. The normalized difference is computed as (first − second) / (first + second). Note that negative input values are forced to 0 so that the result is confined to the range (-1, 1).
nd_threshold (float, optional) – The threshold for extacting pixels from the normalized difference band.
nd_palette (str, optional) – The color palette to use for displaying the normalized difference band.

add_layer_control(position='topright')[source]¶

Adds a layer control to the map.

Parameters:	position (str, optional) – _description_. Defaults to “topright”.

add_layer_manager(position='topright', opened=True, show_close_button=True)[source]¶

Add the Layer Manager to the map.

Parameters:	position (str, optional) – The position of the Layer Manager. Defaults to “topright”. opened (bool, optional) – Whether the control is opened. Defaults to True. show_close_button (bool, optional) – Whether to show the close button. Defaults to True.

add_legend(title='Legend', legend_dict=None, labels=None, colors=None, position='bottomright', builtin_legend=None, layer_name=None, add_header=True, widget_args={}, **kwargs)[source]¶

Adds a customized basemap to the map.

Parameters:

title (str, optional) – Title of the legend. Defaults to ‘Legend’.
legend_dict (dict, optional) – A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.
labels (list, optional) – A list of legend keys. Defaults to None.
colors (list, optional) – A list of legend colors. Defaults to None.
position (str, optional) – Position of the legend. Defaults to ‘bottomright’.
builtin_legend (str, optional) – Name of the builtin legend to add to the map. Defaults to None.
layer_name (str, optional) – Layer name of the legend to be associated with. Defaults to None.
add_header (bool, optional) – Whether the legend can be closed or not. Defaults to True.
widget_args (dict, optional) – Additional arguments passed to the widget_template() function. Defaults to {}.

add_local_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Local COG', zoom_to_layer=True, **kwargs)¶

Add a local raster dataset to the map.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = ‘proxy/{port}’

Parameters:

source (str) – The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to ‘Local COG’.
zoom_to_layer (bool, optional) – Whether to zoom to the extent of the layer. Defaults to True.

add_marker(location, **kwargs)[source]¶

Adds a marker to the map. More info about marker at https://ipyleaflet.readthedocs.io/en/latest/api_reference/marker.html.

Parameters:	location (list \| tuple) – The location of the marker in the format of [lat, lng]. **kwargs – Keyword arguments for the marker.

add_marker_cluster(event='click', add_marker=True)[source]¶

Captures user inputs and add markers to the map.

Parameters:	event (str, optional) – [description]. Defaults to ‘click’. add_marker (bool, optional) – If True, add markers to the map. Defaults to True.
Returns:	a marker cluster.
Return type:	object

add_minimap(zoom=5, position='bottomright')[source]¶

Adds a minimap (overview) to the ipyleaflet map.

Parameters:	zoom (int, optional) – Initial map zoom level. Defaults to 5. position (str, optional) – Position of the minimap. Defaults to “bottomright”.

add_netcdf(filename, variables=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='NetCDF layer', shift_lon=True, lat='lat', lon='lon', **kwargs)[source]¶

Generate an ipyleaflet/folium TileLayer from a netCDF file.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer), try adding to following two lines to the beginning of the notebook if the raster does not render properly.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = f’{os.environ[‘JUPYTERHUB_SERVICE_PREFIX’].lstrip(‘/’)}/proxy/{{port}}’

Parameters:

filename (str) – File path or HTTP URL to the netCDF file.
variables (int, optional) – The variable/band names to extract data from the netCDF file. Defaults to None. If None, all variables will be extracted.
port (str, optional) – The port to use for the server. Defaults to “default”.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to “netCDF layer”.
shift_lon (bool, optional) – Flag to shift longitude values from [0, 360] to the range [-180, 180]. Defaults to True.
lat (str, optional) – Name of the latitude variable. Defaults to ‘lat’.
lon (str, optional) – Name of the longitude variable. Defaults to ‘lon’.

add_osm(query, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', which_result=None, by_osmid=False, buffer_dist=None, to_ee=False, geodesic=True)[source]¶

Adds OSM data to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
which_result (INT, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
by_osmid (bool, optional) – If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
to_ee (bool, optional) – Whether to convert the csv to an ee.FeatureCollection.
geodesic (bool, optional) – Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.

add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within some distance N, S, E, W of address to the map.

Parameters:

address (str) – The address to geocode and use as the central point around which to get the geometries.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
dist (int, optional) – Distance in meters. Defaults to 1000.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_bbox(north, south, east, west, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within a N, S, E, W bounding box to the map.

Parameters:

north (float) – Northern latitude of bounding box.
south (float) – Southern latitude of bounding box.
east (float) – Eastern longitude of bounding box.
west (float) – Western longitude of bounding box.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_geocode(query, which_result=None, by_osmid=False, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM data of place(s) by name or ID to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
which_result (int, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
by_osmid (bool, optional) – If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_place(query, tags, which_result=None, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within boundaries of geocodable place(s) to the map.

Parameters:

query (str | dict | list) – Query string(s) or structured dict(s) to geocode.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
which_result (int, optional) – Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn’t return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
buffer_dist (float, optional) – Distance to buffer around the place geometry, in meters. Defaults to None.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within some distance N, S, E, W of a point to the map.

Parameters:

center_point (tuple) – The (lat, lng) center point around which to get the geometries.
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
dist (int, optional) – Distance in meters. Defaults to 1000.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_polygon(polygon, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within boundaries of a (multi)polygon to the map.

Parameters:

polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon) – Geographic boundaries to fetch geometries within
tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_osm_from_view(tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')[source]¶

Adds OSM entities within the current map view to the map.

Parameters:

tags (dict) – Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.

add_planet_by_month(year=2016, month=1, name=None, api_key=None, token_name='PLANET_API_KEY')[source]¶

Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

year (int, optional) – The year of Planet global mosaic, must be >=2016. Defaults to 2016.
month (int, optional) – The month of Planet global mosaic, must be 1-12. Defaults to 1.
name (str, optional) – The layer name to use. Defaults to None.
api_key (str, optional) – The Planet API key. Defaults to None.
token_name (str, optional) – The environment variable name of the API key. Defaults to “PLANET_API_KEY”.

add_planet_by_quarter(year=2016, quarter=1, name=None, api_key=None, token_name='PLANET_API_KEY')[source]¶

Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

year (int, optional) – The year of Planet global mosaic, must be >=2016. Defaults to 2016.
quarter (int, optional) – The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
name (str, optional) – The layer name to use. Defaults to None.
api_key (str, optional) – The Planet API key. Defaults to None.
token_name (str, optional) – The environment variable name of the API key. Defaults to “PLANET_API_KEY”.

add_plot_gui(position='topright', **kwargs)[source]¶

Adds the plot widget to the map.

Parameters:	position (str, optional) – Position of the widget. Defaults to “topright”.

add_point_layer(filename, popup=None, layer_name='Marker Cluster', **kwargs)[source]¶

Adds a point layer to the map with a popup attribute.

Parameters:

filename (str) – str, http url, path object or file-like object. Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO)
popup (str | list, optional) – Column name(s) to be used for popup. Defaults to None.
layer_name (str, optional) – A layer name to use. Defaults to “Marker Cluster”.

Raises:

ValueError – If the specified column name does not exist.
ValueError – If the specified column names do not exist.

add_points_from_xy(data, x='longitude', y='latitude', popup=None, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], spin=False, add_legend=True, **kwargs)[source]¶

Adds a marker cluster to the map.

Parameters:

data (str | pd.DataFrame) – A csv or Pandas DataFrame containing x, y, z values.
x (str, optional) – The column name for the x values. Defaults to “longitude”.
y (str, optional) – The column name for the y values. Defaults to “latitude”.
popup (list, optional) – A list of column names to be used as the popup. Defaults to None.
layer_name (str, optional) – The name of the layer. Defaults to “Marker Cluster”.
color_column (str, optional) – The column name for the color values. Defaults to None.
marker_colors (list, optional) – A list of colors to be used for the markers. Defaults to None.
icon_colors (list, optional) – A list of colors to be used for the icons. Defaults to [‘white’].
icon_names (list, optional) – A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to [‘info’].
spin (bool, optional) – If True, the icon will spin. Defaults to False.
add_legend (bool, optional) – If True, a legend will be added to the map. Defaults to True.

add_raster(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Local COG', zoom_to_layer=True, **kwargs)[source]¶

Add a local raster dataset to the map.

If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

import os os.environ[‘LOCALTILESERVER_CLIENT_PREFIX’] = ‘proxy/{port}’

Parameters:

source (str) – The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to ‘Local COG’.
zoom_to_layer (bool, optional) – Whether to zoom to the extent of the layer. Defaults to True.

add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs)[source]¶

Add a remote Cloud Optimized GeoTIFF (COG) to the map.

Parameters:

source (str) – The path to the remote Cloud Optimized GeoTIFF.
band (int, optional) – The band to use. Band indexing starts at 1. Defaults to None.
palette (str, optional) – The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
vmin (float, optional) – The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
vmax (float, optional) – The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
nodata (float, optional) – The value from the band to use to interpret as not valid data. Defaults to None.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to None.

add_search_control(marker=None, url=None, zoom=5, property_name='display_name', position='topleft')[source]¶

Add a search control to the map.

Parameters:

marker (ipyleaflet.Marker, optional) – The marker to use. Defaults to None.
url (str, optional) – The URL to use for the search. Defaults to None.
zoom (int, optional) – The zoom level to use. Defaults to 5.
property_name (str, optional) – The property name to use. Defaults to “display_name”.
position (str, optional) – The position of the widget. Defaults to “topleft”.

add_shapefile(in_shp, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8')¶

Adds a shapefile to the map.

Parameters:

in_shp (str) – The input file path to the shapefile.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding of the shapefile. Defaults to “utf-8”.

Raises:

FileNotFoundError – The provided shapefile could not be found.

add_shp(in_shp, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8')[source]¶

Adds a shapefile to the map.

Parameters:

in_shp (str) – The input file path to the shapefile.
layer_name (str, optional) – The layer name to be used.. Defaults to “Untitled”.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding of the shapefile. Defaults to “utf-8”.

Raises:

FileNotFoundError – The provided shapefile could not be found.

add_stac_layer(url=None, collection=None, item=None, assets=None, bands=None, titiler_endpoint=None, name='STAC Layer', attribution='', opacity=1.0, shown=True, **kwargs)[source]¶

Adds a STAC TileLayer to the map.

Parameters:

url (str) – HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
collection (str) – The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
item (str) – The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
assets (str | list) – The Microsoft Planetary Computer STAC asset ID, e.g., [“SR_B7”, “SR_B5”, “SR_B4”].
bands (list) – A list of band names, e.g., [“SR_B7”, “SR_B5”, “SR_B4”]
titiler_endpoint (str, optional) – Titiler endpoint, e.g., “https://titiler.xyz”, “https://planetarycomputer.microsoft.com/api/data/v1”, “planetary-computer”, “pc”. Defaults to None.
name (str, optional) – The layer name to use for the layer. Defaults to ‘STAC Layer’.
attribution (str, optional) – The attribution to use. Defaults to ‘’.
opacity (float, optional) – The opacity of the layer. Defaults to 1.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.

add_styled_vector(ee_object, column, palette, layer_name='Untitled', shown=True, opacity=1.0, **kwargs)[source]¶

Adds a styled vector to the map.

Parameters:

ee_object (object) – An ee.FeatureCollection.
column (str) – The column name to use for styling.
palette (list | dict) – The palette (e.g., list of colors or a dict containing label and color pairs) to use for styling.
layer_name (str, optional) – The name to be used for the new layer. Defaults to “Untitled”.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The opacity of the layer. Defaults to 1.0.

add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs)[source]¶

Add text to the map.

Parameters:

text (str) – The text to add.
fontsize (int, optional) – The font size. Defaults to 20.
fontcolor (str, optional) – The font color. Defaults to “black”.
bold (bool, optional) – Whether to use bold font. Defaults to False.
padding (str, optional) – The padding. Defaults to “5px”.
background (bool, optional) – Whether to use background. Defaults to True.
bg_color (str, optional) – The background color. Defaults to “white”.
border_radius (str, optional) – The border radius. Defaults to “5px”.
position (str, optional) – The position of the widget. Defaults to “bottomright”.

add_tile_layer(url='https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', name='Untitled', attribution='', opacity=1.0, shown=True, **kwargs)[source]¶

Adds a TileLayer to the map.

Parameters:

url (str, optional) – The URL of the tile layer. Defaults to ‘https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png’.
name (str, optional) – The layer name to use for the layer. Defaults to ‘Untitled’.
attribution (str, optional) – The attribution to use. Defaults to ‘’.
opacity (float, optional) – The opacity of the layer. Defaults to 1.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.

add_time_slider(ee_object, vis_params={}, region=None, layer_name='Time series', labels=None, time_interval=1, position='bottomright', slider_length='150px', date_format='YYYY-MM-dd', opacity=1.0, **kwargs)[source]¶

Adds a time slider to the map.

Parameters:

ee_object (ee.Image | ee.ImageCollection) – The Image or ImageCollection to visualize.
vis_params (dict, optional) – Visualization parameters to use for visualizing image. Defaults to {}.
region (ee.Geometry | ee.FeatureCollection) – The region to visualize.
layer_name (str, optional) – The layer name to be used. Defaults to “Time series”.
labels (list, optional) – The list of labels to be used for the time series. Defaults to None.
time_interval (int, optional) – Time interval in seconds. Defaults to 1.
position (str, optional) – Position to place the time slider, can be any of [‘topleft’, ‘topright’, ‘bottomleft’, ‘bottomright’]. Defaults to “bottomright”.
slider_length (str, optional) – Length of the time slider. Defaults to “150px”.
date_format (str, optional) – The date format to use. Defaults to ‘YYYY-MM-dd’.
opacity (float, optional) – The opacity of layers. Defaults to 1.0.

Raises:

TypeError – If the ee_object is not ee.Image | ee.ImageCollection.

add_toolbar(position='topright', **kwargs)[source]¶

Add a toolbar to the map.

Parameters:	position (str, optional) – The position of the toolbar. Defaults to “topright”.

add_vector(filename, layer_name='Untitled', to_ee=False, bbox=None, mask=None, rows=None, style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8', **kwargs)[source]¶

Adds any geopandas-supported vector dataset to the map.

Parameters:

filename (str) – Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO).
layer_name (str, optional) – The layer name to use. Defaults to “Untitled”.
to_ee (bool, optional) – Whether to convert the GeoJSON to ee.FeatureCollection. Defaults to False.
bbox (tuple | GeoDataFrame or GeoSeries | shapely Geometry, optional) – Filter features by given bounding box, GeoSeries, GeoDataFrame or a shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with mask. Defaults to None.
mask (dict | GeoDataFrame or GeoSeries | shapely Geometry, optional) – Filter for features that intersect with the given dict-like geojson geometry, GeoSeries, GeoDataFrame or shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with bbox. Defaults to None.
rows (int or slice, optional) – Load in specific rows by passing an integer (first n rows) or a slice() object.. Defaults to None.
style (dict, optional) – A dictionary specifying the style to be used. Defaults to {}.
hover_style (dict, optional) – Hover style dictionary. Defaults to {}.
style_callback (function, optional) – Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
fill_colors (list, optional) – The random colors to use for filling polygons. Defaults to [“black”].
info_mode (str, optional) – Displays the attributes by either on_hover or on_click. Any value other than “on_hover” or “on_click” will be treated as None. Defaults to “on_hover”.
encoding (str, optional) – The encoding to use to read the file. Defaults to “utf-8”.

add_velocity(data, zonal_speed, meridional_speed, latitude_dimension='lat', longitude_dimension='lon', level_dimension='lev', level_index=0, time_index=0, velocity_scale=0.01, max_velocity=20, display_options={}, name='Velocity')[source]¶

Add a velocity layer to the map.

Parameters:

data (str | xr.Dataset) – The data to use for the velocity layer. It can be a file path to a NetCDF file or an xarray Dataset.
zonal_speed (str) – Name of the zonal speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
meridional_speed (str) – Name of the meridional speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
latitude_dimension (str, optional) – Name of the latitude dimension in the dataset. Defaults to ‘lat’.
longitude_dimension (str, optional) – Name of the longitude dimension in the dataset. Defaults to ‘lon’.
level_dimension (str, optional) – Name of the level dimension in the dataset. Defaults to ‘lev’.
level_index (int, optional) – The index of the level dimension to display. Defaults to 0.
time_index (int, optional) – The index of the time dimension to display. Defaults to 0.
velocity_scale (float, optional) – The scale of the velocity. Defaults to 0.01.
max_velocity (int, optional) – The maximum velocity to display. Defaults to 20.
display_options (dict, optional) – The display options for the velocity layer. Defaults to {}. See https://bit.ly/3uf8t6w.
name (str, optional) – Layer name to use . Defaults to ‘Velocity’.

Raises:

ImportError – If the xarray package is not installed.
ValueError – If the data is not a NetCDF file or an xarray Dataset.

add_widget(content, position='bottomright', add_header=True, opened=True, show_close_button=True, widget_icon='gear', close_button_icon='times', widget_args={}, close_button_args={}, display_widget=None, **kwargs)[source]¶

Add a widget (e.g., text, HTML, figure) to the map.

Parameters:

content (str | ipywidgets.Widget | object) – The widget to add.
position (str, optional) – The position of the widget. Defaults to “bottomright”.
add_header (bool, optional) – Whether to add a header with close buttons to the widget. Defaults to True.
opened (bool, optional) – Whether to open the toolbar. Defaults to True.
show_close_button (bool, optional) – Whether to show the close button. Defaults to True.
widget_icon (str, optional) – The icon name for the toolbar button. Defaults to ‘gear’.
close_button_icon (str, optional) – The icon name for the close button. Defaults to “times”.
widget_args (dict, optional) – Additional arguments to pass to the toolbar button. Defaults to {}.
close_button_args (dict, optional) – Additional arguments to pass to the close button. Defaults to {}.
display_widget (ipywidgets.Widget, optional) – The widget to be displayed when the toolbar is clicked.
**kwargs – Additional arguments to pass to the HTML or Output widgets

add_wms_layer(url, layers, name=None, attribution='', format='image/png', transparent=True, opacity=1.0, shown=True, **kwargs)[source]¶

Add a WMS layer to the map.

Parameters:

url (str) – The URL of the WMS web service.
layers (str) – Comma-separated list of WMS layers to show.
name (str, optional) – The layer name to use on the layer control. Defaults to None.
attribution (str, optional) – The attribution of the data layer. Defaults to ‘’.
format (str, optional) – WMS image format (use ‘image/png’ for layers with transparency). Defaults to ‘image/png’.
transparent (bool, optional) – If True, the WMS service will return images with transparency. Defaults to True.
opacity (float, optional) – The opacity of the layer. Defaults to 1.0.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.

add_xy_data(in_csv, x='longitude', y='latitude', label=None, layer_name='Marker cluster', to_ee=False)[source]¶

Adds points from a CSV file containing lat/lon information and display data on the map.

Parameters:

in_csv (str) – The file path to the input CSV file.
x (str, optional) – The name of the column containing longitude coordinates. Defaults to “longitude”.
y (str, optional) – The name of the column containing latitude coordinates. Defaults to “latitude”.
label (str, optional) – The name of the column containing label information to used for marker popup. Defaults to None.
layer_name (str, optional) – The layer name to use. Defaults to “Marker cluster”.
to_ee (bool, optional) – Whether to convert the csv to an ee.FeatureCollection.

Raises:

FileNotFoundError – The specified input csv does not exist.
ValueError – The specified x column does not exist.
ValueError – The specified y column does not exist.
ValueError – The specified label column does not exist.

add_xyz_service(provider, **kwargs)[source]¶

Add a XYZ tile layer to the map.

Parameters:	provider (str) – A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,
Raises:	`ValueError` – The provider is not valid. It must start with xyz or qms.

basemap_demo()[source]¶: A demo for using geemap basemaps.

centerObject(ee_object, zoom=None)¶

Centers the map view on a given object.

Parameters:	ee_object (Element\|Geometry) – An Earth Engine object to center on a geometry, image or feature. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

center_object(ee_object, zoom=None)[source]¶

Centers the map view on a given object.

Parameters:	ee_object (Element\|Geometry) – An Earth Engine object to center on a geometry, image or feature. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

create_vis_widget(layer_dict)[source]¶

Create a GUI for changing layer visualization parameters interactively.

Parameters:	layer_dict (dict) – A dict containning information about the layer. It is an element from Map.ee_layer_dict.
Returns:	An ipywidget.
Return type:	object

draw_layer_on_top()[source]¶: Move user-drawn feature layer to the top of all layers.

extract_values_to_points(filename)[source]¶

Exports pixel values to a csv file based on user-drawn geometries.

Parameters:	filename (str) – The output file path to the csv file or shapefile.

find_layer(name)[source]¶

Finds layer by name

Parameters:	name (str) – Name of the layer to find.
Returns:	ipyleaflet layer object.
Return type:	object

find_layer_index(name)[source]¶

Finds layer index by name

Parameters:	name (str) – Name of the layer to find.
Returns:	Index of the layer with the specified name
Return type:	int

getBounds(asGeoJSON=False)¶

Returns the bounds of the current map view, as a list in the format [west, south, east, north] in degrees.

Parameters:	asGeoJSON (bool, optional) – If true, returns map bounds as GeoJSON. Defaults to False.
Returns:	A list in the format [west, south, east, north] in degrees.
Return type:	list \| dict

getScale()¶

Returns the approximate pixel scale of the current map view, in meters.

Returns:	Map resolution in meters.
Return type:	float

get_bounds(asGeoJSON=False)[source]¶

Returns the bounds of the current map view, as a list in the format [west, south, east, north] in degrees.

Parameters:	asGeoJSON (bool, optional) – If true, returns map bounds as GeoJSON. Defaults to False.
Returns:	A list in the format [west, south, east, north] in degrees.
Return type:	list \| dict

get_layer_names()[source]¶

Gets layer names as a list.

Returns:	A list of layer names.
Return type:	list

get_scale()[source]¶

Returns the approximate pixel scale of the current map view, in meters.

Returns:	Map resolution in meters.
Return type:	float

image_overlay(url, bounds, name)[source]¶

Overlays an image from the Internet or locally on the map.

Parameters:	url (str) – http URL or local file path to the image. bounds (tuple) – bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)). name (str) – name of the layer to show on the layer control.

inspect(latlon)[source]¶

Create the Inspector GUI.

Parameters:	latlon (list \| tuple) – The coordinates (lat, lon) of the point.
Returns:	The ipytree tree widget for the Inspector GUI.
Return type:	ipytree.Tree

layer_opacity(name, opacity=1.0)[source]¶

Changes layer opacity.

Parameters:	name (str) – The name of the layer to change opacity. opacity (float, optional) – The opacity value to set. Defaults to 1.0.

marker_cluster()[source]¶

Adds a marker cluster to the map and returns a list of ee.Feature, which can be accessed using Map.ee_marker_cluster.

Returns:	a list of ee.Feature
Return type:	object

plot(x, y, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)[source]¶

Creates a plot based on x-array and y-array data.

Parameters:

x (numpy.ndarray or list) – The x-coordinates of the plotted line.
y (numpy.ndarray or list) – The y-coordinates of the plotted line.
plot_type (str, optional) – The plot type can be one of “None”, “bar”, “scatter” or “hist”. Defaults to None.
overlay (bool, optional) – Whether to overlay plotted lines on the figure. Defaults to False.
position (str, optional) – Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to ‘bottomright’.
min_width (int, optional) – Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_width (int, optional) – Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
min_height (int, optional) – Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_height (int, optional) – Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

plot_demo(iterations=20, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)[source]¶

A demo of interactive plotting using random pixel coordinates.

Parameters:

iterations (int, optional) – How many iterations to run for the demo. Defaults to 20.
plot_type (str, optional) – The plot type can be one of “None”, “bar”, “scatter” or “hist”. Defaults to None.
overlay (bool, optional) – Whether to overlay plotted lines on the figure. Defaults to False.
position (str, optional) – Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to ‘bottomright’.
min_width (int, optional) – Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_width (int, optional) – Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
min_height (int, optional) – Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_height (int, optional) – Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

plot_raster(ee_object=None, sample_scale=None, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)[source]¶

Interactive plotting of Earth Engine data by clicking on the map.

Parameters:

ee_object (object, optional) – The ee.Image or ee.ImageCollection to sample. Defaults to None.
sample_scale (float, optional) – A nominal scale in meters of the projection to sample in. Defaults to None.
plot_type (str, optional) – The plot type can be one of “None”, “bar”, “scatter” or “hist”. Defaults to None.
overlay (bool, optional) – Whether to overlay plotted lines on the figure. Defaults to False.
position (str, optional) – Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to ‘bottomright’.
min_width (int, optional) – Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_width (int, optional) – Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
min_height (int, optional) – Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_height (int, optional) – Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

remove_colorbar()[source]¶: Remove colorbar from the map.

remove_colorbars()[source]¶: Remove all colorbars from the map.

remove_drawn_features()[source]¶: Removes user-drawn geometries from the map

remove_ee_layer(name)[source]¶

Removes an Earth Engine layer.

Parameters:	name (str) – The name of the Earth Engine layer to remove.

remove_labels()[source]¶: Removes all labels from the map.

remove_last_drawn()[source]¶: Removes user-drawn geometries from the map

remove_legend()[source]¶: Remove legend from the map.

remove_legends()[source]¶: Remove all legends from the map.

setCenter(lon, lat, zoom=None)¶

Centers the map view at a given coordinates with the given zoom level.

Parameters:	lon (float) – The longitude of the center, in degrees. lat (float) – The latitude of the center, in degrees. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

setControlVisibility(layerControl=True, fullscreenControl=True, latLngPopup=True)¶

Sets the visibility of the controls on the map.

Parameters:

layerControl (bool, optional) – Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
fullscreenControl (bool, optional) – Whether to show the control that allows the user to make the map full-screen. Defaults to True.
latLngPopup (bool, optional) – Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.

setOptions(mapTypeId='HYBRID', **kwargs)¶

Adds Google basemap and controls to the ipyleaflet map.

Parameters:	mapTypeId (str, optional) – A mapTypeId to set the basemap to. Can be one of “ROADMAP”, “SATELLITE”, “HYBRID” or “TERRAIN” to select one of the standard Google Maps API map types. Defaults to ‘HYBRID’.

set_center(lon, lat, zoom=None)[source]¶

Centers the map view at a given coordinates with the given zoom level.

Parameters:	lon (float) – The longitude of the center, in degrees. lat (float) – The latitude of the center, in degrees. zoom (int, optional) – The zoom level, from 1 to 24. Defaults to None.

set_control_visibility(layerControl=True, fullscreenControl=True, latLngPopup=True)[source]¶

Sets the visibility of the controls on the map.

Parameters:

layerControl (bool, optional) – Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
fullscreenControl (bool, optional) – Whether to show the control that allows the user to make the map full-screen. Defaults to True.
latLngPopup (bool, optional) – Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.

set_options(mapTypeId='HYBRID', **kwargs)[source]¶

Adds Google basemap and controls to the ipyleaflet map.

Parameters:	mapTypeId (str, optional) – A mapTypeId to set the basemap to. Can be one of “ROADMAP”, “SATELLITE”, “HYBRID” or “TERRAIN” to select one of the standard Google Maps API map types. Defaults to ‘HYBRID’.

set_plot_options(add_marker_cluster=False, sample_scale=None, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)[source]¶

Sets plotting options.

Parameters:

add_marker_cluster (bool, optional) – Whether to add a marker cluster. Defaults to False.
sample_scale (float, optional) – A nominal scale in meters of the projection to sample in . Defaults to None.
plot_type (str, optional) – The plot type can be one of “None”, “bar”, “scatter” or “hist”. Defaults to None.
overlay (bool, optional) – Whether to overlay plotted lines on the figure. Defaults to False.
position (str, optional) – Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to ‘bottomright’.
min_width (int, optional) – Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_width (int, optional) – Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
min_height (int, optional) – Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
max_height (int, optional) – Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

show_layer(name, show=True)[source]¶

Shows or hides a layer on the map.

Parameters:	name (str) – Name of the layer to show/hide. show (bool, optional) – Whether to show or hide the layer. Defaults to True.

split_map(left_layer='HYBRID', right_layer='ROADMAP', zoom_control=True, fullscreen_control=True, layer_control=True, add_close_button=False, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', widget_layout=None, **kwargs)[source]¶

Adds split map.

Parameters:

left_layer (str, optional) – The layer tile layer. Defaults to ‘HYBRID’.
right_layer (str, optional) – The right tile layer. Defaults to ‘ROADMAP’.
zoom_control (bool, optional) – Whether to show the zoom control. Defaults to True.
fullscreen_control (bool, optional) – Whether to show the full screen control. Defaults to True.
layer_control (bool, optional) – Whether to show the layer control. Defaults to True.
add_close_button (bool, optional) – Whether to add a close button. Defaults to False.
left_label (str, optional) – The label for the left map. Defaults to None.
right_label (str, optional) – The label for the right map. Defaults to None.
left_position (str, optional) – The position of the left label. Defaults to ‘bottomleft’.
right_position (str, optional) – The position of the right label. Defaults to ‘bottomright’.
widget_layout (str, optional) – The layout of the label widget, such as ipywidgets.Layout(padding=”0px 4px 0px 4px”). Defaults to None.
kwargs – Other arguments for ipyleaflet.TileLayer.

to_gradio(width='100%', height='500px', **kwargs)[source]¶

Converts the map to an HTML string that can be used in Gradio. Removes unsupported elements, such as: attribution and any code blocks containing functions. See https://github.com/gradio-app/gradio/issues/3190

Parameters:	width (str, optional) – The width of the map. Defaults to ‘100%’. height (str, optional) – The height of the map. Defaults to ‘500px’.
Returns:	The HTML string to use in Gradio.
Return type:	str

to_html(filename=None, title='My Map', width='100%', height='880px', add_layer_control=True, **kwargs)[source]¶

Saves the map as an HTML file.

Parameters:

filename (str, optional) – The output file path to the HTML file.
title (str, optional) – The title of the HTML file. Defaults to ‘My Map’.
width (str, optional) – The width of the map in pixels or percentage. Defaults to ‘100%’.
height (str, optional) – The height of the map in pixels. Defaults to ‘880px’.
add_layer_control (bool, optional) – Whether to add the LayersControl. Defaults to True.

to_image(filename=None, monitor=1)[source]¶

Saves the map as a PNG or JPG image.

Parameters:	filename (str, optional) – The output file path to the image. Defaults to None. monitor (int, optional) – The monitor to take the screenshot. Defaults to 1.

to_streamlit(width=None, height=600, scrolling=False, **kwargs)[source]¶

Renders map figure in a Streamlit app.

Parameters:	width (int, optional) – Width of the map. Defaults to None. height (int, optional) – Height of the map. Defaults to 600. responsive (bool, optional) – Whether to make the map responsive. Defaults to True. scrolling (bool, optional) – If True, show a scrollbar when the content is larger than the iframe. Otherwise, do not show a scrollbar. Defaults to False.
Returns:	components.html object.
Return type:	streamlit.components

toolbar_reset()[source]¶: Reset the toolbar so that no tool is selected.

ts_inspector(left_ts, left_names=None, left_vis={}, left_index=0, right_ts=None, right_names=None, right_vis=None, right_index=-1, width='130px', date_format='YYYY-MM-dd', add_close_button=False, **kwargs)[source]¶

Creates a split-panel map for inspecting timeseries images.

Parameters:

left_ts (object) – An ee.ImageCollection to show on the left panel.
left_names (list) – A list of names to show under the left dropdown.
left_vis (dict, optional) – Visualization parameters for the left layer. Defaults to {}.
left_index (int, optional) – The index of the left layer to show. Defaults to 0.
right_ts (object) – An ee.ImageCollection to show on the right panel.
right_names (list) – A list of names to show under the right dropdown.
right_vis (dict, optional) – Visualization parameters for the right layer. Defaults to {}.
right_index (int, optional) – The index of the right layer to show. Defaults to -1.
width (str, optional) – The width of the dropdown list. Defaults to ‘130px’.
date_format (str, optional) – The date format to show in the dropdown. Defaults to ‘YYYY-MM-dd’.
add_close_button (bool, optional) – Whether to show the close button. Defaults to False.

update_layer_manager()[source]¶: Update the Layer Manager.

user_roi_coords(decimals=4)[source]¶

Return the bounding box of the ROI as a list of coordinates.

Parameters:	decimals (int, optional) – Number of decimals to round the coordinates to. Defaults to 4.

video_overlay(url, bounds, name='Video')[source]¶

Overlays a video from the Internet on the map.

Parameters:	url (str) – http URL of the video, such as “https://www.mapbox.com/bites/00188/patricia_nasa.webm” bounds (tuple) – bounding box of the video in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)). name (str) – name of the layer to show on the layer control.

zoom_to_bounds(bounds)[source]¶

Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

Parameters:	bounds (list \| tuple) – A list/tuple containing minx, miny, maxx, maxy values for the bounds.

zoom_to_gdf(gdf)[source]¶

Zooms to the bounding box of a GeoPandas GeoDataFrame.

Parameters:	gdf (GeoDataFrame) – A GeoPandas GeoDataFrame.

zoom_to_me(zoom=14, add_marker=True)[source]¶

Zoom to the current device location.

Parameters:	zoom (int, optional) – Zoom level. Defaults to 14. add_marker (bool, optional) – Whether to add a marker of the current device location. Defaults to True.

geemap.geemap.ee_tile_layer(ee_object, vis_params={}, name='Layer untitled', shown=True, opacity=1.0)[source]¶

Converts and Earth Engine layer to ipyleaflet TileLayer.

Parameters:

ee_object (Collection|Feature|Image|MapId) – The object to add to the map.
vis_params (dict, optional) – The visualization parameters. Defaults to {}.
name (str, optional) – The name of the layer. Defaults to ‘Layer untitled’.
shown (bool, optional) – A flag indicating whether the layer should be on by default. Defaults to True.
opacity (float, optional) – The layer’s opacity represented as a number between 0 and 1. Defaults to 1.

geemap.geemap.get_basemap(name)[source]¶

Gets a basemap tile layer by name.

Parameters:	name (str) – The name of the basemap.
Returns:	The basemap layer.
Return type:	ipylealfet.TileLayer \| ipyleaflet.WMSLayer

geemap.geemap.linked_maps(rows=2, cols=2, height='400px', ee_objects=[], vis_params=[], labels=[], label_position='topright', **kwargs)[source]¶

Create linked maps of Earth Engine data layers.

Parameters:	rows (int, optional) – The number of rows of maps to create. Defaults to 2. cols (int, optional) – The number of columns of maps to create. Defaults to 2. height (str, optional) – The height of each map in pixels. Defaults to “400px”. ee_objects (list, optional) – The list of Earth Engine objects to use for each map. Defaults to []. vis_params (list, optional) – The list of visualization parameters to use for each map. Defaults to []. labels (list, optional) – The list of labels to show on the map. Defaults to []. label_position (str, optional) – The position of the label, can be [topleft, topright, bottomleft, bottomright]. Defaults to “topright”.
Raises:	`ValueError` – If the length of ee_objects is not equal to rowscols. `ValueError` – If the length of vis_params is not equal to rowscols. `ValueError` – If the length of labels is not equal to rows*cols.
Returns:	A GridspecLayout widget.
Return type:	ipywidget

geemap.geemap.ts_inspector(layers_dict=None, left_name=None, right_name=None, width='120px', center=[40, -100], zoom=4, **kwargs)[source]¶

Creates a time series inspector.

Parameters:	layers_dict (dict, optional) – A dictionary of layers to be shown on the map. Defaults to None. left_name (str, optional) – A name for the left layer. Defaults to None. right_name (str, optional) – A name for the right layer. Defaults to None. width (str, optional) – Width of the dropdown list. Defaults to “120px”. center (list, optional) – Center of the map. Defaults to [40, -100]. zoom (int, optional) – Zoom level of the map. Defaults to 4.
Returns:	The Map instance.
Return type:	leafmap.Map

geemap.legends module¶

Module of sample legends for some commonly used geospatial datasets.

geemap.legends.ee_table_to_legend(in_table, out_file)[source]¶

Converts an Earth Engine color table to a dictionary

Parameters:	in_table (str) – The input file path (.txt) to the Earth Engine color table. out_file* (str) – The output file path (*.txt) to the legend dictionary.

Module contents¶

Top-level package for geemap.

geemap.use_folium()[source]¶: Whether to use the folium or ipyleaflet plotting backend.