API Reference

Main Class

class geovizpy.Geoviz(**kwargs)

Bases: MarksMixin, PlotsMixin, LegendsMixin, EffectsMixin, ControlsMixin, RendererMixin

A Python wrapper for the geoviz JavaScript library. Allows creating maps by chaining commands and rendering them to an HTML file.

add_export_control(pos=None, x=10, y=50, title='Export')

Add a download button to export the map as SVG or PNG (expands on hover).

Parameters:

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the button.

add_layer_control(layers=None, pos=None, x=10, y=10, title='Layers')

Add a collapsible layer control widget (expands on hover).

Parameters:

• layers (list) – List of layer IDs to control. If None, finds all layers with IDs.

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the control panel.

add_opacity_control(layers, pos=None, x=10, y=90, title='Opacity')

Add a slider to control the opacity of one or multiple layers.

Parameters:

• layers (string or list) – The ID(s) of the layer(s) to control.

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the control.

bertin(**kwargs)

Draw a Bertin map (dots).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name.

• n (int) – Number of dots per unit.

choro(**kwargs)

Draw a choropleth map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• method (string) – Classification method (‘quantile’, ‘jenks’, ‘equal’, etc.).

• nb (int) – Number of classes.

• colors (string|list) – Color palette name or list of colors.

• legend (bool) – Whether to show the legend (default: True).

• leg_pos (list) – Legend position [x, y].

• leg_title (string) – Legend title.

circle(**kwargs)

Draw circles on the map (low-level mark). For proportional circles with legend, use prop().

Parameters:

• data (object) – GeoJSON FeatureCollection.

• r (string|number) – Radius value or property name.

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• tip (string|bool) – Tooltip content.

earth(**kwargs)

Draw the earth (background).

effect_blur(**kwargs)

Apply a blur effect.

Parameters:

• id (string) – ID of the effect.

• stdDeviation (number) – Standard deviation of the blur.

effect_clipPath(**kwargs)

Apply a clip path effect.

Parameters:

• id (string) – ID of the effect.

• datum (object) – GeoJSON to use as clip path.

effect_radialGradient(**kwargs)

Apply a radial gradient effect.

Parameters:

• id (string) – ID of the effect.

• stops (list) – List of stops (e.g., [{“offset”: “0%”, “color”: “white”}, …]).

effect_shadow(**kwargs)

Apply a shadow effect.

Parameters:

• id (string) – ID of the effect.

• dx (number) – X offset.

• dy (number) – Y offset.

• stdDeviation (number) – Blur amount.

• opacity (number) – Opacity of the shadow.

• color (string) – Color of the shadow.

empty(**kwargs)

Create an empty layer.

footer(**kwargs)

Add a footer (source, author) to the map.

Parameters:

• text (string) – Footer text.

• fontSize (number) – Font size.

• fill (string) – Text color.

• anchor (string) – Text anchor.

get_config()

Return the configuration as a JSON-compatible list of commands.

graticule(**kwargs)

Add a graticule to the map.

Parameters:

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

• step (list) – Step [x, y] in degrees.

grid(**kwargs)

Draw a grid.

halfcircle(**kwargs)

Draw half-circles.

header(**kwargs)

Add a header (title) to the map.

Parameters:

• text (string) – Title text.

• fontSize (number) – Font size.

• fontFamily (string) – Font family.

• fill (string) – Text color.

• anchor (string) – Text anchor (“start”, “middle”, “end”).

heatmap(**kwargs)

Draw a heatmap (alias for smooth).

See smooth() for available parameters.

legend_box(**kwargs)

Draw a box legend.

legend_choro_horizontal(**kwargs)

Draw a horizontal choropleth legend.

legend_choro_vertical(**kwargs)

Draw a vertical choropleth legend.

legend_circles(**kwargs)

Draw a circles legend.

legend_circles_half(**kwargs)

Draw a half-circles legend.

legend_circles_nested(**kwargs)

Draw a nested circles legend.

legend_mushrooms(**kwargs)

Draw a mushrooms legend.

legend_spikes(**kwargs)

Draw a spikes legend.

legend_squares(**kwargs)

Draw a squares legend.

legend_squares_nested(**kwargs)

Draw a nested squares legend.

legend_symbol_horizontal(**kwargs)

Draw a horizontal symbol legend.

legend_symbol_vertical(**kwargs)

Draw a vertical symbol legend.

legend_typo_horizontal(**kwargs)

Draw a horizontal typology legend.

legend_typo_vertical(**kwargs)

Draw a vertical typology legend.

north(**kwargs)

Add a north arrow.

Parameters:

• x (number) – X position.

• y (number) – Y position.

• width (number) – Width of the arrow.

outline(**kwargs)

Add an outline to the map (graticule sphere).

Parameters:

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

path(**kwargs)

Draw a path (geometry) on the map.

Parameters:

• datum (object) – GeoJSON Feature or FeatureCollection.

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

picto(**kwargs)

Draw a pictogram map.

plot(**kwargs)

Generic plot function.

Parameters:

• type (string) – Type of plot (“choro”, “prop”, “typo”, etc.).

• data (object) – GeoJSON data.

• var (string) – Variable to map.

prop(**kwargs)

Draw a proportional symbol map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• symbol (string) – Symbol type (“circle”, “square”, “spike”).

• k (number) – Size of the largest symbol.

• fill (string) – Fill color.

• legend (bool) – Show legend.

• leg_type (string) – Legend style (“nested”, “separate”).

propchoro(**kwargs)

Draw proportional symbols colored by a choropleth variable.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable for symbol size.

• var2 (string) – Variable for color.

• method (string) – Classification method for color.

• colors (string|list) – Color palette.

proptypo(**kwargs)

Draw proportional symbols colored by categories.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable for symbol size.

• var2 (string) – Variable for category color.

render_html(filename='map.html')

Render the map to an HTML file.

rhumbs(**kwargs)

Draw rhumb lines.

save(filename='map.html')

Save the map to a file.

If filename ends with .html, saves the interactive map. If filename ends with .png or .svg, saves a static image.

For image export, ‘playwright’ is required. Install it with: pip install geovizpy[export] playwright install

scalebar(**kwargs)

Add a scale bar.

Parameters:

• x (number) – X position.

• y (number) – Y position.

• units (string) – “km” or “mi”.

show(width=800, height=600)

Display the map in a Jupyter notebook using an IFrame.

Parameters:

• width (int/str) – Width of the display area (default 800).

• height (int/str) – Height of the display area (default 600).

smooth(**kwargs)

Draw a smooth density map (isobands).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• colors (string|list) – Color palette name or list of colors.

• fill (string) – Single fill color (if no var).

• bandwidth (number) – Kernel bandwidth in pixels.

• thresholds (int) – Number of isoband thresholds.

• cellSize (number) – Grid cell size in pixels.

• fillOpacity (number) – Fill opacity (0–1).

• strokeOpacity (number) – Stroke opacity (0–1).

• leg_pos (list) – Legend position [x, y].

• leg_title (string) – Legend title.

spike(**kwargs)

Draw spikes on the map (low-level mark).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• height (string|number) – Height value or property name.

• width (number) – Width of the spike.

• fill (string) – Fill color.

square(**kwargs)

Draw squares on the map (low-level mark). For proportional squares with legend, use prop(symbol=”square”).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• side (string|number) – Side length or property name.

• fill (string) – Fill color.

symbol(**kwargs)

Draw symbols.

text(**kwargs)

Add text labels to the map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• text (string) – Property name for the text.

• fontSize (number) – Font size.

• fill (string) – Text color.

tile(**kwargs)

Add a tile layer (basemap).

Parameters:

• url (string) – URL template or keyword (e.g., “worldStreet”, “openstreetmap”).

• opacity (number) – Opacity (0 to 1).

tissot(**kwargs)

Draw Tissot’s indicatrix to visualize distortion.

to_json()

Return the configuration as a JSON string.

typo(**kwargs)

Draw a typology map (categorical data).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing categories.

• colors (string|list) – Color palette or list.

• legend (bool) – Show legend.

Modules

Module containing low-level drawing marks.

class geovizpy.marks.MarksMixin

Bases: object

Mixin class for drawing marks on the map.

outline(**kwargs)

Add an outline to the map (graticule sphere).

Parameters:

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

graticule(**kwargs)

Add a graticule to the map.

Parameters:

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

• step (list) – Step [x, y] in degrees.

path(**kwargs)

Draw a path (geometry) on the map.

Parameters:

• datum (object) – GeoJSON Feature or FeatureCollection.

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• strokeWidth (number) – Stroke width.

header(**kwargs)

Add a header (title) to the map.

Parameters:

• text (string) – Title text.

• fontSize (number) – Font size.

• fontFamily (string) – Font family.

• fill (string) – Text color.

• anchor (string) – Text anchor (“start”, “middle”, “end”).

footer(**kwargs)

Add a footer (source, author) to the map.

Parameters:

• text (string) – Footer text.

• fontSize (number) – Font size.

• fill (string) – Text color.

• anchor (string) – Text anchor.

circle(**kwargs)

Draw circles on the map (low-level mark). For proportional circles with legend, use prop().

Parameters:

• data (object) – GeoJSON FeatureCollection.

• r (string|number) – Radius value or property name.

• fill (string) – Fill color.

• stroke (string) – Stroke color.

• tip (string|bool) – Tooltip content.

square(**kwargs)

Draw squares on the map (low-level mark). For proportional squares with legend, use prop(symbol=”square”).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• side (string|number) – Side length or property name.

• fill (string) – Fill color.

spike(**kwargs)

Draw spikes on the map (low-level mark).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• height (string|number) – Height value or property name.

• width (number) – Width of the spike.

• fill (string) – Fill color.

text(**kwargs)

Add text labels to the map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• text (string) – Property name for the text.

• fontSize (number) – Font size.

• fill (string) – Text color.

tile(**kwargs)

Add a tile layer (basemap).

Parameters:

• url (string) – URL template or keyword (e.g., “worldStreet”, “openstreetmap”).

• opacity (number) – Opacity (0 to 1).

scalebar(**kwargs)

Add a scale bar.

Parameters:

• x (number) – X position.

• y (number) – Y position.

• units (string) – “km” or “mi”.

north(**kwargs)

Add a north arrow.

Parameters:

• x (number) – X position.

• y (number) – Y position.

• width (number) – Width of the arrow.

plot(**kwargs)

Generic plot function.

Parameters:

• type (string) – Type of plot (“choro”, “prop”, “typo”, etc.).

• data (object) – GeoJSON data.

• var (string) – Variable to map.

tissot(**kwargs)

Draw Tissot’s indicatrix to visualize distortion.

rhumbs(**kwargs)

Draw rhumb lines.

earth(**kwargs)

Draw the earth (background).

empty(**kwargs)

Create an empty layer.

halfcircle(**kwargs)

Draw half-circles.

symbol(**kwargs)

Draw symbols.

grid(**kwargs)

Draw a grid.

Module for thematic map plots.

class geovizpy.plots.PlotsMixin

Bases: object

Mixin class for thematic map plots.

choro(**kwargs)

Draw a choropleth map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• method (string) – Classification method (‘quantile’, ‘jenks’, ‘equal’, etc.).

• nb (int) – Number of classes.

• colors (string|list) – Color palette name or list of colors.

• legend (bool) – Whether to show the legend (default: True).

• leg_pos (list) – Legend position [x, y].

• leg_title (string) – Legend title.

typo(**kwargs)

Draw a typology map (categorical data).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing categories.

• colors (string|list) – Color palette or list.

• legend (bool) – Show legend.

prop(**kwargs)

Draw a proportional symbol map.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• symbol (string) – Symbol type (“circle”, “square”, “spike”).

• k (number) – Size of the largest symbol.

• fill (string) – Fill color.

• legend (bool) – Show legend.

• leg_type (string) – Legend style (“nested”, “separate”).

propchoro(**kwargs)

Draw proportional symbols colored by a choropleth variable.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable for symbol size.

• var2 (string) – Variable for color.

• method (string) – Classification method for color.

• colors (string|list) – Color palette.

proptypo(**kwargs)

Draw proportional symbols colored by categories.

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable for symbol size.

• var2 (string) – Variable for category color.

picto(**kwargs)

Draw a pictogram map.

bertin(**kwargs)

Draw a Bertin map (dots).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name.

• n (int) – Number of dots per unit.

smooth(**kwargs)

Draw a smooth density map (isobands).

Parameters:

• data (object) – GeoJSON FeatureCollection.

• var (string) – Variable name containing numeric values.

• colors (string|list) – Color palette name or list of colors.

• fill (string) – Single fill color (if no var).

• bandwidth (number) – Kernel bandwidth in pixels.

• thresholds (int) – Number of isoband thresholds.

• cellSize (number) – Grid cell size in pixels.

• fillOpacity (number) – Fill opacity (0–1).

• strokeOpacity (number) – Stroke opacity (0–1).

• leg_pos (list) – Legend position [x, y].

• leg_title (string) – Legend title.

heatmap(**kwargs)

Draw a heatmap (alias for smooth).

See smooth() for available parameters.

Module for map legends.

class geovizpy.legends.LegendsMixin

Bases: object

Mixin class for map legends.

legend_circles_nested(**kwargs)

Draw a nested circles legend.

legend_circles(**kwargs)

Draw a circles legend.

legend_squares(**kwargs)

Draw a squares legend.

legend_squares_nested(**kwargs)

Draw a nested squares legend.

legend_circles_half(**kwargs)

Draw a half-circles legend.

legend_spikes(**kwargs)

Draw a spikes legend.

legend_mushrooms(**kwargs)

Draw a mushrooms legend.

legend_choro_vertical(**kwargs)

Draw a vertical choropleth legend.

legend_choro_horizontal(**kwargs)

Draw a horizontal choropleth legend.

legend_typo_vertical(**kwargs)

Draw a vertical typology legend.

legend_typo_horizontal(**kwargs)

Draw a horizontal typology legend.

legend_symbol_vertical(**kwargs)

Draw a vertical symbol legend.

legend_symbol_horizontal(**kwargs)

Draw a horizontal symbol legend.

legend_box(**kwargs)

Draw a box legend.

Module for visual effects.

class geovizpy.effects.EffectsMixin

Bases: object

Mixin class for visual effects.

effect_blur(**kwargs)

Apply a blur effect.

Parameters:

• id (string) – ID of the effect.

• stdDeviation (number) – Standard deviation of the blur.

effect_shadow(**kwargs)

Apply a shadow effect.

Parameters:

• id (string) – ID of the effect.

• dx (number) – X offset.

• dy (number) – Y offset.

• stdDeviation (number) – Blur amount.

• opacity (number) – Opacity of the shadow.

• color (string) – Color of the shadow.

effect_radialGradient(**kwargs)

Apply a radial gradient effect.

Parameters:

• id (string) – ID of the effect.

• stops (list) – List of stops (e.g., [{“offset”: “0%”, “color”: “white”}, …]).

effect_clipPath(**kwargs)

Apply a clip path effect.

Parameters:

• id (string) – ID of the effect.

• datum (object) – GeoJSON to use as clip path.

Module for interactive map controls.

class geovizpy.controls.ControlsMixin

Bases: object

Mixin class for interactive map controls.

add_layer_control(layers=None, pos=None, x=10, y=10, title='Layers')

Add a collapsible layer control widget (expands on hover).

Parameters:

• layers (list) – List of layer IDs to control. If None, finds all layers with IDs.

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the control panel.

add_export_control(pos=None, x=10, y=50, title='Export')

Add a download button to export the map as SVG or PNG (expands on hover).

Parameters:

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the button.

add_opacity_control(layers, pos=None, x=10, y=90, title='Opacity')

Add a slider to control the opacity of one or multiple layers.

Parameters:

• layers (string or list) – The ID(s) of the layer(s) to control.

• pos (string) – Predefined position (“top-right”, “top-left”, etc.). Overrides x, y.

• x (int) – X position of the control.

• y (int) – Y position of the control.

• title (string) – Title of the control.