Python API

Basic Usage

JupyterGIS provides a Python API that can be used for opening QGIS projects, add raster or vector layers and apply filtering.

You can open an existing QGIS project and display it in your Jupyter Notebook:

from jupytergis import GISDocument

doc = GISDocument('file.qgz')

doc

Opening an existing file connects you to the file’s collaborative session, meaning that anyone working on the same QGIS project file, whether through the JupyterLab extension or the Python API, will see the edits you make.

Creating a GISDocument object without providing a path to an existing file would create a new empty document:

from jupytergis import GISDocument

doc = GISDocument()

doc

Once the document is opened/created, you can start creating GIS layers.

explore

jupytergis_lab.explore(data, *, layer_name='Exploration layer', basemap='topo')

Run a JupyterGIS data interaction interface alongside a Notebook.

Parameters:

data (str | Path | Any) – A GeoDataFrame or path to a GeoJSON file.

Raises:

• FileNotFoundError – Received a file path that doesn’t exist.

• NotImplementedError – Received an input value that isn’t supported yet.

• TypeError – Received an object type that isn’t supported.

• ValueError – Received an input value that isn’t supported.

Return type:

GISDocument

GISDocument

class jupytergis_lab.GISDocument(path=None, latitude=None, longitude=None, zoom=None, extent=None, bearing=None, pitch=None, projection=None)

Create a new GISDocument object.

Parameters:

path (Union[str, Path, None]) – the path to the file that you would like to open. If not provided, a new ephemeral widget will be created.

add_filter(layer_id, logical_op, feature, operator, value)

Add a filter to a layer

Parameters:

• layer_id (str) – The ID of the layer to filter

• logical_op (str) – The logical combination to apply to filters. Must be “any” or “all”

• feature (str) – The feature to be filtered on

• operator (str) – The operator used to compare the feature and value

• value (Union[str, int, float]) – The value to be filtered on

add_geojson_layer(path=None, data=None, name='GeoJSON Layer', opacity=1, logical_op=None, feature=None, operator=None, value=None, color_expr=None)

Add a GeoJSON Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• path (str | Path | None) – The path to the JSON file or URL to embed into the jGIS file.

• data (Optional[Dict]) – The raw GeoJSON data to embed into the jGIS file.

• opacity (float) – The opacity, between 0 and 1.

• color_expr – The style expression used to style the layer, defaults to None

add_geoparquet_layer(path, name='GeoParquetLayer', type='line', opacity=1, logical_op=None, feature=None, operator=None, value=None, color_expr=None)

Add a GeoParquet Layer to the document :type path: str :param path: The path to the GeoParquet file to embed into the jGIS file. :type name: str :param name: The name that will be used for the object in the document. :type type: circle’ | ‘fill’ | ‘line :param type: The type of the vector layer to create. :type opacity: float :param opacity: The opacity, between 0 and 1. :type logical_op: str | None :param logical_op: The logical combination to apply to filters. Must be “any” or “all” :type feature: str | None :param feature: The feature to be filtered on :type operator: str | None :param operator: The operator used to compare the feature and value :type value: Union[str, int, float] | None :param value: The value to be filtered on :type color_expr: :param color_expr: The style expression used to style the layer

add_heatmap_layer(feature, path=None, data=None, name='Heatmap Layer', opacity=1, blur=15, radius=8, gradient=None)

Add a Heatmap Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• path (str | Path | None) – The path to the JSON file to embed into the jGIS file.

• data (Optional[Dict]) – The raw GeoJSON data to embed into the jGIS file.

• gradient (Optional[List[str]]) – The color gradient to apply.

• opacity (float) – The opacity, between 0 and 1.

• blur (int) – The blur size in pixels

• radius (int) – The radius size in pixels

• feature (str) – The feature to use to heatmap weights

add_hillshade_layer(url, name='Hillshade Layer', urlParameters=None, attribution='')

Add a hillshade layer

Parameters:

• url (str) – URL of the hillshade layer

• name (str) – The name that will be used for the object in the document, defaults to “Hillshade Layer”

• attribution (str) – The attribution.

add_image_layer(url, coordinates, name='Image Layer', opacity=1)

Add a Image Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• url (str) – The image url.

• coordinates ([]) – Corners of image specified in longitude, latitude pairs.

• opacity (float) – The opacity, between 0 and 1.

add_raster_layer(url, name='Raster Layer', attribution='', opacity=1)

Add a Raster Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• url (str) – The tiles url.

• attribution (str) – The attribution.

• opacity (float) – The opacity, between 0 and 1.

add_tiff_layer(url, min=None, max=None, name='Tiff Layer', normalize=True, wrapX=False, attribution='', opacity=1.0, color_expr=None)

Add a tiff layer

Parameters:

• url (str) – URL of the tif

• min (int) – Minimum pixel value to be displayed, defaults to letting the map display set the value

• max (int) – Maximum pixel value to be displayed, defaults to letting the map display set the value

• name (str) – The name that will be used for the object in the document, defaults to “Tiff Layer”

• normalize (bool) – Select whether to normalize values between 0..1, if false than min/max have no effect, defaults to True

• wrapX (bool) – Render tiles beyond the tile grid extent, defaults to False

• opacity (float) – The opacity, between 0 and 1, defaults to 1.0

• color_expr – The style expression used to style the layer, defaults to None

add_vectortile_layer(url, name='Vector Tile Layer', attribution='', min_zoom=0, max_zoom=24, color_expr=None, opacity=1, logical_op=None, feature=None, operator=None, value=None)

Add a Vector Tile Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• url (str) – The tiles url.

• attribution (str) – The attribution.

• opacity (float) – The opacity, between 0 and 1.

add_video_layer(urls, name='Image Layer', coordinates=None, opacity=1)

Add a Video Layer to the document.

Parameters:

• name (str) – The name that will be used for the object in the document.

• urls (List) – URLs to video content in order of preferred format.

• coordinates (Optional[List]) – Corners of video specified in longitude, latitude pairs.

• opacity (float) – The opacity, between 0 and 1.

clear_filters(layer_id)

Clear filters on a layer

Parameters:

layer_id (str) – The ID of the layer to clear filters from

create_color_expr(color_stops, band=1.0, interpolation_type='linear')

Create a color expression used to style the layer

Parameters:

• color_stops (Dict) – Dictionary of stop values to [r, g, b, a] colors

• band (float) – The band to be colored, defaults to 1.0

• interpolation_type (str) – The interpolation function. Can be linear, discrete, or exact, defaults to ‘linear’

property layer_tree: List[str | Dict]

Get the layer tree

property layers: Dict

Get the layer list

remove_layer(layer_id)

Remove a layer from the GIS document.

Parameters:

layer_id (str) – The ID of the layer to remove.

Raises:

KeyError – If the layer does not exist.

sidecar(*, title='JupyterGIS sidecar', anchor='split-right')

Open the document in a new sidecar panel.

Parameters:

anchor (Literal['split-right', 'split-left', 'split-top', 'split-bottom', 'tab-before', 'tab-after', 'right']) – Where to position the new sidecar panel.

to_py()

Get the document structure as a Python dictionary.

Return type:

dict

update_filter(layer_id, logical_op, feature, operator, value)

Update a filter applied to a layer

Parameters:

• layer_id (str) – The ID of the layer to filter

• logical_op (str) – The logical combination to apply to filters. Must be “any” or “all”

• feature (str) – The feature to update the value for

• operator (str) – The operator used to compare the feature and value

• value (Union[str, int, float]) – The new value to be filtered on