0
# Folium
1
2
A comprehensive Python library for creating interactive web maps with Leaflet.js. Folium enables data scientists and developers to visualize geospatial data through Python's data manipulation capabilities while leveraging the powerful mapping features of the Leaflet.js JavaScript library. It offers a complete set of mapping components including markers, polygons, circles, popups, tooltips, choropleth maps, and various tile layers, with support for GeoJSON data integration, custom styling, and interactive features.
3
4
## Package Information
5
6
- **Package Name**: folium
7
- **Language**: Python
8
- **Installation**: `pip install folium`
9
10
## Core Imports
11
12
```python
13
import folium
14
```
15
16
Common patterns for specific functionality:
17
18
```python
19
from folium import Map, Marker, Popup, Icon
20
from folium import GeoJson, Choropleth, FeatureGroup
21
from folium.vector_layers import PolyLine, Polygon, Circle
22
from folium.plugins import MarkerCluster, HeatMap
23
```
24
25
## Basic Usage
26
27
```python
28
import folium
29
import numpy as np
30
31
# Create a basic map
32
map = folium.Map(
33
location=[45.5236, -122.6750], # Portland, OR
34
zoom_start=13,
35
tiles='OpenStreetMap'
36
)
37
38
# Add a simple marker
39
folium.Marker(
40
[45.5244, -122.6699],
41
popup='Downtown Portland',
42
tooltip='Click me!',
43
icon=folium.Icon(color='red', icon='info-sign')
44
).add_to(map)
45
46
# Add a circle
47
folium.Circle(
48
location=[45.5236, -122.6750],
49
radius=300,
50
popup='300m radius',
51
color='blue',
52
fill=True,
53
fillColor='lightblue'
54
).add_to(map)
55
56
# Display map (in Jupyter) or save
57
map.save('my_map.html')
58
```
59
60
## Architecture
61
62
Folium is built around a hierarchical component system:
63
64
- **Map**: The root container managing canvas, layers, and overall layout
65
- **Layers**: Raster (tiles) and vector (shapes) data layers
66
- **Features**: Interactive elements like markers, popups, and data visualizations
67
- **Controls**: UI elements for layer management and user interaction
68
- **Plugins**: Extended functionality through 40 specialized plugins
69
70
This design allows every visual element to be customized and provides seamless integration with Python data science libraries including NumPy, pandas, GeoPandas, and Jupyter notebooks.
71
72
## Capabilities
73
74
### Core Mapping
75
76
The fundamental Map class and essential mapping components including tile layers, basic markers, popups, and layer management controls.
77
78
```python { .api }
79
class Map:
80
def __init__(
81
self,
82
location=None,
83
width='100%',
84
height='100%',
85
left='0%',
86
top='0%',
87
position='relative',
88
tiles='OpenStreetMap',
89
attr=None,
90
min_zoom=0,
91
max_zoom=18,
92
zoom_start=10,
93
min_lat=-90,
94
max_lat=90,
95
min_lon=-180,
96
max_lon=180,
97
max_bounds=False,
98
crs='EPSG3857',
99
control_scale=False,
100
prefer_canvas=False,
101
no_touch=False,
102
disable_3d=False,
103
png_enabled=False,
104
zoom_control=True,
105
**kwargs
106
): ...
107
108
class Marker:
109
def __init__(
110
self,
111
location=None,
112
tooltip=None,
113
popup=None,
114
icon=None,
115
draggable=False,
116
**kwargs
117
): ...
118
119
class TileLayer:
120
def __init__(
121
self,
122
tiles='OpenStreetMap',
123
min_zoom=0,
124
max_zoom=18,
125
max_native_zoom=None,
126
attr=None,
127
name=None,
128
overlay=False,
129
control=True,
130
show=True,
131
**kwargs
132
): ...
133
```
134
135
[Core Mapping](./core-mapping.md)
136
137
### Data Visualization
138
139
Advanced data visualization capabilities including GeoJSON rendering, choropleth maps, and integration with Vega/Vega-Lite for embedded charts.
140
141
```python { .api }
142
class GeoJson:
143
def __init__(
144
self,
145
data,
146
style_function=None,
147
highlight_function=None,
148
name=None,
149
overlay=True,
150
control=True,
151
show=True,
152
smooth_factor=1.0,
153
tooltip=None,
154
popup=None,
155
marker=None,
156
**kwargs
157
): ...
158
159
class Choropleth:
160
def __init__(
161
self,
162
geo_data,
163
data=None,
164
columns=None,
165
key_on=None,
166
bins=6,
167
fill_color='blue',
168
nan_fill_color='black',
169
fill_opacity=0.7,
170
nan_fill_opacity=0.4,
171
line_color='black',
172
line_weight=1,
173
line_opacity=1,
174
name=None,
175
legend_name='',
176
overlay=True,
177
control=True,
178
show=True,
179
topojson=None,
180
smooth_factor=1.0,
181
highlight=False,
182
**kwargs
183
): ...
184
```
185
186
[Data Visualization](./data-visualization.md)
187
188
### Vector Layers
189
190
Geometric shapes and paths including polylines, polygons, circles, and rectangles with customizable styling and interactive features.
191
192
```python { .api }
193
class PolyLine:
194
def __init__(
195
self,
196
locations,
197
popup=None,
198
tooltip=None,
199
smooth_factor=1.0,
200
no_clip=False,
201
**kwargs
202
): ...
203
204
class Polygon:
205
def __init__(
206
self,
207
locations,
208
popup=None,
209
tooltip=None,
210
**kwargs
211
): ...
212
213
class Circle:
214
def __init__(
215
self,
216
location=None,
217
radius=10,
218
popup=None,
219
tooltip=None,
220
**kwargs
221
): ...
222
```
223
224
[Vector Layers](./vector-layers.md)
225
226
### Interactive Features
227
228
User interaction components including click handlers, custom controls, and specialized marker types for enhanced map interactivity.
229
230
```python { .api }
231
class ClickForMarker:
232
def __init__(self, popup=None): ...
233
234
class ClickForLatLng:
235
def __init__(self, format_str=None, alert=False): ...
236
237
class Control:
238
def __init__(self, position='topright'): ...
239
```
240
241
[Interactive Features](./interactive-features.md)
242
243
### Plugins
244
245
Extensive plugin ecosystem providing specialized functionality including clustering, heatmaps, drawing tools, temporal visualizations, and advanced controls.
246
247
```python { .api }
248
class MarkerCluster:
249
def __init__(
250
self,
251
locations=None,
252
popups=None,
253
tooltips=None,
254
icons=None,
255
name=None,
256
overlay=True,
257
control=True,
258
show=True,
259
icon_create_function=None,
260
options=None
261
): ...
262
263
class HeatMap:
264
def __init__(
265
self,
266
data,
267
name=None,
268
min_opacity=0.4,
269
max_zoom=18,
270
max_val=1.0,
271
radius=25,
272
blur=15,
273
gradient=None,
274
overlay=True,
275
control=True,
276
show=True
277
): ...
278
279
class Draw:
280
def __init__(
281
self,
282
export=False,
283
filename='data.geojson',
284
position='topleft',
285
draw_options=None,
286
edit_options=None
287
): ...
288
```
289
290
[Plugins](./plugins.md)
291
292
### Utilities and Styling
293
294
Helper functions, color maps, and JavaScript integration utilities for advanced customization and programmatic map control.
295
296
```python { .api }
297
class JsCode:
298
def __init__(self, js_code): ...
299
300
class ColorMap:
301
def __init__(self, colors, index=None, vmin=0, vmax=1, caption=''): ...
302
303
class LinearColormap:
304
def __init__(
305
self,
306
colors,
307
index=None,
308
vmin=0,
309
vmax=1,
310
caption=''
311
): ...
312
```
313
314
[Utilities and Styling](./utilities-styling.md)
315
316
## Types
317
318
```python { .api }
319
# Location types
320
Location = Union[Tuple[float, float], List[float]]
321
Locations = Union[List[Location], Tuple[Location, ...]]
322
323
# Bounds type
324
Bounds = Union[List[List[float]], Tuple[Tuple[float, float], Tuple[float, float]]]
325
326
# Style function type
327
StyleFunction = Callable[[Dict], Dict[str, Any]]
328
329
# GeoJSON-like data
330
GeoJsonData = Union[Dict, str, FeatureCollection]
331
```