gmaprium
Folium-style Python helpers for rendering Google Maps HTML.
gmaprium can be used to create standalone HTML maps, display maps in Jupyter Notebook, add Google tile layers to existing Folium maps, and embed maps in Streamlit apps.
Installation
pip install gmaprium
Usage
from gmaprium import Choropleth, Draw, GeoJson, HeatMap, LayerControl, Map, Marker, Polygon
m = Map(
location=[35.6812, 139.7671],
zoom_start=12,
api_key="YOUR_GOOGLE_MAPS_API_KEY",
map_type="roadmap",
height="500px",
fullscreen_control=False,
street_view_control=False,
)
Marker([35.6812, 139.7671], popup="Tokyo Station", tooltip="Tokyo", name="Stations").add_to(m)
Polygon(
[[35.70, 139.70], [35.70, 139.82], [35.62, 139.82], [35.62, 139.70]],
name="Area",
).add_to(m)
Choropleth(
geo_data={
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {"id": "central"},
"geometry": {
"type": "Polygon",
"coordinates": [[[139.735, 35.675], [139.755, 35.675], [139.755, 35.690], [139.735, 35.690], [139.735, 35.675]]],
},
}
],
},
data={"central": 42},
key_on="feature.properties.id",
name="Choropleth",
legend_name="Sample values",
).add_to(m)
HeatMap([[35.6812, 139.7671, 2], [35.6895, 139.6917, 1]], name="Heat").add_to(m)
Draw(export=True, filename="drawn.geojson").add_to(m)
LayerControl().add_to(m)
# Full HTML document.
m.save("map.html")
# Embeddable HTML fragment for web apps.
html = m.render_fragment()
You can also pass the API key with the GOOGLE_MAPS_API_KEY environment variable.
Set fullscreen_control=True or fullscreen_control=False to control Google Maps SDK's built-in fullscreen button.
Set street_view_control=True or street_view_control=False to control the built-in Street View button.
Markers use Google's AdvancedMarkerElement. If you add markers without passing map_id=..., the renderer uses Google's DEMO_MAP_ID for local testing.
Supported Elements
MapMarkerPolylinePolygonCircleGeoJsonChoroplethDrawHeatMapLayerControl
GeoJson accepts GeoJSON dictionaries, JSON file paths, objects with __geo_interface__, and GeoPandas-like objects with to_json().
Choropleth accepts GeoJSON plus Folium-style data, columns, key_on, bins, fill/stroke styling, missing-value styling, highlight, and legend options.
It renders as a Google Maps Data layer and can be toggled with LayerControl.
Draw adds a Folium-style drawing toolbar for markers, polylines, polygons, rectangles, and circles.
Set export=True to let users download drawn features as GeoJSON.
Use draw_options to show or hide specific drawing tools:
Draw(
draw_options={
"marker": True,
"polyline": False,
"polygon": True,
"rectangle": False,
"circle": True,
},
export=True,
).add_to(m)
HeatMap uses a canvas overlay instead of Google's deprecated JavaScript HeatmapLayer.
It ports the Leaflet.heat/simpleheat rendering model, including radius, blur, min_opacity, max_zoom, max_value, and gradient.
The defaults match Leaflet.heat/simpleheat on a typical OSM map: radius=25, blur=15, min_opacity=0.05, max_zoom=18, max_value=1.0, and the blue-cyan-lime-yellow-red gradient.
Lower zoom levels are intentionally faded by Leaflet.heat's max_zoom - zoom intensity scale. Set max_zoom closer to your initial zoom if the heat fades too quickly.
Configuration Reference
Map
| Option | Default | Description |
|---|---|---|
location |
required | Initial map center as [lat, lng]. |
zoom_start |
10 |
Initial Google Maps zoom level. |
api_key |
None |
Google Maps API key. If omitted, GOOGLE_MAPS_API_KEY is used. |
map_type |
"roadmap" |
One of "roadmap", "satellite", "hybrid", or "terrain". |
width |
"100%" |
CSS width for HTML and notebook rendering. Integers are treated as pixels. |
height |
"100%" |
CSS height for HTML and notebook rendering. Integers are treated as pixels. |
map_id |
None |
Google Maps Map ID. Markers and Draw use DEMO_MAP_ID if needed and no ID is supplied. |
fullscreen_control |
None |
Enable or disable Google Maps fullscreen control. None leaves the SDK default. |
street_view_control |
None |
Enable or disable Google Maps Street View control. None leaves the SDK default. |
options |
{} |
Extra raw Google Maps JavaScript MapOptions. |
Vector Elements
| Element | Options |
|---|---|
Marker |
location, popup, tooltip, icon, draggable, name |
Polyline |
locations, color, weight, opacity, name |
Polygon |
locations, color, fill_color, fill_opacity, weight, name |
Circle |
location, radius, color, fill_color, fill_opacity, weight, name |
GeoJson |
data, name, style_function |
name makes the element available in LayerControl. style_function is called with a sample GeoJSON feature and should return Google Maps style options such as fillColor, fillOpacity, strokeColor, and strokeWeight.
Draw
| Option | Default | Description |
|---|---|---|
export |
False |
Show the Export button when True. |
filename |
"data.geojson" |
Download filename used by the Export button. |
position |
"topleft" |
Toolbar position: "topleft", "topright", "bottomleft", or "bottomright". |
show_geometry_on_click |
True |
Show drawn feature GeoJSON in an alert when a completed drawing is clicked. |
draw_options |
{} |
Drawing tool visibility and style options. |
feature_group |
None |
Reserved for Folium compatibility; currently unsupported. |
edit_options |
{} |
Reserved for Folium compatibility. |
on |
{} |
Reserved for Folium-style event compatibility. |
draw_options supports these visibility keys: marker, polyline, polygon, rectangle, and circle. Set a key to False to hide that drawing tool.
Draw(draw_options={"marker": True, "polyline": False, "circle": False}).add_to(m)
The same dictionary also accepts style keys used for newly drawn shapes: strokeColor, strokeOpacity, strokeWeight, fillColor, and fillOpacity.
Choropleth
| Option | Default | Description |
|---|---|---|
geo_data |
required | GeoJSON dict, path, __geo_interface__ object, or GeoPandas-like object. |
data |
None |
Mapping, sequence of pairs, Series-like, or DataFrame-like data to join. |
columns |
None |
Key/value column names for DataFrame-like data. |
key_on |
None |
GeoJSON feature path such as "feature.properties.id". |
bins |
6 |
Number of bins or explicit bin edges. |
fill_color |
"Blues" when data is supplied |
ColorBrewer palette name, or a CSS color when no joined data is supplied. |
nan_fill_color |
"black" |
Fill color for missing or non-numeric values. |
fill_opacity |
0.6 |
Fill opacity for matched values. |
nan_fill_opacity |
fill_opacity |
Fill opacity for missing values. |
line_color |
"black" |
Boundary color. |
line_weight |
1 |
Boundary width. |
line_opacity |
1 |
Boundary opacity. |
name |
None |
Layer name used by LayerControl. |
legend_name |
"" |
Caption for the generated legend. |
highlight |
False |
Highlight features on hover. |
use_jenks |
False |
Use Jenks natural breaks. Requires jenkspy. |
topojson is not supported yet. threshold_scale is accepted as a Folium-compatible alias for bins.
HeatMap
| Option | Default | Description |
|---|---|---|
data |
required | Points as [lat, lng], [lat, lng, weight], or {"location": [lat, lng], "weight": n}. |
name |
None |
Layer name used by LayerControl. |
radius |
25 |
Point radius in pixels. |
blur |
15 |
Blur radius in pixels. |
min_opacity |
0.05 |
Minimum alpha for rendered points. |
max_zoom |
18 |
Leaflet.heat-style zoom intensity reference. |
max_value |
1.0 |
Weight value that maps to full intensity. |
gradient |
simpleheat gradient | Mapping of stop positions to CSS colors. |
opacity |
1.0 |
Reserved overall layer opacity option. |
intensity |
1.0 |
Reserved intensity multiplier option. |
threshold |
0.03 |
Reserved low-alpha threshold option. |
scale_radius_with_zoom |
False |
Reserved option for zoom-scaled radius. |
min_radius |
6 |
Minimum radius when zoom scaling is enabled. |
max_radius |
240 |
Maximum radius when zoom scaling is enabled. |
Streamlit
| Option | Default | Description |
|---|---|---|
map_obj |
required | gmaprium.Map instance to render. |
height |
map height in pixels | Component height. If omitted, pixel values from Map.height are used. |
width |
None |
Component width. None lets Streamlit choose the width. |
scrolling |
False |
Enable iframe scrolling. |
returned_objects |
map and Draw state fields | Fields to return. Use [] to avoid reruns from map or Draw updates. |
on_change_events |
["draw"] |
Events that trigger on_change: "draw", "zoom", and "move". |
key |
None |
Stable Streamlit component key. Recommended when using Draw. |
on_change |
None |
Streamlit callback called when one of on_change_events changes the component value. |
args |
None |
Positional arguments passed to on_change. |
kwargs |
None |
Keyword arguments passed to on_change. |
default |
generated from returned_objects |
Initial return value before any Draw action. |
st_gmaprium() returns a dictionary with all_drawings, last_active_drawing, zoom, center, bounds, and last_event by default.
Draw values use GeoJSON Feature dictionaries.
The legacy google_tiles_url() and add_google_tiles() helpers are still available for projects that want to add Google tile URLs to an existing Folium map.
Notebook
In Jupyter Notebook, display the map by returning the Map object as the last expression in a cell.
import os
from gmaprium import HeatMap, LayerControl, Map, Marker
os.environ["GOOGLE_MAPS_API_KEY"] = "your-api-key"
m = Map(location=[35.6812, 139.7671], zoom_start=12, height="500px")
Marker([35.6812, 139.7671], popup="Tokyo Station", name="Markers").add_to(m)
HeatMap([[35.6812, 139.7671, 1.0]], name="Heat", max_zoom=14).add_to(m)
LayerControl().add_to(m)
m
You can also display explicitly:
from IPython.display import HTML, display
display(HTML(m.render_fragment()))
The notebook example is available at examples/example.ipynb.
Folium Extension
If you already use Folium, add Google tile layers to a folium.Map with add_google_tiles().
import folium
from gmaprium import add_google_tiles
m = folium.Map(location=[35.6812, 139.7671], zoom_start=12, tiles=None)
add_google_tiles(m, api_key="your-api-key", map_type="roadmap", name="Google Roadmap")
add_google_tiles(m, api_key="your-api-key", map_type="satellite", name="Google Satellite", show=False)
folium.LayerControl().add_to(m)
m.save("folium_google_tiles.html")
This Folium extension only adds Google tile layers. It does not enable the Google Maps JavaScript API renderer or gmaprium's HeatMap.
The Folium example is available at examples/folium_extension.py.
Streamlit
Use st_gmaprium() to render a gmaprium.Map inside a Streamlit app.
Draw and map state are returned in a st_folium-style dictionary with all_drawings, last_active_drawing, zoom, center, bounds, and last_event.
import os
import streamlit as st
from gmaprium import Draw, Map, Marker, st_gmaprium
api_key = os.environ["GOOGLE_MAPS_API_KEY"]
m = Map(location=[35.6812, 139.7671], zoom_start=12, api_key=api_key, height="600px")
Marker([35.6812, 139.7671], popup="Tokyo Station").add_to(m)
Draw(export=True).add_to(m)
draw_result = st_gmaprium(m, key="main-map")
st.json(draw_result)
Use on_change and on_change_events when you want to react to Draw, zoom, or move updates through Streamlit session state.
def on_map_change():
state = st.session_state["main-map"]
if state["last_event"] == "zoom":
st.toast(f"Zoom changed to {state['zoom']}")
draw_result = st_gmaprium(
m,
key="main-map",
on_change=on_map_change,
on_change_events=["draw", "zoom", "move"],
)
Install the optional dependency and run the example app:
python -m pip install -e ".[dev,streamlit]"
export GOOGLE_MAPS_API_KEY="your-api-key"
streamlit run examples/streamlit_app.py
The Streamlit example is available at examples/streamlit_app.py.
Development
python -m pip install -e ".[dev]"
pytest
Metadata
Release files for gmaprium 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gmaprium-0.3.1.tar.gz | 33.6 kB | Without provenance | Details for gmaprium-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gmaprium-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for gmaprium-0.3.1-py3-none-any.whl |
Total release size: 59.9 kB
Release files / gmaprium-0.3.1.tar.gz
| Download URL | gmaprium-0.3.1.tar.gz |
|---|---|
| Size | 33.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eb85e72383132caf4c2b572bc28549355ab95c357df459eb5c6489c79323ce87
|
|
BLAKE2b-256 checksum How to use checksums |
4f4d892346e62d4307a4146e14699f6afe0b11db785b6c9a93ac69537538ed69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / gmaprium-0.3.1-py3-none-any.whl
| Download URL | gmaprium-0.3.1-py3-none-any.whl |
|---|---|
| Size | 26.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb158cd312796c50d8b530be05bf77276870c654528d0fa321e02cbbcec5deca
|
|
BLAKE2b-256 checksum How to use checksums |
d9eb27f9b567bc7abec12539a8b942995cb1accfaff6397fddfb592cfc81a6b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for gmaprium 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.