FoliumライクにGoogle Mapsを扱うgmapriumを使ってみた

Last updated at 2026-05-03Posted at 2026-05-03

gmapriumの使い方

gmaprium は、Folium に近い書き味で Google Maps の HTML を描画できる Python ライブラリです。
既に Folium を使っているなら、Map にレイヤーを足していく感覚のまま、Google Maps ベースの地図を扱えます。

この記事では、Folium ユーザーを主な読者として、gmaprium の全体像をつかめるようにまとめます。
単体で HTML を出力する使い方だけでなく、Jupyter Notebook、Folium 連携、Streamlit 埋め込みまで一通り紹介します。

gmapriumでできること

gmaprium の主な用途は次の 4 つです。

Google Maps ベースの地図を単体 HTML として出力する
Jupyter Notebook 上でそのまま表示する
既存の Folium マップに Google タイルを追加する
Streamlit アプリに埋め込む

特に Folium ユーザーにとって重要なのは、「gmaprium 本体」と「Folium 拡張」は役割が違うという点です。

Map, Marker, HeatMap などを使う gmaprium 本体は、Google Maps JavaScript API を土台に地図を描画し、HeatMap は canvas を使って重ね描きします
add_google_tiles() を使う Folium 拡張は、既存の folium.Map に Google タイルレイヤーを追加します

つまり、Google Maps の描画機能を中心に使いたいなら gmaprium 本体、Folium ベースの既存コードを活かしつつタイルだけ差し替えたいなら Folium 拡張が向いています。

インストールとAPIキーの準備

まずはインストールします。

pip install gmaprium

Google Maps を使うので、API キーも必要です。
キーは Map(..., api_key="...") で直接渡せますが、環境変数に入れておくと扱いやすくなります。

export GOOGLE_MAPS_API_KEY="your-api-key"

Python 側では、環境変数を設定しておけば api_key を明示しない書き方もできます。

最初の1枚を表示する

最初に試すなら、Map に Marker、canvas ベースで描画される HeatMap、LayerControl を追加する最小例が分かりやすいです。

from gmaprium import HeatMap, LayerControl, Map, Marker

m = Map(
    location=[35.6812, 139.7671],
    zoom_start=12,
    api_key="YOUR_GOOGLE_MAPS_API_KEY",
    map_type="roadmap",
    height="500px",
)

Marker(
    [35.6812, 139.7671],
    popup="Tokyo Station",
    tooltip="Tokyo Station",
    name="Markers",
).add_to(m)

HeatMap(
    [
        [35.6812, 139.7671],
        [35.6895, 139.6917],
        [35.6812, 139.7671],
        [35.6825, 139.7685],
        [35.6840, 139.7700],
        [35.6895, 139.6917],
        [35.6920, 139.6940],
        [35.6586, 139.7454],
        [35.6600, 139.7480],
        [35.7101, 139.8107],
        [35.7085, 139.8088],
    ],
    name="Heat",
    max_zoom=14,
).add_to(m)

LayerControl().add_to(m)

m.save("map.html")

m.save("map.html") で完全な HTML ファイルを書き出せます。
生成されたファイルをブラウザで開けば、そのまま地図を確認できます。

Web アプリに埋め込みたい場合は、完全な HTML 文書ではなく HTML 断片が欲しいことがあります。
その場合は render_fragment() を使います。

html = m.render_fragment()

このあたりの API は Folium にかなり近く、add_to() でレイヤーを積んでいく感覚で扱えます。

もう少し本格的な地図を作る

gmaprium では、Marker だけでなく Polyline、Polygon、Circle、GeoJson、HeatMap も同じ流れで追加できます。

from gmaprium import Circle, GeoJson, HeatMap, LayerControl, Map, Marker, Polygon, Polyline

m = Map(
    location=[35.6812, 139.7671],
    zoom_start=12,
    api_key="YOUR_GOOGLE_MAPS_API_KEY",
    map_type="roadmap",
    height="600px",
)

Marker([35.6812, 139.7671], popup="Tokyo Station", name="Markers").add_to(m)

Polyline(
    [[35.6812, 139.7671], [35.6895, 139.6917]],
    color="#0b57d0",
    weight=4,
    name="Route",
).add_to(m)

Polygon(
    [[35.7000, 139.7000], [35.7000, 139.8200], [35.6200, 139.8200], [35.6200, 139.7000]],
    color="#188038",
    fill_color="#34a853",
    fill_opacity=0.18,
    name="Area",
).add_to(m)

Circle(
    [35.6895, 139.6917],
    radius=700,
    color="#d93025",
    fill_color="#f28b82",
    fill_opacity=0.25,
    name="Circle",
).add_to(m)

GeoJson(
    {
        "type": "FeatureCollection",
        "features": [],
    },
    name="GeoJSON",
).add_to(m)

HeatMap(
    [
        [35.6812, 139.7671, 1.0],
        [35.6825, 139.7685, 0.95],
        {"location": [35.7101, 139.8107], "weight": 0.85},
    ],
    name="Heat",
    max_zoom=14,
).add_to(m)

LayerControl().add_to(m)

GeoJson は GeoJSON の辞書だけでなく、JSON ファイルパス、__geo_interface__ を持つオブジェクト、to_json() を持つ GeoPandas ライクなオブジェクトも受け取れます。
既に GeoJSON を扱うコードがあるなら、そのまま流し込みやすい設計です。

Foliumユーザー向け: 既存マップにGoogleタイルを追加する

既に Folium ベースのコードがあるなら、いきなり gmaprium の Map に置き換えなくても大丈夫です。
add_google_tiles() を使えば、folium.Map に Google のタイルレイヤーを追加できます。

import folium
from folium import Circle, GeoJson, Polygon
from folium.plugins import HeatMap

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_GOOGLE_MAPS_API_KEY",
    map_type="roadmap",
    name="Google Roadmap",
)
add_google_tiles(
    m,
    api_key=api_key,
    map_type="satellite",
    name="Google Satellite",
    show=False,
)

folium.Marker(
    [35.6812, 139.7671],
    popup="Tokyo Station",
    tooltip="Tokyo Station",
).add_to(m)

Polygon(
    [[35.7000, 139.7000], [35.7000, 139.8200], [35.6200, 139.8200], [35.6200, 139.7000]],
    color="#188038",
    fill_color="#34a853",
    fill_opacity=0.18,
    name="Area",
).add_to(m)

Circle(
    [35.6895, 139.6917],
    radius=700,
    color="#d93025",
    fill_color="#f28b82",
    fill_opacity=0.25,
    name="Circle",
).add_to(m)

GeoJson(
    {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "properties": {"name": "Sample GeoJSON"},
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [139.735, 35.675],
                            [139.755, 35.675],
                            [139.755, 35.690],
                            [139.735, 35.690],
                            [139.735, 35.675],
                        ]
                    ],
                },
            }
        ],
    },
    name="GeoJSON",
    style_function=lambda feature: {
        "fillColor": "#fbbc04",
        "fillOpacity": 0.3,
        "strokeColor": "#f9ab00",
        "strokeWeight": 2,
    },
).add_to(m)

HeatMap(
    [
        [35.6812, 139.7671],
        [35.6825, 139.7685],
        [35.6840, 139.7700],
        [35.6895, 139.6917],
        [35.6920, 139.6940],
        [35.6586, 139.7454],
        [35.6600, 139.7480],
    ],
    name="Heat",
).add_to(m)

folium.LayerControl().add_to(m)

m.save("folium_extension.html")

これは Folium から gmaprium へ移行する前の橋渡しとして便利です。
まずは既存の folium.Map に Google タイルを足し、必要に応じて gmaprium 本体へ寄せていく、という進め方ができます。

ただし、この拡張は Google タイルを追加するだけです。
gmaprium 本体のように Google Maps JavaScript API ベースで描画されるわけではなく、leafletベースでタイル描画されます。

Jupyter Notebookで使う

Notebook では、セルの最後に Map オブジェクトを置くだけで表示できます。

from gmaprium import Circle, GeoJson, HeatMap, LayerControl, Map, Marker, Polygon, Polyline

m = Map(
    location=[35.6812, 139.7671],
    zoom_start=12,
    api_key="YOUR_GOOGLE_MAPS_API_KEY",
    map_type="roadmap",
    height="600px",
)

Marker(
    [35.6812, 139.7671],
    popup="Tokyo Station",
    tooltip="Tokyo Station",
    name="Markers",
).add_to(m)

Polyline(
    [[35.6812, 139.7671], [35.6895, 139.6917]],
    color="#0b57d0",
    weight=4,
    name="Route",
).add_to(m)

Polygon(
    [[35.7000, 139.7000], [35.7000, 139.8200], [35.6200, 139.8200], [35.6200, 139.7000]],
    color="#188038",
    fill_color="#34a853",
    fill_opacity=0.18,
    name="Area",
).add_to(m)

Circle(
    [35.6895, 139.6917],
    radius=700,
    color="#d93025",
    fill_color="#f28b82",
    fill_opacity=0.25,
    name="Circle",
).add_to(m)

GeoJson(
    {
        "type": "FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "properties": {"name": "Sample GeoJSON"},
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [139.735, 35.675],
                            [139.755, 35.675],
                            [139.755, 35.690],
                            [139.735, 35.690],
                            [139.735, 35.675],
                        ]
                    ],
                },
            }
        ],
    },
    name="GeoJSON",
    style_function=lambda feature: {
        "fillColor": "#fbbc04",
        "fillOpacity": 0.3,
        "strokeColor": "#f9ab00",
        "strokeWeight": 2,
    },
).add_to(m)

HeatMap(
    [
        [35.6812, 139.7671, 1.0],
        [35.6825, 139.7685, 0.95],
        [35.6840, 139.7700, 0.9],
        [35.6895, 139.6917, 0.85],
        [35.6920, 139.6940, 0.8],
        [35.6586, 139.7454, 0.8],
        [35.6600, 139.7480, 0.75],
        [35.7101, 139.8107, 0.85],
        [35.7085, 139.8088, 0.8],
    ],
    name="Heat",
    max_zoom=14,
).add_to(m)

LayerControl().add_to(m)

m

明示的に埋め込みたい場合は、render_fragment() と IPython.display.HTML を組み合わせます。

from IPython.display import HTML, display

display(HTML(m.render_fragment()))

Notebook 上で軽く試したいときは m をそのまま返す書き方、既存の出力フローに組み込みたいときは render_fragment() と覚えると整理しやすいです。

Streamlitに埋め込む

Streamlit では st_google_map() を使います。

最小のコードは次のようになります。

from gmaprium import Map, Marker, st_google_map


m = Map(
    location=[35.6812, 139.7671],
    zoom_start=12,
    api_key="YOUR_GOOGLE_MAPS_API_KEY",
    height="600px",
)
Marker([35.6812, 139.7671], popup="Tokyo Station").add_to(m)

st_google_map(m)

サンプルの examples/streamlit_app.py では、これに加えて HeatMap や LayerControl も組み合わせています。
Notebook で試した地図を、そのままアプリに持っていきやすいのが gmaprium の分かりやすい利点です。

知っておきたい注意点

Marker は AdvancedMarkerElement を使う

gmaprium の Marker は、従来の google.maps.Marker ではなく、Google の AdvancedMarkerElement を使います。
そのため、Google Maps 側の現在の流儀に沿ったマーカー表示を扱えます。

また、Marker を使うときに map_id を渡していない場合、ローカル確認用として DEMO_MAP_ID が使われます。
map_id は Map の引数として渡します。

m = Map(
    location=[35.6812, 139.7671],
    zoom_start=12,
    api_key="YOUR_GOOGLE_MAPS_API_KEY",
    map_id="YOUR_GOOGLE_MAPS_MAP_ID",
)

まずは試したい、という段階では便利ですが、本番寄りの構成ではこのように自前の map_id を指定しておくと安心です。

HeatMap は Google 純正の HeatmapLayer ではない

gmaprium の HeatMap は、Google の deprecated な JavaScript HeatmapLayer ではなく、canvas を使った overlayとして実装されています。
内部的には Leaflet.heat / simpleheat に近い描画モデルを採用していて、radius、blur、min_opacity、max_zoom、max_value、gradient を調整できます。

Folium のヒートマップに慣れている人にとっては、設定の発想が近いので入りやすいはずです。
一方で、ズームに応じて見え方が変わるため、最初に「思ったより薄い」と感じたら max_zoom を見直すのが有効です。

まとめ

gmaprium は、Folium ライクな書き方を保ちながら Google Maps を使いたいときにちょうどよいライブラリです。

新しく Google Maps ベースで地図を組み立てるなら Map を中心に使う
既存の Folium コードを活かしたいなら add_google_tiles() から始める
Notebook や Streamlit にも展開したいなら render_fragment() や st_google_map() がそのまま活きる

Folium に慣れているほど、gmaprium の API は入りやすく感じるはずです。
まずは Map と Marker だけで 1 枚出力し、そのあと HeatMap、GeoJson、LayerControl を足していくと理解しやすく進められます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up